weicw-dshsa
1d16e94c4e
- package.json 增 dev:mp-weixin:win / build:mp-weixin:win：用 UNI_OUTPUT_DIR 把产物写到
${WIN_OUT_DIR:-/mnt/d/tuanwei-dev}/<dev|build>/mp-weixin，供 WSL 编译 + Windows 侧开发者工具导入
- README 补「在 WSL 里开发」一节：分工、产物目录对照、WIN_OUT_DIR 覆盖与实测边界
- 人工冒烟回执：编译后导入微信开发者工具验证通过
157 lines
8.4 KiB
Markdown
157 lines
8.4 KiB
Markdown
# 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`。
|
||
|
||
## 快速开始
|
||
|
||
三条命令都在**仓库根目录**执行：
|
||
|
||
```bash
|
||
# 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`，
|
||
外加两条 WSL 专用变体 `dev:mp-weixin:win` / `build:mp-weixin:win`（见「在 WSL 里开发」一节）。
|
||
**`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`。
|
||
- 上面两个目录是**在 WSL 之外的机器上编译**时的位置。在 WSL 里开发请走下一节，产物不落在 `dist/`。
|
||
|
||
## 在 WSL 里开发：开发者工具跑在 Windows 侧
|
||
|
||
微信开发者工具只有 Windows / macOS 版，**没有 Linux 版，装不进 WSL**。
|
||
（这台机器的 WSLg 是好的，Linux GUI 程序能显示；但开发者工具本身没有 Linux 构建，用不上。）
|
||
所以分工是「WSL 编译、Windows 运行工具」，两边靠一个落在 **Windows 盘上**的产物目录对接：
|
||
|
||
```bash
|
||
# WSL 侧：产物直接写到 Windows 的 D 盘，watch 常驻不退出
|
||
pnpm dev:mp-weixin:win
|
||
```
|
||
|
||
然后在 Windows 侧打开微信开发者工具 → 「导入项目」→ 目录选 `D:\tuanwei-dev\dev\mp-weixin`。
|
||
|
||
| 命令 | 产物目录（WSL 视角） | Windows 视角 | 什么时候用 |
|
||
| --- | --- | --- | --- |
|
||
| `pnpm dev:mp-weixin:win` | `/mnt/d/tuanwei-dev/dev/mp-weixin` | `D:\tuanwei-dev\dev\mp-weixin` | 日常开发：watch |
|
||
| `pnpm build:mp-weixin:win` | `/mnt/d/tuanwei-dev/build/mp-weixin` | `D:\tuanwei-dev\build\mp-weixin` | 发布 / 上传前：一次性构建 |
|
||
|
||
`<dev|build>/mp-weixin` 这一层与仓库内的 `dist/<dev|build>/mp-weixin` **刻意同形**，
|
||
只是根从仓库内挪到了 Windows 盘上。换盘符或换目录就设 `WIN_OUT_DIR`：
|
||
|
||
```bash
|
||
WIN_OUT_DIR=/mnt/e/tuanwei-dev pnpm dev:mp-weixin:win
|
||
```
|
||
|
||
`WIN_OUT_DIR` 指向的目录**不存在也可以**：编译器会连多级父目录一起建（实测 `/mnt/d/__probe/deep/nested` 一次跑通，无需先 `mkdir`）。
|
||
|
||
**为什么不把产物留在 `dist/`、直接让工具导入 `\\wsl.localhost\...`？** 那条路本仓库没实测，
|
||
原理上要走 9p 网络路径；本方案不依赖它 —— 产物落在本地 NTFS，工具看到的就是一个普通 Windows 目录。
|
||
|
||
实测到的事实（WSL2 + Debian 13，2026-10-15）：
|
||
|
||
- `dev:mp-weixin:win` 起 watch 后把首次全量产物写进了 `/mnt/d/tuanwei-dev/dev/mp-weixin`；
|
||
- 改一次 `src/main.js`，产物 `app.js` **约 3 秒后**重编译落盘（1364 → 1397 字节，标记命中 1 次）。
|
||
依据是 `@dcloudio/vite-plugin-uni` 的 `configResolved/env.js` 只在**未设置**时才兜底默认目录，
|
||
所以 `UNI_OUTPUT_DIR` 是它认的出口，dev 与 build 两条路径都生效。
|
||
- **未实测**：开发者工具那侧收到新产物后是否**自动刷新界面** —— 这要工具跑起来才验得了，WSL 里验不了。
|
||
若没自动刷新，点一下工具里的「编译」即可。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── 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` 包的 `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 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` 里，但不在承诺范围内。
|