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

docs: 修正 §10.9 预览命令的建议——它是必填项，不是留空 

上一条把预览命令写成「留空并取消勾选」，但 UI 里勾选启用预览构建后该字段为必需。
预览命令改用 npx wrangler dev --ip 0.0.0.0 --port 8787（wrangler 3.114.17 无
preview 子命令，dev 才有 --ip/--port；8787 是 dev 默认端口）。

同时澄清构建命令 ≠ 部署命令：部署命令（必需）保持 npx wrangler deploy 不动，
把 deploy 塞进可选的构建命令才是错的。补一句预览环境没有 BACKEND_ORIGINS_JSON，
所以预览只能验证 Worker 能拉起与路由表生效，后端转发只能看生产。

另补：根目录在折叠的「高级设置」里，设了之后三个命令都在 cloudflare-worker/ 下执行。

GATE-DOCS 6/6（114 行号锚点 / 252 节引用 / 469 路径引用）。
This commit is contained in:
anonsaber 2026-09-30 17:10:35 +08:00
parent 8d73b73fb5
commit e853032445
1 changed files with 13 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
docs/deployment.md
View File

@ -858,22 +858,27 @@ 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` | `node -e "process.exit(0)"` |
| **预览命令** | `npx wrangler preview` | 留空，并**取消勾选「启用预览构建」** | | **部署命令**（必需） | `npx wrangler deploy` | **保持不动** |
| **预览命令**（勾选「启用预览构建」后为必需） | `npx wrangler preview` | `npx wrangler dev --ip 0.0.0.0 --port 8787` |
四条理由（全部实测）： 四条理由（全部实测）：
1. **根目录是决定性的一步。** 本仓库根是 Rust 后端，Worker 在 `cloudflare-worker/` 子目录。 1. **根目录是决定性的一步。** 本仓库根是 Rust 后端，Worker 在 `cloudflare-worker/` 子目录。
不设根目录时 Cloudflare 在仓库根跑 wrangler，那里没有 `wrangler.toml`，构建直接失败。 不设根目录时 Cloudflare 在仓库根跑 wrangler，那里没有 `wrangler.toml`，构建直接失败。
「高级设置」默认是折叠的——**展开它**，根目录就是里面的字段；设了之后，
构建 / 部署 / 预览三个命令都在 `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. **构建命令别填 `npx wrangler deploy`。** Cloudflare 在构建之后**自己**会跑 wrangler deploy， 3. **构建命令 ≠ 部署命令。** 构建命令负责「把源码变成可部署产物」，本项目是纯 JS、无编译步骤，
再在构建命令里写一遍等于部署两次，而且那次拿不到 Cloudflare 注入的部署上下文。 填一个 no-op 即可；`npx wrangler deploy` 属于**部署命令**字段（必需，保持默认）。
本项目无构建步骤（纯 JS，无需编译），构建命令填一个 no-op 即可。 把 deploy 塞进构建命令，等于在错误的阶段执行部署。
4. **`wrangler preview` 子命令不存在。** wrangler 3.114.17 的子命令只有 `dev` / `deploy` / 4. **`wrangler preview` 子命令不存在。** wrangler 3.114.17 的子命令只有 `dev` / `deploy` /
`deployments`，填了必然构建失败。更关键的是预览环境没有 `BACKEND_ORIGINS_JSON` `deployments`，默认那个值填了必然失败。预览命令填 `npx wrangler dev --ip 0.0.0.0 --port 8787`
（secret 只存在于你的账号配置里，仓库里不该有 `.dev.vars`），预览出来也只有 （8787 是 `wrangler dev` 的默认端口，`--ip 0.0.0.0` 让 Cloudflare 的预览代理能连进来）。
`no-backends` / 503——**预览对这个 Worker 没有意义，直接关掉**。 ⚠️ 预览环境**没有** `BACKEND_ORIGINS_JSON`（secret 只存在于你的账号配置，仓库里不该有
`.dev.vars`），所以预览只能验证「Worker 能被拉起 + 路由表生效 + `/healthz` 返回 200 但
`status` 是 `no-backends`」，**不能**验证后端转发。后端转发只能看生产。
**Node 版本**用 22 即可（实测 Node 22.23.3 全绿）。npm 版本不必手动固定： **Node 版本**用 22 即可（实测 Node 22.23.3 全绿）。npm 版本不必手动固定：
仓库已提交 cloudflare-worker 下的 lockfile，有 lockfile 时 Cloudflare 跑 `npm ci`， 仓库已提交 cloudflare-worker 下的 lockfile，有 lockfile 时 Cloudflare 跑 `npm ci`，