出问题的时候

这个项目不会闷声出错。哪一步不肯往下走，它都会说明原因，并且给这个原因一个短码 —— 像 E_PLACEHOLDER_ID、E_MISSING_SECRETS —— 你可以拿它来查，而不是靠猜。

先做这个

在项目里跑：

pnpm support

它会打印一份「你的项目现在长什么样」：哪些资源根本没创建、哪些密钥没填、哪些数据库 变更还没应用、你比脚手架落后了多少。它不会读取任何密钥的值，所以这份报告给谁看 都安全。

然后把它交给你的助手：

读一下这份报告，把它点出来的问题修掉。

它找出来的东西，大部分不需要惊动任何人就能修好。如果还是失败，往下找那个码。

还什么都没配起来

E_NOT_SHIPKIT

它是什么意思。 这条命令跑在了一个不是本项目的地方。

为什么会发生。 几乎总是文件夹不对 —— 终端开在了你的用户目录，而不是项目里。

该怎么办。 进到项目文件夹（里面有 shipkit.json 的那个）再跑一次。要是不确定 它在哪，问你的助手：「我的项目在哪个文件夹？带我过去。」

E_PLACEHOLDER_ID

它是什么意思。 本该写着真实数据库或存储桶名字的地方，项目里还留着一个 TODO-。

为什么会发生。 项目是故意留着这些空的，这样它就不可能误部署到别人的账号里。 这些空由「开通资源」那一步填上，而这个环境还没跑过那一步。

该怎么办。 给那个环境开通资源 —— 先预览环境，再正式环境。跟你的助手说： 「帮我把这个项目的预览环境开通好。」这一步需要你已经登录 Cloudflare。

E_NOT_LOGGED_IN

它是什么意思。 Cloudflare 不知道你是谁。

为什么会发生。 你在这台电脑上还没登录过，或者登录状态过期了。

该怎么办。 跑 pnpm exec wrangler login。浏览器会弹出来，你点同意就好。如果你 在一台没有浏览器的机器上，把 Cloudflare API token 放进 CLOUDFLARE_API_TOKEN 也是 一样的效果。

E_STALE_ID

它是什么意思。 项目指着一个数据库，但你当前登录的 Cloudflare 账号里没有它。

为什么会发生。 通常是两个账号 —— 一个私人的、一个公司的 —— 而你登的是另一个。 偶尔是这个数据库真的在 Cloudflare 后台里被删掉了。

该怎么办。 用 pnpm exec wrangler whoami 看看你现在是谁。账号不对就重新登对的 那个。数据库确实没了，就给那个环境重新开通一次。

部署和上线

E_PENDING_MIGRATIONS

它是什么意思。 你的数据库结构有已经写好、但还没应用上去的改动。

为什么会发生。 有什么东西加了一个字段或者一张表，而「告诉线上数据库这件事」的 那一步还没跑。

该怎么办。 部署之前先把它们应用到那个环境。代码指望着一个数据库里还不存在的 字段 —— 这正是一个网站开始对真实用户报错的方式。跟你的助手说：「把待应用的数据库 变更应用到预览环境。」

E_MISSING_SECRETS

它是什么意思。 线上的站点需要一个值 —— 签名密钥、某个 API key —— 但从来没有人 给过它。

为什么会发生。 本地开发的密钥放在 .dev.vars 里，而每一个线上环境的密钥要单独 再设一次。后半句很容易被漏掉。

该怎么办。 给那个环境把密钥设上。值写进 .dev.vars.staging 或 .dev.vars.production（这两个都被 git 忽略，不会离开你的电脑），然后跑设置密钥那 一步。永远不要把密钥的值打进跟助手的聊天框里。

E_WORKER_NOT_DEPLOYED

它是什么意思。 你在给一个还不存在的站点做配置。

为什么会发生。 密钥只能挂在一个已经跑起来的东西上，所以第一次部署必须排在前面。

该怎么办。 先把那个环境部署一次，再设密钥，再部署一次。第一次部署可能因为缺密钥 而短暂失败 —— 这是预期之内的，第二次就好了。

E_PRODUCTION_GATE

它是什么意思。 没出错。是有什么东西想动正式环境，而因为没人点头，被拦下来了。

为什么会发生。 每一条会影响到你客户看见的那个线上站点的命令，每一次都要你明确 确认。这个开关关不掉，而这正是它存在的意义。

该怎么办。 如果你确实是这个意思，说清楚再带着确认跑一次。如果你不是这个意思， 那你刚刚被省下了一个很糟的下午。

命令中途停了

E_CMD_FAILED

它是什么意思。 底下的某个工具 —— 通常是 wrangler、构建或者测试 —— 报错退出了。 真正的原因就在上面那段输出里。

该怎么办。 往上读最后二十行，真正的抱怨就在里面。如果看不出来，把输出存成文件 带上：

pnpm support --last-error <那个文件>

E_VERIFY_FAILED

它是什么意思。 这一步跑完了，然后检查自己的成果，检查没过。

为什么会发生。 有东西应用了但没生效 —— 比如一条迁移应用完之后，仍然显示为待应用。

该怎么办。 这个值得报给我们。跑一下 pnpm support，把报告发过来。

E_TOOL_DRIFT

它是什么意思。 某个外部工具在脚手架底下变了，行为跟以前不一样了。

为什么会发生。 不是你的问题。是上游发了个新版本，输出格式变了。

该怎么办。 报给我们。这正是那种一改就同时给所有人改好了的问题。

E_JSONC_AMBIGUOUS

它是什么意思。 wrangler.jsonc —— 描述你那三个环境的那个文件 —— 被改成了工具 不敢再安全改动的样子。

为什么会发生。 手改过，或者一次合并冲突解错了。

该怎么办。 跟你的助手说：「把我的 wrangler.jsonc 和脚手架的对比一下，告诉我差 在哪。」三环境的结构必须留着；里面的值是你的。

E_USAGE、E_PRECONDITION、E_NONINTERACTIVE、E_DECLINED

这四个其实算不上失败。

• E_USAGE —— 命令收到了它看不懂的东西，正确写法会跟着一起打出来。
• E_PRECONDITION —— 有件事得先做，消息里写了是哪件。
• E_NONINTERACTIVE —— 有个问题需要人回答，而当时没人可问。你自己在终端里跑一次， 或者把答案作为参数传进去。
• E_DECLINED —— 问过你了，你说不。

还是卡住

看怎么找到我们。把 pnpm support 的输出、你当时想做什么、实际发生了 什么一起发过来。