weicw-dshsa
79420e28f6
- 集成分支 feat/cli-migration 整体并入 master；此后 HBuilderX 不再是本仓库的构建方式 - 7 张票全部 resolved（.scratch/uniapp-cli/）；产物 app.json / 分包 / tabBar / appid 与迁移前逐项一致，业务代码零改动 - 产物：pnpm build:mp-weixin → dist/build/mp-weixin，用微信开发者工具导入该目录 - 回滚：git revert -m 1 <本合并提交>；口径与取舍见 docs/adr/0009-uniapp-built-by-cli-not-hbuilderx.md - 未做：微信开发者工具人工冒烟（清单见 .scratch/uniapp-cli/issues/03-artifact-parity-and-smoke-checklist.md）
tuanwei-uniapp
团员管理系统移动端（uni-app + Vue 3）。本仓库是标准 uni-app Vite CLI 工程：命令行即可构建，不需要 HBuilderX。
环境要求
| 依赖 | 实测版本 | 说明 |
|---|---|---|
| Node.js | v22.23.3 | 构建用 |
| pnpm | v12.11.2 | 唯一包管理器，不要用 npm / yarn |
| 微信开发者工具 | — | 只用来预览产物，不参与构建 |
npm 源使用官方 registry.npmjs.org。
快速开始
三条命令都在仓库根目录执行：
# 1. 安装依赖
pnpm install
# 2. 日常开发：watch 构建，不退出；产物持续写入 dist/dev/mp-weixin
pnpm dev:mp-weixin
# 3. 发布构建：一次性产出静态快照到 dist/build/mp-weixin
pnpm build:mp-weixin
package.json 里只有四条 scripts：dev:h5 / build:h5 / dev:mp-weixin / build:mp-weixin。
mp-weixin 是本仓库唯一承诺的平台；h5 两条只是顺带保留，不作保证。
产物路径与微信开发者工具的导入目录
| 命令 | 产物目录 | 什么时候用 |
|---|---|---|
pnpm dev:mp-weixin |
dist/dev/mp-weixin |
日常开发：改源码自动重编译 |
pnpm build:mp-weixin |
dist/build/mp-weixin |
发布 / 上传前：一次性静态构建 |
产物路径由 uni CLI 固定为 dist/<dev|build>/<平台>，dist/ 已在 .gitignore 中，不会进版本库。
微信开发者工具 → 「导入项目」→ 目录选 dist/dev/mp-weixin（开发）或 dist/build/mp-weixin（发布构建）。
- 要导入的是产物目录本身，也就是
app.json、project.config.json所在的那一层； 不要再往外选到仓库根目录，也不要再往里选一层。 - appid 不用手填：
project.config.json由编译器生成，appid 取自src/manifest.json的mp-weixin.appid（wxf7ee9cd5801bf7a6），项目名取自manifest.json的name。 - 开发时先起
pnpm dev:mp-weixin（它进入 watch、不退出），再导入dist/dev/mp-weixin。
目录结构
.
├── index.html # H5 入口（仅 h5 构建使用）
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml # pnpm 12 的 allowBuilds 白名单，见「常见问题」
├── shims-uni.d.ts
├── vite.config.js
├── src/ # uni-app 源码根（官方 src/ 布局）
│ ├── App.vue main.js manifest.json pages.json uni.scss
│ ├── pages/ packageMine/ components/ utils/ static/ uni_modules/
│ └── uni.promisify.adaptor.js
└── dist/ # 构建产物（git 忽略）
@/ 别名指向 src/。不要把源码挪回仓库根目录：vite.config.js 的 root / build.outDir
是 uni-app 官方明确不支持的，UNI_INPUT_DIR 是文档不背书的源码后门 —— 官方 src/ 布局是唯一受支持的形状。
为什么不再需要 HBuilderX
改造前这是 HBuilderX 可视化工程：构建只能在 IDE 里点菜单完成，命令行里没有等价入口，
无法在 CI、脚本或别人机器上复现构建结果。现在整个构建流程就是 pnpm install + pnpm build:mp-weixin，
退出码 0、产物在 dist/build/mp-weixin，任何人在命令行都能复现。
改造的背景、布局 / 版本 / 包管理器的取舍、以及「绝不用 @dcloudio 的 latest tag」这条硬约束，
记录在工作区仓库（本仓库之外）的 docs/adr/0009-uniapp-built-by-cli-not-hbuilderx.md。
.gitignore 里保留的 .hbuilderx/ 与 unpackage/ 只是为了不让旧的 IDE 配置与旧产物被误提交，
它们不是构建路径，与现在的构建无关。
版本口径（硬约束）
- 五个编译器包（
@dcloudio/uni-app/uni-components/uni-h5/uni-mp-weixin/vite-plugin-uni） 必须同一版本，按精确版本号 pin。具体值以package.json为准。 @dcloudio/types不受上面这条约束：它是 IDE 用的类型定义，单独窄化到3.4.31（@dcloudio/uni-app的 strict peer，不影响构建）。- 绝不用
@dcloudio包的latesttag。latest指向 Vue 2 线 （实测npm view @dcloudio/uni-app dist-tags→latest: 2.0.2-5020620260917001）， 与 Vue 3 线同日期后缀、极易看错；Vue 3 线在精确版本号上（vue3tag 只给 alpha）。 vite钉精确5.2.8：@dcloudio/vite-plugin-uni的 peer 要求精确版本，不要写^。- 升级编译器走官方
npx @dcloudio/uvm（一次改全套），不要手改单个@dcloudio/*版本。
常见问题
pnpm install 报 ERR_PNPM_IGNORED_BUILDS、退出码非 0
pnpm 12 下依赖的构建脚本默认不执行，且 strictDepBuilds 默认为 true，
会把「被跳过的依赖构建脚本」判成安装失败。本项目已在 pnpm-workspace.yaml 里用 allowBuilds
显式复核（esbuild / @parcel/watcher / core-js / core-js-pure），之后
pnpm install --frozen-lockfile 退出码 0（node_modules/.modules.yaml 里记着 allowBuilds、pendingBuilds 为空）。
这里只写实测到的事实（pnpm v12.11.2）：生效的键是 pnpm-workspace.yaml 的 allowBuilds；
把 onlyBuiltDependencies 写进 package.json 的 pnpm 字段，pnpm 12 会明确打印
The "pnpm" field in package.json is no longer read by pnpm（并列出被忽略的键名），无效；
写在 pnpm-workspace.yaml 里同样不生效（既不告警、也不执行那批构建脚本）。
这个键究竟从哪个版本起失效，本仓库没有逐版本复现，不下版本学结论。
构建输出一堆 sass @import / legacy-js-api 弃用告警
这是既有 scss 写法与新版 dart-sass 的差异，告警不影响退出码，也不影响产物。
H5
pnpm dev:h5 / pnpm build:h5 仍在 package.json 里，但不在承诺范围内。