部署、资源与域名
根据发布失败阶段恢复部署，核对 Cloudflare 资源、环境变量、域名和线上内容。
部署不是一个整体事务。脚本最后失败，不代表前面的远程操作没有发生。排查前保留第一条错误、失败阶段、代码版本和时间，再确认线上当前状态。
一、选对项目和命令
| 场景 | 命令 |
|---|---|
| 全新项目第一次创建远程 Worker 和资源 | npm run deploy:init |
| 已有 Worker 和完整远程绑定，发布后续修改 | npm run deploy:update |
| 绑定或更换正式域名 | npm run domain:set -- https://app.example.com |
命令属于初始化后的应用项目。默认模板没有 deploy:prod，也没有要求使用 wrangler --env production 的生产环境分支。.env.production 是部署脚本读取的变量文件，不等同于 Wrangler 的命名环境。
只看到 account_id 不能认定首次部署已经完成。这个字段可能在创建资源前就写入，必须继续核对 Worker 和资源。
二、先确认账户和资源归属
npx wrangler whoami
npm run doctor:remote核对当前身份是否能访问 wrangler.jsonc.account_id，以及配置中的 Worker、D1 ID、KV ID、R2 和 Queue 名称是否属于目标项目。
doctor:remote 主要验证本地生产配置、资源标识的填写和命名关系，以及账户可用性。它不会逐个证明远程 D1、KV、R2、Queue 都存在，也不会执行完整业务验证。资源不存在时，还应在对应账户的控制台核对实际资源。
CLI 创建的名称通常使用项目名前缀，例如 my-app-db。不要把模板默认名称当成必须存在的远程资源，更不要复制其他应用的数据库 ID 来让检查通过。
三、首次部署中途失败
先判断停在哪一步，再选择恢复方式：
| 失败位置 | 可能已完成的内容 | 下一步 |
|---|---|---|
| 配置交互或资源预检查 | 本地配置和 .env.production 可能已更新 | 修复配置，确认未创建远程资源后再执行首次部署 |
| 类型检查或构建 | 部分本地文件已修改，Worker 可能尚未发布 | 修复第一条代码或内容错误 |
| 创建资源或上传 Worker | 部分远程资源可能存在 | 逐项核对资源与配置，不要盲目再次创建 |
| 远程数据库初始化 | Worker 可能已上线，一个库可能已初始化 | 按数据库章节确认两个库的状态 |
| KV 同步 | Worker 和数据库可能已准备好 | 用同一版本内容恢复同步 |
| 页面健康检查 | 前面的部署可能已经完成 | 直接检查线上响应和 Worker 日志 |
首次部署先发布 Worker，再完成数据库与内容准备。只有等这些步骤全部成功后才适合开放业务流量。
如果 Worker、D1 和 KV 等绑定已经完整，修复故障后可使用更新流程完成发布。如果只创建了部分资源，应先确认归属和是否已有数据，再修复缺失配置，不要通过删除同名资源或清空 ID 强行重来。
详细流程见首次部署与后续更新。
四、更新部署在哪一步停止
当前 deploy:update 的主要顺序是：
核对账户、Worker、生产环境文件、主密钥和站点地址
→ doctor:remote → cf-typegen → verify
→ db:migrate:remote → 发布 Worker
→ kv:sync:remote → 页面健康检查如果 verify 失败，当前更新流程尚未执行后面的远程迁移和发布。先修复代码、类型、测试或构建，不应跳过验证直接发布。
如果远程迁移失败，前面的某些迁移可能已经完成。如果 Worker 上传失败，数据库可能已经更新。此时要保证旧 Worker 仍能使用现有结构，不能只回滚代码就认为数据库也恢复了。
如果 KV 同步或健康检查失败，新 Worker 可能已经在线。先查看部署版本和实际响应，再决定重跑更新还是修复具体阶段。
五、环境文件正确，线上仍提示缺少配置
检查的是哪一份文件、哪一个 Worker，以及修改后是否部署：
| 修改内容 | 必要后续操作 |
|---|---|
.env | 重启本地开发并验证，不会自动改变线上 |
.env.production | 执行更新部署，让变量进入 Worker |
config/ 或界面语言资源 | 重新构建并部署 |
| OAuth 或 Turnstile 平台设置 | 在平台保存并重新验证，若应用凭据变更还需部署 |
部署脚本会区分普通变量与 Secret。以 VITE_ 开头的变量可能进入浏览器产物，不能保存密钥。
空字符串不会作为新值写入远程 Worker，文件中缺少的远程 Secret 也不会因此自动删除。如果目的是停用旧集成，应按服务使用情况明确处理配置与远程 Secret，不能只把文件内容删空。
如果报 SAAS_SECRET must exist and match，检查 .env 与 .env.production 是否仍使用项目原始主密钥。不要为了让比较相等而同时生成新值，这可能导致已有资料无法解密。
Cloudflare 部署身份的 Token 属于工具凭据，不应放进应用的 .env.production，当前脚本会拒绝这类字段。
六、Binding 或 Durable Object 报错
先看错误发生在类型检查还是运行时：
- 类型缺失时，核对
wrangler.jsonc后执行npm run cf-typegen。 - 运行时找不到 Binding 时，检查已部署版本和真实绑定，生成类型不会创建远程资源。
- Queue 有消息但没有处理时，转到后台任务与统计检查三处名称和消费者。
- Durable Object 错误时，比较
class_name与src/index.tsx实际导出的类名，并检查迁移声明。
当前模板导出 RateLimiterDO、CounterDO、NonceDO、TokenBucketDO 和 TimerDO。新增或调整类应按 Durable Object 迁移规则处理，不能随意修改已经部署过的迁移标签，详见 Wrangler Durable Object 配置。
七、域名不通或反复跳转
先在浏览器 Network 中查看跳转链，判断发生在 DNS、TLS、站点入口，还是登录流程。
| 现象 | 检查方向 |
|---|---|
| 无法解析域名或连接失败 | DNS、目标账户、域名接入和证书状态 |
| 不同域名之间循环跳转 | VITE_SITE_URL、实际 Host、deploy.hosts 和代理跳转规则 |
| 首页正常，登录后失效 | Cookie 主机、协议和 OAuth 回调 |
| 只在某个旧入口出错 | 是否仍访问旧 Worker 或旧自定义域名 |
模板生产地址要求完整 HTTPS Origin，不包含额外路径、查询参数或端口。设置正式域名使用 domain:set，它会修改配置并重新部署，但不包含日常更新流程的完整数据库迁移和 KV 同步。
切换后分别核对 GitHub、Google、Stripe 和 Turnstile 的配置。站点地址修改不会自动更新第三方平台后台中的回调或允许主机列表。
八、部署完成，却仍是旧内容
先核对正在访问的地址和 Worker 版本，再处理缓存。对于文档与博客，还要分开看页面导航、正文和搜索索引。
构建时生成的导航或搜索已更新，但远程 KV 同步失败时，可能出现页面结构新、正文旧的情况。确认本地代码与当前发布版本一致后，可以单独恢复内容同步：
npm run kv:sync:remote这是远程写入操作，应使用准备发布的正确内容版本。正常发布通常使用 deploy:update 一起更新构建产物和 KV，不需要每次重复手工同步。
/docs 或 /blog 返回 404 时，还要检查 deploy.content 对应开关、baseUrl、启用语言和内容目录。不要把所有 404 都当作 CDN 缓存问题。
九、查看日志和验证恢复
在目标项目目录启动实时日志，再复现一次失败请求：
npx wrangler tail也可以在 Cloudflare 控制台查看目标 Worker 的运行日志。记录失败路径、时间、错误名和关联 ID，分享前隐藏凭据与个人信息。命令说明见 Wrangler Worker 命令。
健康检查只检查首页及已启用内容入口等页面响应，不能证明注册、支付、邮件或后台任务正常。修复后完成原故障操作，再按上线验收验证受影响的业务。