# 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 包的 latest tag。 latest 指向 Vue 2 线（实测 npm view @dcloudio/uni-app dist-tags → latest: 2.0.2-5020620260917001），与 Vue 3 线同日期后缀、极易看错；Vue 3 线在精确版本号上（vue3 tag 只给 alpha）。
vite 钉精确 5.2.8：@dcloudio/vite-plugin-uni 的 peer 要求精确版本，不要写 ^。
升级编译器走官方 npx @dcloudio/uvm（一次改全套），不要手改单个 @dcloudio/* 版本。

常见问题

pnpm install 报 ERR_PNPM_IGNORED_BUILDS、退出码非 0

pnpm v11 起依赖的构建脚本默认不执行，且 strictDepBuilds 默认为 true，会把「被跳过的依赖构建脚本」判成安装失败。本项目已在 pnpm-workspace.yaml 里用 allowBuilds 显式复核（esbuild / @parcel/watcher / core-js / core-js-pure）。注意旧的 onlyBuiltDependencies 在 pnpm v11 起已废弃：写在 package.json 的 pnpm 字段里会被 pnpm 12 明确告知「不再读取」，无效。

构建输出一堆 sass @import / legacy-js-api 弃用告警

这是既有 scss 写法与新版 dart-sass 的差异，告警不影响退出码，也不影响产物。

pnpm dev:h5 / pnpm build:h5 仍在 package.json 里，但不在承诺范围内。

README.md Unescape Escape

tuanwei-uniapp

环境要求

快速开始

产物路径与微信开发者工具的导入目录

目录结构

为什么不再需要 HBuilderX

版本口径（硬约束）

常见问题

README.md