# 4 个 bat 使用说明

项目根目录下 4 个双击即用的批处理，按用途分两类：

| 我想做的事 | 用哪个 bat |
| --- | --- |
| 出小程序发行版，并自动在微信开发者工具里打开 | `publish-sit.bat`（测试）/ `publish-prod.bat`（生产） |
| 在 HBuilderX 里「运行 → 运行到小程序模拟器」调试 | 先切环境：`switch-sit.bat` / `switch-prod.bat` |

> 一句话区分：`publish-*` 产出 `unpackage/dist/build/mp-weixin` 发行产物，编译期 appid 由脚本注入，**不改仓库里的任何文件**；`switch-*` 改的是 HBuilderX 的编译输入 `manifest.json`，供 GUI 编译/调试用。

---

## 1. 一次性前提

1. Node.js（命令行 `node -v` 可用）
2. HBuilderX（提供命令行 `cli.exe`）
3. 微信开发者工具，且 **设置 → 安全设置 → 服务端口 = 开启**（不开时 `cli.bat open` 会失败，脚本会降级提示你手动导入）

**工具路径不需要配置**，脚本按顺序自动查找，命中后把所在目录加入本次进程的 `PATH`（便于按名字直接调用）：

1. 环境变量 `HBUILDERX_CLI` / `WX_DEVTOOLS_CLI`
2. 系统 `PATH`
3. 常见安装目录（`Program Files`、`Program Files (x86)`、用户目录、桌面、下载、各磁盘常见软件目录…）
4. 磁盘浅层扫描（≤2 层，只扫本地固定磁盘，跳过系统目录）

找不到时直接报错并给出办法：

```bat
set PATH=%PATH%;<HBuilderX 或 微信开发者工具 的安装目录>
set HBUILDERX_CLI=<HBuilderX cli.exe 完整路径>
set WX_DEVTOOLS_CLI=<微信开发者工具 cli.bat 完整路径>
```

---

## 2. publish-sit.bat / publish-prod.bat

双击 = 发行并自动打开。实际执行 4 步：

| 步骤 | 做什么 | 具体命令 |
| --- | --- | --- |
| 0 | 生成 `manifest.json`（模板 `manifest.json.demo` + 该环境 appid） | 内置逻辑 |
| 1 | HBuilderX CLI 发行编译 | `cli.exe publish --platform mp-weixin --project <项目根>` |
| 2 | 回写产物 appid（兜底校正） | 写入 `unpackage/dist/build/mp-weixin/project.config.json` |
| 3 | 微信开发者工具 CLI 打开产物 | `cli.bat open --project <产物目录>` |

- 发行产物：`unpackage/dist/build/mp-weixin`
- 编译日志在 **HBuilderX 控制台**里看
- 任一步失败，窗口会打印 `[FAILED] ...`（退出码非 0）

### 可加的参数（`%*` 原样传给 `scripts/publish.js`）

| 参数 | 作用 |
| --- | --- |
| `--dry-run` | 只打印将要执行的命令，不做任何写操作 |
| `--no-open` | 只编译，不打开微信开发者工具（此种情况不要求安装开发者工具） |
| `--no-gen` | 跳过生成 `manifest.json`（要求它已存在；适合你手工维护 manifest 的场景） |
| 其他参数 | 原样透传给 HBuilderX cli |

用法示例（在命令行窗口里）：

```bat
publish-sit.bat --dry-run
publish-prod.bat --no-open
```

等价命令：`npm run release:sit` / `npm run release:prod` / `node scripts/publish.js sit`

---

## 3. switch-sit.bat / switch-prod.bat

双击 = 按该环境重新生成 `manifest.json`（`manifest.json.demo` + 该环境 appid）。

- 等价命令：`npm run env:sit` / `npm run env:prod` / `node scripts/set-env.js sit`
- **切完必须做两件事**：① 在 HBuilderX 里重新编译一次；② 在微信开发者工具里重新打开该项目（appid 变更需重开）
- 幂等：内容已一致时提示「无需重写」，可放心重复双击
- 适用场景：在 HBuilderX GUI 里直接运行/调试（编译期 appid 取自 `manifest.json`），或需要出 App 包（顶层 DCloud appid）

### 两个环境的取值

| 环境 | 小程序 appid（`mp-weixin.appid`） | DCloud appid（顶层） | 接口地址 |
| --- | --- | --- | --- |
| sit | `wx7e443c60d08449de` | `__UNI__3D0C5FE` | `https://sit.tohours.com/crmeb/front` |
| prod | `wx15d029cdf2e92a9f` | `__UNI__CE0C605` | `https://acmall.bluedeer.com.cn/crmeb/front` |

数据源：`config/env/sit.js`、`config/env/prod.js`（唯一数据源，改这两处即可，两个文件键名保持一致）。

---

## 4. 为什么跑完 git 是干净的

`manifest.json` 是**生成物**，`project.config.json` 与 `unpackage/` 已忽略：

```
manifest.json.demo（入库，模板） ──注入环境 appid──▶ manifest.json（已忽略，不入库）
```

所以发行、切环境都不会产生 git 改动，`git status` 只会有你自己改的源码。

两点注意：

1. 新 clone 的机器**没有 `manifest.json`，HBuilderX 打不开项目** —— 先跑一次 `switch-sit.bat`（或任意 `publish-*.bat`）把它生成出来。
2. 在 HBuilderX GUI 里直接改的 manifest 配置落在**生成物**上，下次生成会被模板内容覆盖（脚本会打印警告）。需要长期保留的改动，请写进 `manifest.json.demo`。

---

## 5. 接口地址为什么自动对得上

`config/env/index.js` 的识别顺序：手动 `OVERRIDE_ENV` > 小程序 appid 自动识别 > H5 域名识别 > 默认 prod，对外导出 `ENV_NAME` / `IS_SIT` / `IS_PROD`。

也就是「用哪个 appid 编译」就等于「用哪套接口」，不会出现接口与环境错配 —— 你只需要选对 bat。

---

## 6. 常见问题

| 现象 | 处理 |
| --- | --- |
| 窗口报 `'…' is not recognized as an internal or external command` 且带中文乱码 | bat 内混用 UTF-8 中文时，cmd 按代码页解析会错位。现在 4 个 bat **全部是 ASCII**，中文提示由 Node 打印。自己改 bat 时不要加中文，要加就用 Node 输出 |
| `未找到 HBuilderX 命令行 cli.exe` / `未找到微信开发者工具命令行 cli.bat` | 按报错里的两种办法处理：加 `PATH` 或设对应环境变量（见第 1 节） |
| 自动打开失败，提示未开启服务端口 | 开发者工具 → 设置 → 安全设置 → 打开服务端口；或手动「导入项目」选 `unpackage\dist\build\mp-weixin` |
| 开发者工具里 appid 还是旧的 | appid 变更后需要在工具里**重新打开**该项目 |
| `--no-gen 需要 manifest.json 已存在` | 先跑一次 `switch-*.bat`，或去掉 `--no-gen` |
| `cli.exe 退出码 …` | 编译失败，看 HBuilderX 控制台里的具体报错 |

---

## 7. 附注

- 4 个 bat 都会先 `cd /d "%~dp0"`，所以在任意目录双击或命令行调用都不会跑错位置；末尾 `pause` 方便双击后查看输出。
- 微信开发者工具生成的 `project.private.config.json` 属于纯本地工具偏好，不参与编译，已从版本库移除并加入 `.gitignore`。