Public
/
MessageWeave
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: §10.9 构建命令改为 npm ci + npm test 

Cloudflare Git 集成的默认安装步骤实测用的是 bun install（日志
'Installing project dependencies: bun install'），bun 不读 npm 锁文件、
自己重新解析依赖（'Saved lockfile'），仓库里提交的锁文件被完全绕过。
只填 no-op 构建命令意味着 CI 装的是 bun 解析出来的版本树，而不是我们
锁定的 wrangler 4.144.0。构建命令改成显式 npm ci 后由 npm ci 删掉
node_modules 再严格按锁文件重装；项目无编译步骤，顺带跑一遍 npm test
当门禁。

同时把 Node 版本说明改为实测值（CI 给的是 nodejs@24.18.0），并记录
wrangler 4 与 3 一样按 wrangler.toml 的 name 部署。
This commit is contained in:
anonsaber 2026-09-30 18:08:57 +08:00
parent 7737693c2b
commit 7aa880c429
1 changed files with 15 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/deployment.md
View File

@ -858,7 +858,7 @@ Git 集成**必须改的四个字段**（Cloudflare 的默认值对不上本仓
|---|---|---| |---|---|---|
| **根目录 / Root directory**（在「高级设置」里） | 仓库根 | `cloudflare-worker` | | **根目录 / Root directory**（在「高级设置」里） | 仓库根 | `cloudflare-worker` |
| 应用名 | UI 里自填的名字 | 与 `wrangler.toml` 的 `name` 一致，否则 wrangler 会部署成**另一个名字** | | 应用名 | UI 里自填的名字 | 与 `wrangler.toml` 的 `name` 一致，否则 wrangler 会部署成**另一个名字** |
| **构建命令**（可选） | `npx wrangler deploy` | `node -e "process.exit(0)"` | | **构建命令**（可选） | `npx wrangler deploy` | `npm ci --no-audit --no-fund && npm test` |
| **部署命令**（必需） | `npx wrangler deploy` | **保持不动** | | **部署命令**（必需） | `npx wrangler deploy` | **保持不动** |
| **预览命令**（勾选「启用预览构建」后为必需） | `npx wrangler preview` | `npx wrangler dev --ip 0.0.0.0 --port 8787` | | **预览命令**（勾选「启用预览构建」后为必需） | `npx wrangler preview` | `npx wrangler dev --ip 0.0.0.0 --port 8787` |
@ -870,20 +870,26 @@ Git 集成**必须改的四个字段**（Cloudflare 的默认值对不上本仓
构建 / 部署 / 预览三个命令都在 `cloudflare-worker/` 里执行。 构建 / 部署 / 预览三个命令都在 `cloudflare-worker/` 里执行。
2. **应用名要跟 `wrangler.toml` 的 `name` 对齐。** wrangler 部署用的是 toml 里的 `name`， 2. **应用名要跟 `wrangler.toml` 的 `name` 对齐。** wrangler 部署用的是 toml 里的 `name`，
UI 上的名字不一致时，你部署出去的是 toml 里那个名字的 Worker，UI 上那个应用永远等不到部署。 UI 上的名字不一致时，你部署出去的是 toml 里那个名字的 Worker，UI 上那个应用永远等不到部署。
3. **构建命令 ≠ 部署命令。** 构建命令负责「把源码变成可部署产物」，本项目是纯 JS、无编译步骤， 3. **构建命令里必须显式 `npm ci`，不能只填 no-op。** Cloudflare 的默认安装步骤实测用的是
填一个 no-op 即可；`npx wrangler deploy` 属于**部署命令**字段（必需，保持默认）。 `bun install`（CI 日志 `Resolved, downloaded and extracted [334]`、`Saved lockfile`），而
把 deploy 塞进构建命令，等于在错误的阶段执行部署。 bun 不读 npm 的锁文件——那句 `Saved lockfile` 说明是 bun 自己生成了锁文件、按自己的解析
4. **`wrangler preview` 子命令不存在。** wrangler 3.114.17 的子命令只有 `dev` / `deploy` / 结果装依赖，仓库里已提交的锁文件被完全绕过了。所以构建命令里自己跑一次 `npm ci` 才有
意义：它会删掉 node_modules、严格按锁文件重装。项目无编译步骤，`npm test` 顺手做一遍
当门禁。`npx wrangler deploy` 属于**部署命令**字段（必需，保持默认），把 deploy 塞进
构建命令才是错的。
4. **`wrangler preview` 子命令不存在。** wrangler 4.144.0 的子命令只有 `dev` / `deploy` /
`deployments`，默认那个值填了必然失败。预览命令填 `npx wrangler dev --ip 0.0.0.0 --port 8787` `deployments`，默认那个值填了必然失败。预览命令填 `npx wrangler dev --ip 0.0.0.0 --port 8787`
（8787 是 `wrangler dev` 的默认端口，`--ip 0.0.0.0` 让 Cloudflare 的预览代理能连进来）。 （8787 是 `wrangler dev` 的默认端口，`--ip 0.0.0.0` 让 Cloudflare 的预览代理能连进来）。
⚠️ 预览环境**没有** `BACKEND_ORIGINS_JSON`（secret 只存在于你的账号配置，仓库里不该有 ⚠️ 预览环境**没有** `BACKEND_ORIGINS_JSON`（secret 只存在于你的账号配置，仓库里不该有
`.dev.vars`），所以预览只能验证「Worker 能被拉起 + 路由表生效 + `/healthz` 返回 200 但 `.dev.vars`），所以预览只能验证「Worker 能被拉起 + 路由表生效 + `/healthz` 返回 200 但
`status` 是 `no-backends`」，**不能**验证后端转发。后端转发只能看生产。 `status` 是 `no-backends`」，**不能**验证后端转发。后端转发只能看生产。
**Node 版本**用 22 即可（实测 Node 22.23.3 全绿）。npm 版本不必手动固定： **Node 版本不用管。** Cloudflare 环境实测给的是 `nodejs@24.18.0`，本地在 Node 24.21.0 与
仓库已提交 cloudflare-worker 下的 lockfile，有 lockfile 时 Cloudflare 跑 `npm ci`， 22.23.3 上都验过（32/32 通过）。**wrangler 已升到 4.144.0**：3.114.17 在 CI 里会打印
精确复现 wrangler 3.114.17，构建可复现。 `The version of Wrangler you are using is now out-of-date … to prevent critical errors`，
（此前没有 lockfile，`wrangler@^3.57.0` 是浮动范围，每次 CI 可能解析到不同小版本。） 4.144.0 在该警告消失，且 wrangler 4 与 wrangler 3 一样会按 `wrangler.toml` 的 `name`
部署（toml 里的 `name = "messageweave-lb"` 保持不变即可）。lockfile 锁定 wrangler 4.144.0，
由构建命令里的 `npm ci` 保证 CI 拿到的是同一个版本。
**secret 仍在网页上配**：Workers & Pages → 你的应用 → Settings → Variables & Secrets → **secret 仍在网页上配**：Workers & Pages → 你的应用 → Settings → Variables & Secrets →
**Encrypt**（不是 Plain Text）→ 加 `BACKEND_ORIGINS_JSON`。`wrangler.toml` 的 `vars = {}` **Encrypt**（不是 Plain Text）→ 加 `BACKEND_ORIGINS_JSON`。`wrangler.toml` 的 `vars = {}`