使用 Codex 修改项目时，经常会遇到一种很典型的情况：

开发环境里页面能正常打开，功能也能跑，但一执行打包就失败。

常见表现包括：

• npm run dev 正常；

• npm run build 报错；

• 本地页面没有明显异常；

• TypeScript 构建阶段突然出现类型错误；

• 路径别名、环境变量、动态导入在 Build 时出问题。

这种情况并不一定说明 Codex 改坏了整个项目。

很多时候真正的问题是：

开发模式和正式构建检查的内容并不完全一样。

---

一、本地能跑，不代表Build一定能过

开发环境通常更关注：

能不能快速启动和热更新。

而 Build 阶段往往还会额外执行：

• 类型检查；

• 代码压缩；

• 模块解析；

• 静态资源处理；

• 环境变量替换；

• 生产配置加载。

所以某些问题在 dev 阶段没有暴露，到了构建阶段才会出现。

例如：

开发环境
↓
页面能打开
↓
功能正常

并不等于：

类型检查
构建配置
生产依赖
路径解析

全部正确。

---

二、先看Build到底失败在哪一步

不要一看到打包失败就直接重新改代码。

先运行项目自己的构建命令，例如：

npm run build

重点看错误属于哪一类：

Type error
Module not found
Cannot resolve
Missing environment variable
Build failed

不同错误对应的排查方向完全不同。

先分类，比直接让 Codex“修一下Build”更有效。

---

三、TypeScript问题经常在构建阶段暴露

例如代码：

const user = getUser()
console.log(user.name)

如果 user 可能是 undefined，开发页面未必立刻触发这个分支。

但构建时的类型检查可能直接报错。

所以可以单独运行：

npm run typecheck

或者项目对应的 TypeScript 检查命令。

这样能先确认：

到底是类型问题，还是构建工具本身的问题。

---

四、路径别名在Build时也容易出问题

例如代码使用：

@/components/Button

开发工具能够识别。

但构建配置里如果没有正确同步路径别名，就可能出现：

Module not found

尤其是项目同时使用：

• tsconfig.json

• Vite

• Webpack

• Next.js

• Jest

不同工具可能各自维护一套路径配置。

Codex修改 import 后，最好确认：

这个别名在构建工具里是否同样有效。

---

五、环境变量是另一个高频原因

开发环境可能读取：

.env.local

而生产构建使用：

.env.production

如果 Codex 新增：

API_BASE_URL

本地文件已经配置，生产构建环境却没有，就可能导致：

本地正常
↓
Build失败

所以涉及环境变量时，要确认：

• 变量名是否一致；

• 构建环境是否存在；

• 是否需要特定前缀；

• 是否在正确阶段注入。

---

六、动态导入和服务端代码也要检查

一些项目里，某段代码在开发环境可以运行，但正式构建时会被提前分析。

例如：

动态import
浏览器对象
Node专用模块
服务端API

如果客户端代码里直接使用：

window
document
fs

放错执行环境，就可能在Build阶段报错。

所以出现这类问题时，要确认：

这段代码到底应该运行在浏览器端还是服务端。

---

七、不要只跑一个Build命令

比较稳定的检查顺序可以是：

Lint
↓
Type Check
↓
Test
↓
Build

例如：

npm run lint
npm run typecheck
npm test
npm run build

具体命令按项目实际配置执行。

这样能更快判断：

问题到底出在：

• 代码规范；

• 类型；

• 功能逻辑；

• 生产构建。

---

八、Codex完成任务后最好把“Build验证”写进要求

如果项目最终需要部署，可以提前告诉 Codex：

完成修改后请依次确认：

1. 代码能正常运行；
2. 类型检查通过；
3. 测试通过；
4. 正式Build通过；
5. 如果Build失败，先说明错误类别，不要直接扩大修改范围。

这样可以避免只验证：

页面能不能打开。

却忽略真正交付时最重要的：

项目能不能完整构建。

---

九、一个实用排查顺序

以后遇到“本地能跑，Build失败”，可以按这个顺序：

第一步：看完整Build错误。

先判断错误类型。

第二步：单独跑Type Check。

确认是否是类型问题。

第三步：检查路径和依赖。

特别是新增 import。

第四步：检查环境变量。

开发和生产配置是否一致。

第五步：确认运行环境。

浏览器端、服务端代码有没有混用。

第六步：重新Build。

确认问题真正解决。

---

最后

Codex修改代码后本地能跑、打包却失败，本质上通常不是：

“开发环境骗了你。”

而是开发模式和正式构建关注的检查维度不同。

排查时不要只盯着页面是否正常。

更应该依次确认：

类型 → 路径 → 环境变量 → 构建配置 → 生产Build。

真正完成一个开发任务，不只是：

代码在本地能运行。

还应该做到：

项目能够稳定通过完整构建流程。

---

持续更新 Codex、大模型开发与 AI 编程实战内容，更多技术内容和稳定订阅渠道欢迎搜索关注「仙逆GPT」。