让 Codex 排查构建失败

构建失败是最适合交给 Codex 分析的基础任务之一。

> 如果你还不会看 Codex 的检查结果和失败收敛方式，先完成前置教程。

> 依据来源：OpenAI Codex 官方手册中的验证、错误分析、审批、沙箱和工作流建议。

适合这些情况：

npm run build 失败。
pnpm build 失败。
npm test 失败。
类型检查失败。
lint 失败。
Maven 或后端构建失败。

本篇以前端构建失败为例，但方法可以迁移到其他构建工具。

构建失败时，不要上来就说：


帮我修好。


更稳的顺序是：


先分类 -> 再定位 -> 再最小修复 -> 再验证 -> 再总结


第 1 步：把错误完整交给 Codex
如果你已经有构建错误，把关键输出复制给 Codex。
注意：

不要复制 API Key。
不要复制生产密钥。
不要只截最后一行。
保留错误堆栈、文件路径和行号。

提示词：


当前项目构建失败。
错误信息如下：
【粘贴构建失败输出】
请先分析，不要修改文件。
要求：


判断这是依赖问题、语法问题、类型问题、路径问题、环境问题，还是配置问题。

2. 按最可能到最不可能排序。
3. 指出最可能相关的文件。
4. 告诉我最小修复方案。
5. 不要直接大范围重构。


第 2 步：如果没有错误输出，让 Codex 自己检查
如果你不知道怎么拿错误输出，可以让 Codex 根据项目现有脚本检查。
提示词：


请检查当前项目为什么构建失败。
要求：


先查看项目里有哪些构建脚本。

2. 根据项目现有脚本选择合适的检查方式。
3. 如果需要运行命令，请先说明命令目的。
4. 如果运行失败，请分析失败原因。
5. 只修复导致构建失败的最小问题，不要顺手重构。


这符合实际使用方式：用户不需要自己变成命令机器，重点是让 Codex 解释它做了什么、为什么做、结果是什么。
第 3 步：看 Codex 的分类
常见构建失败类型：
| 类型   | 常见现象                         |
| ---- | ---------------------------- |
| 语法问题 | 少括号、标签没闭合、逗号错误               |
| 类型问题 | TypeScript 类型不匹配             |
| 路径问题 | import 路径错误、大小写不一致           |
| 依赖问题 | 包没装、版本不兼容                    |
| 配置问题 | Vite、Nuxt、Astro、Webpack 配置错误 |
| 环境问题 | Node 版本、环境变量、系统差异            |
如果 Codex 分类很模糊，追问：


请不要泛泛而谈。
请指出错误输出中哪几行支持你的判断，并说明对应到哪个文件。


第 4 步：最小修复与验证
确认原因后再修：


请按最小修复方案处理。
要求：


只修改导致构建失败的文件。

2. 不要重构无关代码。
3. 不要升级依赖，除非没有其他方案。
4. 修改后请重新检查构建结果。
5. 如果仍然失败，请说明新的失败是否和本次修改有关。


如果 Codex 想升级依赖，先让它解释：


先不要升级依赖。
请说明为什么必须升级，是否有不升级也能修复的方案。


第 5 步：检查验证结果
构建失败修复后，重点看：

Codex 是否重新检查。
检查命令是什么。
结果是否通过。
如果失败，是否是同一个错误。
有没有引入新的错误。

追问模板：


请总结验证结果：


你运行了什么检查。

2. 检查是否通过。
3. 如果失败，错误是否和原问题相同。
4. 如果没有运行检查，请说明原因。


第 6 步：看 diff 是否合理
构建失败修复通常应该很小.
让 Codex 检查：


请检查本次 diff 是否合理。
要求：


列出修改文件。

2. 说明每个修改和构建失败的关系。
3. 判断是否有无关修改。
4. 判断是否有新依赖或锁文件变化。
5. 如果有锁文件变化，请说明原因。


如果修构建失败改了十几个文件，就要警惕。
第 7 步：排障总结
最后让 Codex 输出：


请给出本次构建失败排查总结：


原始错误是什么。

2. 根因是什么。
3. 修改了哪些文件。
4. 如何验证已经修复。
5. 是否还有剩余风险。

这份总结非常适合放到提交说明里。

完成后，你应该得到：

构建失败原因分类。
最可能相关文件。
最小修复。
重新检查结果。
diff 合理性检查。
交付总结。

下一步可以回到：实战案例总览。