一句话总答

CI 失败时，我一般先定位失败阶段，再结合日志判断是环境问题、依赖问题还是代码问题，最后在本地或 CI 环境复现并修复。

---

一、第一步：定位“失败在哪一步”（最关键）

我会先看 CI Pipeline 的阶段：

• install 阶段？
• lint / test 阶段？
• build 阶段？
• deploy 阶段？

👉 不看日志先看阶段，能直接砍掉 70% 可能性。

---

二、第二步：根据阶段分类排查

① install 失败（依赖问题）

常见原因：

• 依赖版本冲突
• lock 文件不一致
• registry / 网络问题

我会：

• 对比本地和 CI 的 Node / pnpm 版本
• 检查 package-lock / pnpm-lock
• 看是否有私有包权限问题

---

② lint / typecheck 失败（代码问题）

特征：

• 本地没跑
• CI 强校验

我会：

• 本地执行同样的 lint / typecheck 命令
• 对齐 CI 的参数和配置
• 修复规则或补齐类型

👉 这类问题通常是流程没跑全导致的。

---

③ test 失败（环境差异）

常见：

• 时区
• 环境变量
• mock 不完整

我会：

• 检查 CI 是否缺少必要的 env
• 本地用相同命令复现
• 补 mock 或调整测试隔离

---

④ build 失败（最常见）

比如：

• 内存不足
• 构建工具版本不一致
• 静态资源路径错误

我会：

• 对比 CI 和本地构建环境
• 检查构建日志的首个 error
• 必要时本地用 Docker 模拟 CI 环境

---

⑤ deploy 失败（非代码）

常见：

• 权限
• 网络
• 资源不存在

我会：

• 检查部署账号权限
• 看目标环境状态
• 回滚到上一版本

---

三、第三步：复现问题（体现工程能力）

尽量在本地复现 CI 的环境和命令，而不是只在 CI 上反复试。

做法：

• 使用相同 Node / pnpm 版本
• 复制 CI 命令到本地执行
• 必要时用 Docker 跑 CI 环境

👉 能复现，问题就解决了一半

---

Why does it pass locally but fail in CI?

一句话总答

本地通过，CI 失败，通常是因为两者的运行环境、依赖、配置或资源不同，而不是代码本身的问题。

---

二、最常见原因（按工程经验列）

1️⃣ 环境差异

差异类型	举例	解决思路
Node / pnpm / npm 版本	本地 18.16，CI 18.14	固定 CI 环境版本或用 .nvmrc / Docker
OS 差异	本地 macOS，CI Ubuntu	注意大小写文件路径、依赖系统库
环境变量	本地有 .env，CI 没有	CI 配置 secrets / env
时区 / locale	测试时间相关逻辑	统一时区或 mock 时间

---

2️⃣ 依赖差异

• package-lock.json / pnpm-lock.yaml 没同步
• CI 拉取私有库失败
• 可选依赖在 CI 缺失

排查方法：

• 用 CI 完整命令本地复现
• 确认 lock 文件与 CI 一致
• 固定依赖版本

---

3️⃣ 构建 / 测试配置差异

• lint / typecheck 在 CI 运行 stricter
• 测试用例依赖本地 mock / DB
• 构建工具参数差异

排查方法：

• 同步 CI build 命令到本地
• 用 Docker 模拟 CI 环境

---

4️⃣ 资源或权限问题

• CI 内存不足 → webpack build 失败
• CI 无权限写缓存 / 上传文件
• 外部 API 在 CI 无访问权限

排查方法：

• 查 CI 日志错误原因
• 增加 CI 资源或 mock 权限依赖

---

5️⃣ 时间 / 并发 / 随机因素

• 测试依赖顺序或网络请求
• CI 并行跑测试 → race condition
• flaky test

解决方法：

• 修复测试顺序 / mock 网络
• 增加 retry 或稳定化测试