Claude Code 修改项目后编译通过，真正启动却报错，是开发中很常见的一类落差。编译器主要检查语法、类型和静态依赖，运行阶段还要面对环境变量、数据库、缓存、端口、文件权限、网络和真实数据。编译成功只能证明代码跨过了静态门槛，不能替代启动验证和集成测试。排查时应保护现有差异，从第一条运行时错误入手，而不是为了“能启动”继续大范围改代码。

一、先保存编译成功的基线

在处理运行错误前记录编译命令、运行时版本、工作目录和成功输出，并查看 Git 差异。把当前修改导出补丁或提交到临时分支，防止后续排查把已通过编译的状态弄丢。不要因为运行失败就立即回滚全部修改，故障可能来自本机服务未启动。

确认编译和运行使用的是同一份代码、同一配置与同一构建产物。多模块项目可能编译了一个包，却启动了另一个旧目录；容器可能仍使用缓存镜像。先核对产物时间和启动路径，再分析代码。

二、抓住第一条异常，不要只看最后退出信息

运行日志结尾常常只有进程退出或服务启动失败，真正原因在更早的第一条异常。保留完整日志到文件，查找首个 error、exception 或拒绝连接，再向前后读取上下文。后续几十条错误可能都是连锁反应。

记录异常类型、文件位置、请求地址和退出码，但对令牌、连接串和用户数据脱敏。让 Claude Code先解释证据并提出最小验证步骤，不要直接要求“修好所有报错”。范围越清楚，误改业务逻辑的概率越低。

三、环境变量是编译与运行之间的第一道差异

编译阶段可能不需要数据库密码、服务地址或功能开关，运行时才读取。检查必需变量是否存在、是否为空、名称是否匹配以及由哪一层注入。不要打印真实值，可以只报告存在性或脱敏特征。

从终端、编辑器、Claude Code、容器和系统服务启动，继承的环境可能不同。人工运行成功而 Claude 执行失败，应比较启动方式与工作目录。刚修改变量后要重启相关进程，旧终端不会自动刷新。

四、确认依赖服务已启动且版本匹配

数据库、缓存、消息队列、对象存储模拟器和后端 API 都可能在编译时缺席。运行前检查服务是否启动、端口是否监听、健康检查是否通过。连接被拒绝通常是服务未运行或地址错误，认证失败才进一步检查账号权限。

不要为了通过本地测试而连接真实生产服务。使用开发或测试实例，数据可以重建，权限保持最小。若项目通过 Docker Compose 或任务脚本启动依赖，应使用仓库提供的标准入口，避免手工启动出不同版本。

五、检查端口、文件路径和权限

端口被占用会让应用启动失败，配置中的相对路径会随工作目录变化，上传目录和缓存目录则可能没有写权限。先确认占用进程和路径的绝对位置，不要随意结束未知系统进程或给整个目录开放完全控制。

Windows、WSL 和容器对路径格式、大小写与权限的处理不同。在一个环境编译、另一个环境运行时，静态阶段未必能发现这些差异。统一运行环境，或把平台差异写进启动脚本和文档。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成代码修改、测试和审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：
https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

六、编译缓存和旧产物也会制造假象

增量编译可能复用旧输出，开发服务器也可能没有真正重启。确认当前进程已经停止，再按项目推荐方式清理必要缓存并重新构建。不要一开始就删除所有依赖和缓存；先从构建产物、进程与镜像标签入手，减少无谓重装。

容器项目要确认镜像确实包含最新代码，挂载目录没有覆盖构建结果。前端项目还要区分构建时变量与运行时变量，有些值在打包时已经写入，启动后修改环境不会改变旧产物。

七、用集成测试覆盖运行时边界

单元测试可以在没有真实服务的情况下通过，集成测试才会验证数据库连接、迁移、序列化、认证和跨模块调用。先运行最小集成路径，例如启动服务、访问健康检查、完成一次低风险读写，再扩展到完整套件。

集成测试失败时保留依赖服务版本、初始化数据和环境说明。不要为了变绿而把所有外部调用都 mock 掉，否则恰好绕开了需要发现的运行问题。合理做法是单元测试隔离逻辑，集成测试验证边界，两者各自承担职责。

八、检查数据库迁移和数据兼容

代码编译通过，但启动时查询了不存在的字段或旧数据格式，就会立刻失败。核对迁移是否执行、数据库版本是否符合项目要求、当前连接是否指向正确环境。迁移前备份重要数据，不要让 Claude Code在未确认目标数据库时自动执行破坏性操作。

对于团队共享开发库，先查看迁移状态，再按流程应用。若新代码需要兼容滚动发布，还应考虑旧服务与新结构并存的时间窗口。运行错误有时不是单机配置，而是部署顺序问题。

九、让 Claude Code 做小步修复

先让它根据首个异常列出假设和验证命令，再由结果决定是否改代码。配置缺失就补文档或安全默认值，服务未启动就修开发脚本，只有确认代码逻辑错误时才修改业务模块。每次修改后重新编译，并重复最小运行验证。

限制修改范围，检查 Git 差异，防止工具顺手重构无关文件。运行错误消失后，还要确认日志没有新的警告、接口返回符合预期、进程可以正常关闭。仅“没有崩溃”不等于功能正确。

十、建立完整验收而不是停在编译通过

一个可交付结果至少包括：干净环境能够安装依赖，项目编译通过，必要服务可启动，环境配置有安全示例，最小集成测试通过，关键功能完成冒烟验证。CI 中也应把这些阶段分开报告，方便快速定位失败层级。

以后遇到编译成功但运行报错，按“保存基线、首个异常、环境变量、依赖服务、端口路径、构建产物、集成测试、数据迁移”的顺序排查。这个顺序能让 Claude Code围绕证据行动，把静态成功推进成真正可运行、可验证的工程结果。