deploy-an-app

部署应用

让只能在一台机器上运行的应用为所有人提供服务。最终会得到一个由用户拥有的线上 URL，背后有真实的基础设施，并如实说明已为用户完成了哪些工作，以及还有哪些事情需要用户自行处理。

部署不是构建。 此技能负责配置基础设施、设置配置并运行部署。它不会添加功能、重新设计页面，也不会改进它碰巧不喜欢的代码。如果确实需要修改代码才能在生产环境中运行——而且只有一种常见情况，即将 SQLite 应用迁移到 Postgres——就会将其列入第 3 步的清单，并在修改前获得批准。

大部分工作都可以自动化，而无法自动化的部分也能提前知晓。 此技能的价值不在于运行 vercel deploy，而在于开始前一次性在同一处询问所有只能由人工提供的凭据，而不是每次构建失败后才发现还缺少凭据。

基本原则

• 每一步都要像给一位聪明但不会编程的朋友讲解那样说明。先说“人们会输入的地址”，再说“域名”。每个术语只需简要介绍一次，之后正常使用。
• 绝不写出或接受版本号。 安装命令中不行，正文中不行，也不能用 CLI 版本号作为门槛。每次调用都使用当前版本，而第 1 步会确定当前版本的含义。技能文件中写下的版本号，只是一条带有时间戳的谎言。
• 绝不使用已弃用的内容。 如果当前版本重命名或取代了参考文件中使用的内容，就用替代项，而不是那个“仍然可用”的旧路径。
• 关于托管 CLI 能做什么，--help 的优先级高于一切——包括本文件、参考文件、第 1 步的研究，以及服务提供商自己的文档。文档描述的是撰写者当时使用的版本。要询问即将运行的二进制文件。这是部署侧与父技能规则的对应：研究结果在 API 细节上具有优先权。
• 公开 URL 必须从平台读取，绝不能预测。 名称冲突会导致主机分配其他名称，而所有基于猜测 URL 得出的值——登录来源、OAuth 回调、令牌受众——都会因此悄然出错。
• 构建开始前必须设置好构建所需的一切。 不只是数据库。提供商客户端会在模块首次导入时创建，因此缺少密钥会导致构建失败，而不是运行时警告。第 7 步必须在第 8 步开始前完成。
• .env 不是部署产物。 其中有些值在生产环境中非常危险——本地数据库地址、沙盒支付开关、关闭签名检查的开关。每项都要有意识地复制、转换、重新生成或拒绝。references/env.md 中有对应表格；不要循环复制。
• 密钥只能从来源传到主机，不得出现在其他地方。 绝不打印，绝不回显到对话中，也绝不在文件或环境变量可行时通过聊天消息索取。
• 只需一次批准，并且只在一处事先说明暂停。 第 3 步是用户唯一需要做决定的地方。第 6 步是预先安排好的交接，用户需要执行任何 API 都无法完成的浏览器操作——要事先在清单中说明，这样它才是一次会议，而不是一次打断。
• 除非用户另行明确说明，否则使用测试模式。 清单中的其他事项都在一次批准后执行。收取真实款项则不然：这是唯一可能从真实银行卡扣款的操作，而且真实价格之后无法删除。
• 创建前先检查，并记录创建的内容。 这里的每个服务提供商都会毫不犹豫地再创建一个同类资源。同一个 URL 上有两个 webhook，就意味着每个事件都会被处理两次，其中一半的签名检查会失败。每创建一项，就立即写下记录，绝不能事后重建——格式见 references/recovery.md，有了它，中断的运行才能有据可查，而不是令人困惑。
• 发生故障时，停止并报告——绝不拆除。 后续步骤无法访问的数据库，仍然保留着已成功运行的架构。references/recovery.md 说明哪些可以撤销，哪些不能。
• 绝不删除或覆盖本次运行未创建的内容。 遇到名称冲突时，停止并询问。例外情况是本次运行自行写入并需要修正的值。
• 没有运行的检查要明确说明，绝不能声称已通过。 在此技能中，容易犯的错包括：只读取了名称，却声称已验证环境；只收到页面返回的 200，却声称已连接数据库；只注册了端点，却声称 webhook 可用。用户会把沉默视为成功。
• 通过修复部署来通过门槛，绝不能放宽门槛。 不得抑制构建错误，不得跳过验证，尤其绝不能为了让红色 X 变绿而从构建脚本中移除迁移步骤。
• 绝不使用 drizzle-kit push。 这是父技能的规则；而且这里的数据库中存放着用户的真实数据。
• 应用必须从当前工作目录部署——该文件夹就是项目根目录。绝不创建子文件夹，也绝不 cd 进入子文件夹。
• 所有命令、软件包名称和配置都放在参考文件中，绝不放在本文件中。只加载检测到的分支所需的参考文件。
• 如果参考命令因工具发生变化而失败，请查阅该工具的官方文档，使用当前的等效命令完成任务，并在最后告知用户需要更新哪个文件。

步骤 0 — 部署前检查

先弄清楚实际情况，再做任何承诺。references/preflight.md。

这里的任何操作都不会更改任何内容。此步骤会确认：托管 CLI 是否可用，以及它实际能做什么；用户是否已登录，以及登录的是哪个账户；这个应用是什么、使用哪个包管理器，以及构建命令实际会运行什么；从代码中读取应用具备哪些功能，而不是向用户询问；代码读取的环境变量完整列表；以及 Git 工作树是否干净。

分支列表来自代码。 应用有支付功能，是因为其中有支付客户端，而不是因为用户记得提过。这也让该技能可以用于它没有构建过的应用。

如果工作树不干净，就在此停止。 从未提交的工作中部署，构建结果就无法复现；而两种部署方式——推送和直接上传——对其实际包含的内容甚至意见不一。

是否已有面向用户的生产部署？ 如果有，本次运行后续步骤的处理方式就要改变：不从头创建任何内容，并且步骤 8 不会直接部署到生产环境。应在这里确认，而不是等到真正需要时再确认。

步骤 1 — 检查当前情况

现在已知有哪些分支，接下来要了解目前部署这些分支需要做什么。沿用父技能的模式：每个检测到的分支分配一个研究子 Agent，并在同一条消息中一次性派发。

托管 CLI、控制面板和服务商 API 的变化比应用库更快，而且这些变化会导致脚本出错，而非类型报错。一个已重命名的标志，可能就会让流水线半途停止，而此时有些资源已经创建。

每个子 Agent 都会收到标准任务说明——当前稳定版本、已弃用或重命名的内容、当前命令和端点的格式，以及自参考文件编写以来新增的、可替代手写步骤的功能。像父技能一样协调结果：只采用最新稳定版本，有新功能就采用；至于各部分如何配合，由本技能决定。

只有发现变化时才向用户说明。 如果研究结果表明一切正常，却仍然讲述研究过程，只会显得多余。

步骤 2 — 只有用户才知道的信息

问题不多，因为步骤 0 已从代码中解答了大部分内容。每次只问一件事，并给出建议。

1. “您希望应用使用哪个地址？”——用户拥有的域名，或托管服务商提供的免费域名。先问这个问题，因为每个回调 URL、每个 webhook 目标和登录来源都由它决定，之后每次更改都需要手动重新处理。
2. 检测到的分支所需的凭据，集中在一个区块中收集——每个服务商账户和密钥、各自用途，以及获取方式。不要每出一个问题就问一次。
3. 如果有支付功能：使用测试模式还是收取真实款项。 建议使用测试模式。收取真实款项需要另行明确确认。

第 3 步 — 部署方案

用通俗的话重述方案，并获得明确的同意。start-an-app 第 3 步在部署方面的任务是：

这是我将为 TrailLog 配置的内容：

访问地址： traillog.com — 你需要在域名注册商处添加两条 DNS 记录，我会告诉你具体内容。 数据库： 托管的 Postgres，免费套餐 — 空闲时会休眠，因此长时间无人访问后首次打开需要等一秒。 照片： 连接到项目的文件存储，有一定的免费额度。 登录： 你需要将一个回调 URL 粘贴到 Google 控制台 — 大约两分钟，我会提供确切的文本。 付款： 在测试模式下配置。你同意之前不会使用真实卡片。 费用： 今天不花钱。所有部分都使用免费套餐，我会告诉你每项免费额度的上限。 暂停一次： 设置好地址后，我会停下来给你一份简短的浏览器操作清单 — 包括 DNS 记录和 Google 回调。其他操作都会自动完成，不会打断你。

这样可以吗？

说明将创建哪些内容、费用是多少、哪些操作不可逆，以及会在哪一步暂停。对于 SQLite 应用，也要在此用通俗的话说明代码需要进行的转换。

第 4 步 — 地址

后续所有操作都需要 URL，因此必须先确定地址，再创建其他内容。references/project-and-url.md。

创建项目，读回平台实际分配的生产 URL，如果有自定义域名则将其绑定，并生成用户需要添加的 DNS 记录。尽早开始配置 DNS：这是整个流程中最耗时的步骤，而且不依赖其他步骤。

如果涉及域名，要确定规范主机名 — 裸域名还是 www — 并将另一个重定向到它。在错误主机名上设置的会话 Cookie，可能导致登录看似成功，之后却无法使用。

第 5 步 — 配置资源并做好准备

references/provision-database.md；如果涉及上传功能，还要查看 references/provision-storage.md。

创建数据库和文件存储，并将它们连接到项目。两个细节决定能否成功：提供商注入的名称可能与代码读取的名称不同；迁移需要使用直接连接字符串，而应用需要使用连接池连接字符串。

如果需要修改代码，也在这一步完成：转换 SQLite，并统一变量名。提交这些更改。

然后在部署任何内容之前，使用生产数据库在本地构建。 这会运行与平台相同的迁移后构建流程，发现转换问题和所有模块作用域密钥问题，而且不会消耗部署次数。这是此技能中性价比最高的一项检查。

第 6 步 — 统一处理

这是唯一一次提前告知的暂停。将所有需要用户在浏览器中操作的事项放在同一个区块中交给用户：DNS 记录、OAuth 回调 URL，以及用户仍需创建的任何服务商账户。提供可直接粘贴的准确值。

这不是让用户做决定 — 第 3 步已经完成了这件事。这是提前承诺好的安排好的交接，让用户可以一次性花十五分钟在控制台中完成操作，而不是被打断五次。

第 7 步 — 环境变量

references/env.md。在任何构建开始前，将代码读取的所有变量写入生产环境。

有三点让这不只是简单复制：有些值必须转换或拒绝，不能直接复制；有些密钥末尾不可见的换行符会导致密钥损坏，而且无法读回以排查问题；此外，写入密钥后可以确认它确实存在，但永远无法确认它确实正确。

接下来配置那些只需要 URL、无需网站已上线的外部系统 — 付款 Webhook、后台任务密钥。仅在相应分支存在时，才查看 references/wire-payments.md、references/wire-jobs.md、references/wire-auth.md、references/wire-email.md 和 references/wire-mcp.md。

步骤 8 — 部署

references/deploy.md。执行一次。 构建所需的一切都已就绪，因此首次部署就是首次有望成功的部署，而不是一次因缺少数据库而失败的试验性部署。

如果用户已有代码仓库，就连接该仓库并通过推送触发部署——这样，他们今后一直会用的机制刚刚得到验证。直接上传是备用方案。

然后确认已上线的部署对应的正是你认为的那个提交。这只需一条命令，就能避免两种最常见的虚假成功：新构建仍在进行时查看了上一次构建的结果，以及部署了从未提交过的内容。

只有本次运行创建的项目才能直接部署到生产环境。 如果已有面向用户的线上网站，情况就不同了，具体请见 references/deploy.md。

步骤 9 — 验证

references/gate.md。应用已部署，但目前还没有任何证据能证明它正常运行。

对线上 URL 执行命令并读取输出。无需浏览器就能从外部切实验证的内容比看起来更多：已部署的提交、迁移是否运行、数据库是否有响应、每条路由、证书和规范主机、Cookie 标志、Webhook 端点是否会验证签名而不是接受任何请求，以及发现文档是否指向真实域名。

区分失败、受阻和未尝试。 如果 DNS 尚未生效，那么所有依赖该域名的检查都会因同一个原因失败；把同一原因报告成 15 项失败，只会让用户学会忽略验证结果。

如果可以使用浏览器，就用浏览器——在正式域名上实际登录，是唯一能同时证明 URL、数据库和会话 Cookie 都正确的检查。其他仍无法完成的检查都要明确标为未执行。

步骤 10 — 独立审视

验证能证明网站有响应，却无法判断部署是否符合约定，或是否留下了什么。在一条消息中派发审查者，只读访问、查看证据而非权限；进行两轮后停止。说明见 references/gate.md。

审查视角与父级技能的不同，因为这里没有新应用需要审查——核对清单与实际情况、主张与证据、机密是否暴露，以及是否有遗留内容。

步骤 11 — 交接

• 当前已有哪些资源，以及费用是多少，根据创建过程中维护的记录说明——列出每项资源、免费额度限制，以及如何移除。
• 下一次 git push 会发生什么。 如果已配置推送即部署，这会彻底改变他们的工作方式，值得用一句直白的话说明：推送到主分支就会上线，迁移出错则构建会失败。
• 如何再次部署，以及如何回滚。
• 所有未能执行的检查，以及执行这些检查所需的条件。
• 仍待完成的手动步骤，如协调过程中有遗留。
• 如果已构建 Agent 访问能力，提供连接器 URL，以及在 Claude 中的配置位置——他们不会自行找到。
• 列出步骤 1 的调研发现中与实际情况相矛盾的内容，以便修正此技能。