构建失败别只看最后一行：让 Codex 找到第一处有效错误

教程定位

这篇教程解决什么问题

构建失败最容易误导人的地方，是它常常把真正的错误埋在中间，最后只留下一句很大的失败结论。你看到终端底部写着 `ELIFECYCLE Command failed with exit code 1`、`Error: Process completed with exit code 1`、`Build failed`、`npm ERR! code 1`，心里会自然地想从最后一屏开始看。但最后一屏往往只是任务调度器、包管理器或 CI 平台的收尾汇报，它告诉你“失败了”，却不告诉你“最早在哪里失败”。

这篇教程讲一个具体场景：发版前构建日志很长，最后只显示任务失败，负责检查的人需要让 Codex 从完整日志中找出第一处有效错误、相关文件、可能触发它的最近提交，以及修复优先级。这里的“第一处有效错误”不是日志里第一行红字，也不是最后一条 error，而是最早能解释构建为什么无法继续的那条错误。它可能是 TypeScript 类型错误、模块解析失败、缺少环境变量、依赖版本冲突、静态生成阶段的路由错误，也可能是测试在构建流程里失败。后续几十条失败、warning、退出码和脚本包装信息，很多只是它的连锁后果。

本文的目标读者是负责发版前检查的工程师。你可能不是这次改动的作者，只是在 release cut 之前跑了一次 `pnpm build` 或看 CI 构建记录。日志从安装依赖开始，一路经过 lint、类型检查、单元测试、打包、静态页面生成、产物校验，最后只剩一句任务失败。你要交付的不是“我感觉是构建坏了”，而是一份构建失败定位报告：第一处有效错误是什么，出现在什么阶段，指向哪些文件和行号，和哪个最近提交最可能相关，当前应该先修什么，哪些日志暂时不该处理。

Codex 很适合做这件事，因为它能在长日志中提取错误层级、识别重复块、对照路径和提交记录，把人眼容易混在一起的信息拆开。但前提是你要给它正确任务：不要让它泛泛地“分析构建失败”，而要明确要求它按时间顺序找第一处有效错误，区分根因、连锁失败和包装错误，并结合最近提交和依赖版本判断优先级。

本文不讨论运行时 bug。比如页面上线后点击按钮报错、用户访问某个接口 500、浏览器红屏、Node 服务启动后某条请求失败，这些属于运行时定位。本文只处理构建阶段：命令还没成功产生产物，或者 CI 在发版前检查里失败。这个边界很重要，因为构建失败的证据顺序和运行时 bug 不一样。构建日志里最重要的是阶段、命令、退出码、第一条有效错误、相关源码路径、依赖版本和最近提交，而不是用户操作路径或线上请求链路。

我们会用一个虚构但真实感很强的例子：一个 Next.js + TypeScript 项目在发版前运行 `pnpm build` 失败。日志最后只有 `next build exited with code 1`，中间夹杂了 ESLint warning、Browserslist 提示、Sentry source map 警告和多页静态生成信息。真正导致构建失败的是 TypeScript 在 `src/features/billing/InvoiceSummary.tsx` 里报错：最近提交把 `invoice.customer` 改成可选，但组件仍然直接读取 `invoice.customer.name`。Codex 的任务不是把所有 warning 修掉，而是先把这一条错误定位出来，并给出修复优先级。

使用场景

什么情况下最适合用这一套

你是负责发版前检查的工程师。今天有一个版本准备发布，功能改动不大：账单页增加了发票摘要，订单详情页调整了字段展示，顺手升级了一个图表依赖。你在本地或 CI 上跑构建，终端滚了好几分钟，最后停在一屏失败信息：

这几行没有告诉你太多。你往上翻，看到一堆东西：

如果你只看最后一行，就会以为 `next build` 本身坏了，或者包管理器失败。若你被 warning 吸引，可能会先去更新 Browserslist、修 React Hook 依赖、处理 Sentry source map。可这些未必是本次构建失败的根因。真正能解释退出码的，可能是中间那条 TypeScript 错误。

构建日志的困难在于它由很多层叠在一起：包管理器负责启动脚本，构建工具负责打包，框架负责类型检查和静态生成，插件负责上传 source map 或校验产物，CI 平台负责汇总退出码。任何一层都可能打印 `error`，但不是每个 `error` 都是根因。你需要把它们拆开看：

让 Codex 参与时，你不能只粘最后二十行。最后二十行经常缺少关键上下文。你要给它完整构建日志，至少是从命令开始到失败结束的完整片段；再给最近提交摘要、构建命令、Node 和包管理器版本、关键依赖版本。这样它才能判断错误发生在哪个阶段，和哪次改动最相关。

一个好的输出不应该马上变成“请修改代码”。发版前检查最需要的是定位报告和修复优先级。比如：

第一处有效错误：`src/features/billing/InvoiceSummary.tsx:88` 读取可能为 `null` 的 `invoice.customer`，TypeScript 在类型检查阶段失败。

相关最近提交：`a13f2c7 billing: allow invoices without customer record`，该提交把 `Invoice.customer` 类型从 `Customer` 改为 `Customer | null`，但没有同步调整发票摘要组件。

修复优先级：P0，阻断构建；优先修组件空状态或数据适配层。Browserslist、React Hook warning、source map 上传 warning 暂不作为阻断项。

这类报告能让改动作者快速接手，也能让 release owner 判断是否应该暂停发布、回退某个提交，还是做一个很小的修复后重新构建。

• 哪个阶段从正常变成失败：安装、lint、typecheck、test、bundle、static generation、postbuild。
• 第一条使命令退出的有效错误是什么：类型错误、模块找不到、测试断言失败、环境变量缺失、依赖不兼容。
• 它指向哪个项目文件：源码路径、配置文件、测试文件、锁文件或构建脚本。
• 它是否和最近提交相关：字段改动、依赖升级、导出方式调整、路径改名、配置变更。
• 后续日志是否只是包装信息：`ELIFECYCLE`、`Process completed`、重复失败块、插件收尾失败。

> web@1.18.0 build /workspace/apps/web
> next build

Failed to compile.

 ELIFECYCLE  Command failed with exit code 1.
Error: Process completed with exit code 1.

Browserslist: caniuse-lite is outdated. Please run:
  npx update-browserslist-db@latest

./src/features/orders/OrderTimeline.tsx
42:6  Warning: React Hook useEffect has missing dependency: 'reload'. react-hooks/exhaustive-deps

info  - Creating an optimized production build ...
info  - Compiled successfully
info  - Linting and checking validity of types ...
error TS18047: 'invoice.customer' is possibly 'null'.
error Command failed with exit code 1.

材料准备

开始前先把材料和边界备齐

开始前准备四类材料。缺任何一类，Codex 都可能把日志读偏。

第一类是完整构建日志。这里的“完整”不是从项目创建以来的所有日志，而是从本次构建命令开始，到失败退出结束。要保留命令、阶段切换、第一条 error、后续 error、warning、退出码和 CI 平台收尾信息。很多人只复制最后一屏，这会把第一处有效错误剪掉。更稳的做法是把日志保存到文件，例如 `build.log`，再让 Codex 读取或粘贴关键片段。

第二类是构建命令和运行环境。至少包括命令本身、所在目录、Node 版本、包管理器和版本、构建工具或框架版本。比如：`pnpm --filter web build`、`Node 20.11.1`、`pnpm 9.1.0`、`Next.js 14.2.3`、`TypeScript 5.4.5`。如果本地成功、CI 失败，还要提供 CI 环境差异：操作系统、缓存、环境变量是否可用、是否使用 `--frozen-lockfile`。

第三类是最近提交。不要只写“最近改了账单页”。最好给出最近 5 到 10 个提交的标题、hash、作者和 touched files。构建失败常常不是当前文件孤立坏掉，而是最近提交改变了类型、导出、路径、依赖版本或构建配置。Codex 需要把日志里的文件和提交里的文件对上。

第四类是依赖版本和锁文件变化。构建失败不一定来自业务代码。一次依赖升级可能让 `eslint` 规则变严格、让 TypeScript 类型更窄、让打包插件改变默认行为、让 Node ESM 解析方式暴露问题。给 Codex 依赖版本时，不必把整个 lockfile 贴进去，但要说明最近是否改过 `package.json`、`pnpm-lock.yaml`、`package-lock.json`、`yarn.lock`，以及关键依赖是否升级。

在粘贴日志前要做脱敏。构建日志可能包含私有 npm registry、Sentry token、环境变量名、内部域名、路径中的个人用户名、客户名称。可以保留错误结构，但替换敏感值。例如把真实仓库地址写成 `git@internal.example.com:team/web.git`，把 token 写成 `[REDACTED_TOKEN]`。不要为了“完整”把真实密钥交给任何 AI。

准备好材料后，把本轮目标写窄：

这组约束看起来像在限制 Codex，其实是在帮它像构建值班的人一样工作。构建失败不是越勤快越好，尤其在发版前。你要的是最快找到阻断点，并用最小代价恢复可构建状态。

• 先不要修改代码。
• 先从日志中找第一处有效错误。
• 按构建阶段整理，不按最后一屏整理。
• 区分阻断错误、连锁失败、warning 和 CI 包装信息。
• 标出相关文件、行号、最近提交和依赖版本线索。
• 给修复优先级，不要一次性处理所有 warning。
• 如果证据不足，列出需要补充的日志或文件。

实操流程

按这套步骤把工作跑起来

第一步，先确认失败的是哪条命令。复杂项目常常有 monorepo、多个 package、多个脚本串联：`pnpm lint && pnpm typecheck && pnpm build && pnpm test:ci`，也可能是 `turbo run build --filter=web`。最后的退出码只说明某个脚本失败，但你需要知道具体是 `web#build`、`api#typecheck`、`docs#build`，还是 postbuild 上传产物失败。让 Codex 先从日志中提取命令层级和失败 package。

第二步，按时间顺序找阶段边界。构建日志通常会出现明显阶段提示：安装依赖、恢复缓存、lint、type check、bundle、generate pages、collect traces、upload source maps、artifact check。让 Codex 把这些阶段列出来，并标出哪一阶段第一次出现阻断性 error。这样可以避免把 postbuild 的失败当成 bundle 的失败，也避免把 warning 阶段当成失败阶段。

第三步，找第一处有效错误。判断标准不是“第一条出现 error 字样”，而是“最早能解释命令为什么退出失败的错误”。例如 `Browserslist outdated` 看起来像错误提示，但通常不阻断；`React Hook missing dependency` 如果是 warning，也不阻断；`error TS18047` 在 `next build` 的 type checking 阶段会阻断；`Module not found: Can't resolve '@/features/billing/InvoiceSummary'` 在编译阶段会阻断；`ReferenceError: window is not defined` 在静态生成阶段会阻断。让 Codex 对每个候选错误写清楚“是否阻断”和理由。

第四步，提取相关文件和行号。第一处有效错误通常会带文件路径、行号、列号，或者测试文件和断言位置。Codex 应该把路径拆出来，而不是只复述错误文本。例如：`src/features/billing/InvoiceSummary.tsx:88:31`、`src/app/invoices/[id]/page.tsx`、`packages/ui/src/index.ts`、`vitest.config.ts`。如果日志只指向编译后的路径或框架内部路径，就要继续向上找项目源码路径。

第五步，结合最近提交判断触发改动。让 Codex 把错误文件和最近提交 touched files 对比。最强线索通常是：同一文件刚改过；上游类型定义刚改过；路径刚重命名；依赖刚升级；配置刚变严格。比如错误在 `InvoiceSummary.tsx`，最近提交没有改它，但改了 `types/invoice.ts`，把 `customer` 改为可空，这仍然是强相关。Codex 的输出要写“证据”，不要只写“可能相关”。

第六步，检查依赖版本线索。若错误类型是 `Cannot find module`、ESM/CJS 解析失败、插件 API 不存在、类型声明不匹配、peer dependency 冲突，就要看最近是否升级依赖。比如 `@sentry/nextjs` source map 上传失败可能是插件配置问题，但如果构建主体已经成功，只是上传 source map 失败，优先级和 TypeScript 阻断不同。依赖版本可以帮助你判断是业务修复、锁文件修复、还是回退依赖。

第七步，给修复优先级。不要把所有错误同等处理。建议分成四类：

P0：直接阻断构建，必须先修。比如类型错误、模块解析失败、测试失败、静态生成崩溃。

P1：可能在修完 P0 后继续阻断，需要下一轮构建验证。比如日志里出现多个 package 的独立失败，但当前构建在第一处就退出。

P2：不阻断但影响发布质量。比如 source map 上传 warning、bundle size 警告、过期配置提醒。

P3：噪音或技术债。比如开发模式 warning、重复日志、非本次改动导致的老 lint warning。

第八步，输出“不处理清单”。这一步很重要。发版前最怕为了让日志变干净，顺手修了十个 warning，结果引入新风险。Codex 应该明确列出：哪些 warning 暂不处理，哪些依赖提醒不作为当前阻断项，哪些 CI 包装错误只是结果，哪些后续失败需要等 P0 修完后重新构建再看。

第九步，再决定是否进入修复。定位报告完成后，你可以让 Codex 做最小修复，但提示词要带上边界：“只修 P0 阻断错误；不要处理 P2/P3；如果发现需要改共享类型或依赖版本，先说明影响范围。”这样它不会从 TypeScript 空值错误一路改到 Sentry 配置和 lint 规则。

第十步，修复后重新构建并更新报告。构建失败有一个特点：修完第一处有效错误后，第二处错误可能浮出来。这不是定位失败，而是构建流程终于走到了更后面。报告里要记录每一轮：本轮第一处有效错误、修复点、重新构建结果、是否出现新的阻断错误。这样 release owner 能看见进展，而不是只听到“还在修”。

输入示例

可以直接参考的输入材料

下面是一份可以直接交给 Codex 的材料包。它模拟一个发版前构建失败的场景。真实项目中请替换为自己的日志、提交和版本，并先脱敏。

这份输入里有多个干扰项：Browserslist 过期、React Hook warning、依赖升级、Next worker 退出、CI 收尾失败。它们都值得知道，但第一处有效错误更可能是 `InvoiceSummary.tsx` 的 TypeScript 空值错误，因为它出现在 `Linting and checking validity of types` 阶段，带有项目源码路径和行号，并且能直接解释 `Next.js build worker exited with code: 1`。

任务：
请先不要写代码。请从完整构建日志中找第一处有效错误，输出构建失败定位报告和修复优先级。

构建命令：
pnpm --filter web build

运行环境：
Node: 20.11.1
pnpm: 9.1.0
Next.js: 14.2.3
TypeScript: 5.4.5
CI: Ubuntu 22.04

最近提交：
f7a91bd billing: show invoice summary on detail page
  - apps/web/src/features/billing/InvoiceSummary.tsx
  - apps/web/src/app/invoices/[id]/page.tsx

a13f2c7 billing: allow invoices without customer record
  - apps/web/src/features/billing/types.ts
  - apps/web/src/features/billing/normalizeInvoice.ts

9cd32e1 deps: upgrade chart renderer to 3.8.0
  - package.json
  - pnpm-lock.yaml

完整构建日志片段：
> web@1.18.0 build /workspace/apps/web
> next build

  ▲ Next.js 14.2.3
  - Environments: .env.production

Browserslist: caniuse-lite is outdated. Please run:
  npx update-browserslist-db@latest

info  - Creating an optimized production build ...
info  - Compiled successfully
info  - Linting and checking validity of types ...

./src/features/orders/OrderTimeline.tsx
42:6  Warning: React Hook useEffect has a missing dependency: 'reload'. react-hooks/exhaustive-deps

./src/features/billing/InvoiceSummary.tsx:88:31
Type error: 'invoice.customer' is possibly 'null'.

  86 |       <div className="invoice-summary">
  87 |         <span className="label">客户</span>
> 88 |         <span>{invoice.customer.name}</span>
     |                               ^
  89 |       </div>
  90 |     )
  91 |   }

Next.js build worker exited with code: 1 and signal: null
 ELIFECYCLE  Command failed with exit code 1.
Error: Process completed with exit code 1.

补充信息：
- 本地 main 分支昨天构建成功。
- 这次 PR 改了发票详情和账单类型。
- package.json 里 chart renderer 升级了，但日志里没有直接出现 chart 相关错误。

提示词

可复制使用的提示词

下面这段提示词适合直接复制给 Codex。你可以把日志作为文本粘贴，也可以让它读取本地 `build.log`，但任务目标要保持清楚。

如果第一轮定位已经完成，并且你准备让 Codex 进入修复，可以用第二段提示词：

把定位和修复分成两轮，会明显降低发版前误改范围的概率。第一轮让 Codex 做判断，第二轮才让它动手。

你现在只做“构建失败日志定位”，不要写代码。

我会给你完整构建日志、构建命令、运行环境、最近提交和依赖版本。请你不要只看最后一行，也不要把所有 warning 都当根因。

请按以下要求输出：

1. 构建命令和失败阶段
   - 说明失败的是哪个 package、哪个脚本、哪个阶段。
   - 如果日志里有多层命令，请拆出真正失败的那一层。

2. 第一处有效错误
   - 找出最早能解释构建失败的错误。
   - 写出错误类型、原始错误文本、文件路径、行号、列号。
   - 说明为什么它比最后一行退出码更有诊断价值。

3. 日志分层
   - 阻断错误：会导致构建退出的错误。
   - 连锁后果：由阻断错误引发的后续失败或退出码。
   - 非阻断 warning：需要记录但本轮不优先修。
   - CI 或包管理器包装信息：只说明任务失败，不作为根因。

4. 最近提交关联
   - 对照最近提交和 touched files，判断哪一个提交最可能触发错误。
   - 必须写证据，例如同一文件、上游类型、导出变更、路径重命名、依赖升级。
   - 不要只写“可能是最近改动导致”。

5. 依赖版本线索
   - 判断错误是否可能由依赖升级、锁文件变化、Node 版本或构建工具版本触发。
   - 如果依赖升级只是噪音，也要说明理由。

6. 修复优先级
   - P0：必须先修，直接阻断构建。
   - P1：修完 P0 后需要重新构建确认。
   - P2：不阻断但影响发布质量。
   - P3：暂不处理的噪音或技术债。

7. 需要继续读取的文件
   - 按优先级列出文件和读取目的。
   - 不要一开始扩大到全仓库。

8. 建议的最小修复方向
   - 只给方向，不写代码。
   - 说明应修在业务组件、类型定义、数据适配、构建配置还是依赖版本。

9. 不处理清单
   - 列出本轮不建议处理的 warning、插件提示、包装错误或无关依赖。
   - 写清不处理理由，防止修复范围扩大。

约束：
- 不要直接根据最后一行判断根因。
- 不要为了日志变干净而建议同时修所有 warning。
- 不要把运行时 bug 分析方法套到构建失败上。
- 如果日志不足，请明确要求补充哪一段，而不是猜。

现在进入最小修复阶段。

请只围绕上一轮定位报告中的 P0 阻断错误修改代码。不要处理 P2/P3 项，不要顺手修 lint warning、Browserslist 提示、source map 上传警告或无关依赖升级。

修改前请先说明：
1. 将读取哪些文件，目的是什么。
2. 预计只修改哪些文件。
3. 为什么这些文件能解决第一处有效错误。

如果读取代码后发现上一轮判断不成立，请停止并重新输出：
- 新的第一处有效错误
- 原判断为什么不成立
- 需要补充的日志或文件

输出样例

AI 应该输出到什么程度

下面是一份较理想的 Codex 输出样例。它不是完整代码修复，而是构建失败定位报告。

这份输出有几个关键点。它没有被最后一行带偏，没有把 warning 当成根因，也没有直接说“把 `invoice.customer?.name` 加上就行”。它先给出证据顺序，再给修复优先级。对于发版前检查来说，这比一份仓促的代码建议更有用。

如果你希望 Codex 的输出更适合发到团队群，可以要求它追加一个短版：

构建失败定位报告

1. 失败命令和阶段
- 命令：pnpm --filter web build
- 实际失败脚本：apps/web 的 next build
- 失败阶段：Next.js 的 “Linting and checking validity of types” 阶段
- 不是 bundle 阶段失败，因为日志已出现 “Compiled successfully”

2. 第一处有效错误
- 文件：apps/web/src/features/billing/InvoiceSummary.tsx
- 位置：88:31
- 错误类型：TypeScript 空值类型错误
- 原始错误：Type error: 'invoice.customer' is possibly 'null'.
- 相关代码：invoice.customer.name

这是第一处有效错误，因为它出现在类型检查阶段，带有项目源码路径和精确行号，并且后续 “Next.js build worker exited with code: 1” 与 “ELIFECYCLE” 都是该阶段失败后的包装结果。

3. 日志分层
- P0 阻断错误：InvoiceSummary.tsx:88 读取可能为 null 的 invoice.customer。
- 连锁后果：Next.js build worker exited with code 1；pnpm ELIFECYCLE；CI Process completed with exit code 1。
- 非阻断 warning：OrderTimeline.tsx 的 React Hook dependency warning；Browserslist caniuse-lite outdated。
- 暂无证据表明 chart renderer 升级导致本次失败。

4. 最近提交关联
- 最相关提交：a13f2c7 billing: allow invoices without customer record。
- 证据：该提交修改 billing/types.ts 和 normalizeInvoice.ts，使 invoice.customer 允许为 null；当前错误正是 InvoiceSummary.tsx 未处理 null。
- 次相关提交：f7a91bd billing: show invoice summary on detail page，因为它新增或修改了 InvoiceSummary.tsx 的展示。
- 依赖升级 9cd32e1 当前相关性低，因为日志没有 chart renderer、打包插件或模块解析错误。

5. 最小修复方向
- 优先检查 InvoiceSummary.tsx 的展示逻辑，以及 invoice.customer 为 null 时产品上应如何展示。
- 如果 customer 缺失是合法状态，组件层应显示空状态，例如 “客户信息暂不可用”。
- 如果 customer 缺失不应发生，应回到 normalizeInvoice.ts 或接口类型定义确认数据合同。
- 不建议直接全局加可选链，因为这可能掩盖客户缺失的业务语义。

6. 修复优先级
- P0：处理 InvoiceSummary.tsx 中 invoice.customer 为 null 的构建阻断。
- P1：修完后重新运行 pnpm --filter web build，确认是否出现下一处阻断错误。
- P2：记录 OrderTimeline React Hook warning，单独排期处理。
- P3：Browserslist outdated 不是本次构建阻断，暂不处理。

7. 建议继续读取文件
- apps/web/src/features/billing/InvoiceSummary.tsx：确认组件如何展示 customer。
- apps/web/src/features/billing/types.ts：确认 customer 类型改动。
- apps/web/src/features/billing/normalizeInvoice.ts：确认 null 是否为合法输入。
- apps/web/src/app/invoices/[id]/page.tsx：确认 InvoiceSummary 的数据来源。

短版给 release 群：
构建失败的第一处有效错误在 apps/web/src/features/billing/InvoiceSummary.tsx:88，TypeScript 提示 invoice.customer 可能为 null。它和最近提交 a13f2c7 将发票 customer 改为可空直接相关。Next worker exit、ELIFECYCLE 和 CI exit code 都是后续包装信息。建议优先修 InvoiceSummary 对无客户发票的展示，再重新跑 pnpm --filter web build。Browserslist 和 React Hook warning 暂不作为本次阻断项。

人工验收

人要怎么检查和改到可用

Codex 能帮你整理日志，但发版前检查不能完全交给它自动判断。你需要做几项人工确认。

第一，确认日志没有被截断。很多 CI 页面默认折叠中间日志，或者只复制最后 500 行。如果第一处有效错误在更前面，Codex 会误把后面的退出码当成线索。复制日志时要确认从构建命令开始，至少包含第一次出现 `error`、`failed`、`Type error`、`Module not found`、`test failed` 的位置。

第二，确认 warning 是否真的不阻断。有些项目会把 warning 当 error，例如 `CI=true` 下某些脚手架会让 ESLint warning 阻断构建，或者自定义脚本会检查 bundle size warning。Codex 可能根据常见经验判断 warning 不阻断，但你的项目规则可能不同。你要看脚本配置和日志里的退出位置。如果 warning 后面立刻出现 `Treating warnings as errors because process.env.CI = true`，那它就不是普通 warning。

第三，确认最近提交关联不是巧合。同一文件刚改过当然是强线索，但也可能只是碰巧。比如错误在 `InvoiceSummary.tsx`，最近提交只是改了样式类名，而真正原因是 TypeScript 版本升级后类型检查更严格。人工检查时要看触发机制：字段是否真的改成可空，导出是否真的改名，依赖升级是否真的改变类型声明。

第四，确认修复层级。构建错误指出的是报错位置，不一定是最佳修复位置。`invoice.customer.name` 报错，可以在组件里加空状态，也可以在数据适配层补默认 customer，也可以恢复类型合同。选哪一种取决于业务语义。如果“无客户发票”是合法状态，就应该让组件展示空状态；如果不是合法状态，就应该让数据层抛出更明确的错误或修正接口。不要为了让 TypeScript 通过而掩盖业务事实。

第五，确认依赖版本。若构建失败出现在模块解析、ESM/CJS、插件 API、peer dependency 或类型声明不兼容上，修代码可能不是最小解。比如最近升级 `@types/react` 后出现大量类型错误，可能需要按升级说明调整类型；最近升级 Vite 插件后出现 `plugin.apply is not a function`，可能是插件版本不兼容。Codex 的报告要帮助你判断是业务代码修复，还是依赖版本处理。

第六，确认修复优先级。P0 修完后重新构建，可能出现新的 P0。不要一次报告里承诺“修完这行就一定构建通过”。更稳的说法是：“当前日志中第一处有效错误是 X；修复后需要重新构建确认是否有下一处阻断。”这能避免发版沟通里过度承诺。

第七，检查修改范围。进入代码修复后，要求 Codex 只改和 P0 相关的最小文件。发版前不要顺手升级 Browserslist、重写 lint 规则、清理旧 warning、改动 unrelated package。构建失败处理最怕把一个可控阻断变成一串不可控变更。

第八，保留报告。修复完成后，把定位报告附在 PR 描述或发版记录里。内容不用很长，但要包含：失败命令、第一处有效错误、相关文件、相关提交、修复点、重新构建结果、未处理 warning。这能帮助后续复盘，也能让 reviewer 明白为什么这次只改了一个点。

失败反例

这些失败反例要提前避开

反例 1：只看最后一行，把退出码当根因。

很多人会把最后的 `Process completed with exit code 1` 截给 Codex，然后问“怎么修”。这几乎等于只告诉医生“我不舒服”。退出码是结果，不是诊断。它可能来自 TypeScript、ESLint、test、bundle、postbuild，也可能来自 CI 脚本自己的校验。只看最后一行，Codex 只能猜，常见输出会变成“检查依赖、清理缓存、重新安装 node_modules”。这些建议不是完全没用，但离真实修复很远。

更好的做法是补充完整构建日志，至少包含失败阶段前后的 100 到 300 行，并让 Codex 找第一处有效错误。如果日志太长，就让它先按阶段索引，而不是直接修。

反例 2：把所有 warning 都列为修复项。

构建日志里常常有很多 warning：Browserslist 过期、React Hook 依赖缺失、bundle size 超出建议、source map 上传失败、CSS order warning、deprecated API。看到它们很不舒服，尤其发版前。但如果当前阻断是 TypeScript 类型错误，先修 warning 会浪费时间，还可能引入新风险。

更好的做法是让 Codex 把 warning 分成 P2 或 P3，并写明“为什么本轮不处理”。如果项目配置确实把 warning 当 error，再升级为 P0。判断依据是日志中是否显示 warning 导致退出，而不是 warning 看起来刺眼。

反例 3：看到相关文件就让 Codex 全仓库批量改。

比如第一处错误是 `invoice.customer` 可能为 null，有人会让 Codex 搜索所有 `customer.name`，然后全部改成 `customer?.name ?? '-'`。这很危险。不同页面的业务语义不同，有的 customer 必须存在，有的缺失要报错，有的缺失要显示空状态，有的需要阻止后续请求。全局可选链可能让构建通过，却把真实数据合同问题藏起来。

更好的做法是先围绕构建报错文件和最近提交修 P0。若怀疑同类问题很多，可以作为后续专项检查，但不要混进这次发版前阻断修复。

反例 4：忽略最近提交，只按日志文本猜。

日志告诉你哪里报错，最近提交告诉你为什么现在才报错。比如 `Module not found: Can't resolve '@/components/ChartCard'`，如果最近提交重命名了 `ChartCard.tsx`，那方向很清楚；如果最近升级了路径别名插件，方向可能是配置；如果最近没有相关改动，可能是缓存或分支同步问题。只看日志文本，Codex 容易给出泛化建议；结合提交，它才能给出可验证假设。

更好的做法是提供最近 5 到 10 个提交和 touched files。让 Codex 明确写出“最相关提交”和证据。

反例 5：把构建失败和运行时 bug 混在一起。

构建失败发生在产物生成前，证据主要来自构建命令和静态检查；运行时 bug 发生在应用启动或用户操作后，证据主要来自请求、状态、浏览器或服务日志。两者当然可能有关，但处理顺序不同。比如 `window is not defined` 出现在 Next.js 静态生成阶段，这是构建失败；同样的 `window is not defined` 出现在用户打开页面后，则是运行时错误。提示词里如果不区分，Codex 可能把用户复现路径、浏览器调试方法带进来，反而偏题。

更好的做法是在开头写清楚：“本文只分析构建阶段失败，不处理上线后的运行时 bug。”

主题边界

它和相邻主题的区别

这个主题和“页面红屏调试”相邻，但重点不同。页面红屏通常要看浏览器堆栈、用户操作、接口响应、组件状态和可复现路径；构建失败要看构建命令、阶段边界、类型检查、模块解析、静态生成、依赖版本和退出码。红屏的第一条有效错误往往是运行时堆栈中的第一条业务代码；构建失败的第一条有效错误则可能在日志中间，出现在 `typecheck`、`bundle` 或 `generate static pages` 阶段。

它也和“CI 失败排查”相邻。CI 失败范围更大，可能包括权限、缓存、机器资源、测试环境、部署凭证、制品上传、网络访问。本文只关注构建日志定位。如果 CI 在安装依赖时因为私有 registry 401 失败，那是 CI 环境或凭证问题；如果 CI 成功安装后 `next build` 类型检查失败，那就是本文处理的构建失败。两者在报告里可以相互引用，但不要混成一个大问题。

它还和“依赖升级排查”相邻。依赖升级可能导致构建失败，但不是所有构建失败都应该从依赖回退开始。本文要求把依赖版本当作线索之一：如果日志出现 peer dependency、模块格式、插件 API、类型声明变化，就提高依赖线索优先级；如果日志明确指向业务代码空值类型错误，而依赖升级没有相关报错，就不要把精力先放在锁文件上。

它和“测试失败定位”也有交集。有些团队把测试放进 build pipeline，测试断言失败会让构建任务失败。此时第一处有效错误可能是 `expect(received).toEqual(expected)`，相关文件是测试文件和被测模块。处理方式仍然是先找第一处有效错误，但修复优先级要判断：是测试暴露了真实行为变化，还是测试快照需要更新。不要因为它出现在 build 日志里，就默认是打包问题。

最后，它和“发布前质量清单”不同。发布前质量清单会关心 lint warning、bundle size、source map、覆盖率、性能预算、产物大小、许可证扫描等很多项。本文只解决一个更窄的问题：当构建已经失败，如何让 Codex 从长日志里找到最早的有效阻断点，并给出可执行的修复优先级。先恢复可构建，再处理质量项，顺序清楚，发版才不容易被日志拖进泥潭。