用 Codex 检查 Vercel 部署问题

Vercel 部署失败时，新手很容易只看最后一行红字，然后不断改代码。实际上部署问题可能来自 build 命令、Node 版本、环境变量、路由、依赖、静态生成、域名、账号权限或平台配置。Codex 可以帮你解释日志、列可能原因和整理排查顺序，但最终要靠人工确认项目环境和客户授权。

这篇文章适合小网站、Next.js 项目、作品集页和落地页部署前后的检查。若你要做完整交付，可以配合 小网站交付检查；如果只想要短表版，可以看 Vercel 部署检查清单。

适合谁

适合已经能本地运行项目，但第一次部署到 Vercel 时遇到构建失败、页面 404、环境变量缺失或线上和本地不一致的新手。你可能会用 Codex 修代码，但还不熟悉部署日志和平台设置。

也适合准备接小网站部署协助的人。部署任务看起来轻，但往往涉及客户账号、域名、环境变量和上线后验收，边界必须提前写清。

不适合谁

不适合直接拿客户生产项目试错的人。没有预览环境、没有回退方案、没有客户授权时，不应该贸然改部署设置。

也不适合处理复杂后端、数据库迁移、支付、登录权限和真实用户数据的新手独立承接。Vercel 部署检查不能替代完整运维和安全审查。

风险提醒

部署风险主要有三类。第一是环境差异：本地能跑，不代表云端有相同 Node 版本、环境变量和文件系统。第二是账号授权：域名、项目设置、环境变量、团队权限都可能需要客户登录。第三是公开风险：草稿页、测试数据、临时链接、调试日志不应进入公开站点。

需要登录、购买、授权、DNS 修改、域名绑定、团队成员邀请或环境变量配置的事项，应先列为客户确认或明日待办，不要使用个人账号替客户完成。

具体步骤

1. 先保存日志。复制 Vercel build 日志、失败步骤、commit、分支、项目名和部署链接。不要只截最后一屏。

1. 本地复现。运行项目约定的 lint、build 或测试命令。若本地也失败，先在本地修；若本地通过但 Vercel 失败，重点看环境差异。

1. 检查 Node 和包管理器。确认 package.json、lockfile、engines、Vercel 构建命令是否一致。不要混用 npm、pnpm 和 yarn。

1. 检查环境变量。确认是否有 .env.example 或 README 说明。真实密钥不要写进代码或聊天记录，客户项目要由客户确认配置方式。

1. 检查路由和静态生成。Next.js 项目常见问题包括动态路由参数、服务端代码、构建期读取数据、缺少 fallback、大小写路径不一致。

1. 检查公开面。部署成功后打开首页、关键页面、工具页、sitemap、robots 和 404。草稿、测试页和未审核内容不能出现在公开导航或 sitemap。

1. 写交付记录。记录命令、日志结论、已验证页面、未覆盖范围和客户待确认事项。报错可用 报错解释器拆解，报价可用 报价计算器估算复核时间。

Codex 可以帮什么

Codex 很适合做日志摘要、错误分类、构建命令对比、环境变量缺口提醒和交付记录草稿。你可以让它先分析，不要立刻改文件。

提示词可以这样写：

请分析这段 Vercel build 日志。
不要直接修改代码。
请列出错误类型、可能原因、低风险验证命令、需要客户确认的账号或环境变量事项。

这个提示词能把节奏从“马上改”拉回“先判断”。

上线后复查

部署成功不是结束。上线后至少打开首页、主要页面、CTA、表单、sitemap、robots 和移动端视图。如果是客户网站，还要确认正式域名、联系方式、隐私政策和免责声明是否为最终版。

需要模板时，可以从 模板库 里拿部署检查记录；准备客户说明时，可以用 Proposal 生成器起草后人工删改。

部署记录怎么写

建议把部署记录写成固定格式：分支、commit、部署链接、本地命令、Vercel 日志结论、环境变量状态、已验证页面、客户待确认事项。这样即使部署失败，也能说明你做了哪些有效判断。

例如：本地 build 通过，Vercel build 失败在环境变量读取；当前没有真实密钥，需客户在 Vercel 项目设置中配置；暂不修改业务代码。这样的结论很短，却比“部署失败了”有用得多。

客户项目怎么降风险

客户项目不要一上来绑定正式域名。更稳的顺序是先预览部署，再检查页面，再确认环境变量和表单，最后由客户确认域名和账号配置。预览环境能让你发现问题，同时减少对正式访问的影响。

如果客户要求马上上线，但没有给完整材料，你可以先交付部署诊断报告。报告包含失败原因、缺少材料和下一步建议，不等于承诺立即修完所有部署问题。

CTA：下一步

找一次 Vercel 部署日志，先不要改代码。把它拆成：本地是否复现、Vercel 哪一步失败、是否需要环境变量、是否涉及客户账号。再用 检查清单 逐项复核。

免责声明

本文是学习和流程整理，不构成法律、财务、安全或职业承诺。具体部署需要结合项目代码、Vercel 设置、客户授权、平台规则、数据边界和真实运行环境人工判断。