本地开发与 CI 的一致性

本地能跑、CI 挂掉(或者反过来)——这是协作里最浪费时间的报错之一。它的根因通常不在代码,而在环境:操作系统、工具链、依赖、环境变量、缓存,任何一处不同,都会让同一段代码在两个地方表现不同。这个问题在 AI 参与开发后被放大了:AI 往往在本地或沙箱里把代码跑通,却不知道 CI 用的是什么环境;等流水线一挂,来回定位的成本全落在人身上。前面几篇分别收敛了版本、依赖、命令与卡口,本文处理最后一道裂缝:本地开发与 CI 的一致性。它承接命令收口与检查左移,系列最后一篇是 AI 生成代码的评审清单。完整导航见文末。

一、不一致从哪来

把「本地能跑、CI 挂掉」拆开看,差异基本落在这几类:

  • 操作系统差异:本地可能是 macOS,CI 是 Linux。文件系统大小写、路径分隔符、系统库版本都不同。
  • 工具链版本差异:本地装了某个版本的编译器 / 运行时,CI 装的是另一个版本;本地用全局命令,CI 里没有。
  • 依赖与缓存差异:本地 node_modules、构建缓存是攒出来的;CI 每次都是干净环境,缺一个包就挂。
  • 环境变量与外部服务差异:本地连着某个数据库、某个代理,CI 里没有;*.env 文件本地有、仓库里没有。
  • 「脏」与「干净」的差异:本地环境里积累了大量未提交、未声明的状态,CI 每次从零开始——本地能跑,是因为它「记得」你手动做过的步骤。

这些差异的共同点是:它们都没有被写进仓库。没有被写进仓库的约定,换一台机器就消失;AI 读不到,也一样会踩。

二、原则:CI 是同一份定义在干净机器上的执行

收敛不一致,最核心的一条心智模型是:

CI 不是「另一套环境」,而是同一份定义在干净机器上的执行。

本地和 CI 的差别应该只在于「干净程度」,而不在于「定义不同」。按这个原则,收敛顺序通常是:

  1. 命令同源:CI 调用的,就是本地开发用的那组命令(见命令收口)。
  2. 工具链同源:运行时、编译器、核心工具的版本被显式锁定(见各语言环境配置)。
  3. 依赖同源:依赖版本由 lock 文件固定,CI 用冻结安装,而不是临时解析(见依赖治理)。
  4. 环境定义同源:当上面三层仍不够时,把整个环境写成一份可复现的定义——容器镜像。

前三层做完,绝大多数「本地能跑 CI 挂掉」就已经消失;第四层是给复杂环境准备的,不必一步到位。

三、逐层收敛

3.1 命令同源

CI 里最容易出现的问题是:本地用 make test,CI 里写了一串 npm run xxx && go test ...。两边逻辑一旦分叉,行为就可能不同。

做法很直接:CI 的每一步都调用项目定义好的命令,而不是自己拼。命令定义在仓库里,本地和 CI 共用同一份。

3.2 工具链同源

本地和 CI 用不同版本的运行时,是最隐蔽的不一致来源。做法是:

  • 把版本写进仓库:Node 的版本文件 / packageManager 字段、Go 的 go.mod 与 toolchain 行、C/C++ 的工具链版本约束。
  • CI 里安装指定版本,而不是「装最新的」。
  • 本地也通过版本管理工具对齐到同一份声明,而不是各自装各自的。

3.3 依赖同源

CI 里最常见的两个词是 --frozen-lockfile(npm / Yarn / pnpm)和 -mod=readonly(Go)。含义一致:只按 lock 文件安装,不允许现场解析版本。

配合 lock 文件入库、CI 不写缓存产物,就能保证本地和 CI 用的是同一份依赖快照。

3.4 环境变量与外部依赖

本地依赖的外部服务(数据库、缓存、对象存储)往往靠「我机器上正好有」运行。收敛方式是:

  • 把需要的环境变量列成清单(通常给一份示例文件,如 .env.example),而不是散落在个人机器上。
  • CI 里用服务容器 / 内存模拟 / 测试替身提供同类依赖,让测试不依赖「某台机器上正好装着什么」。
  • 把「本地连着什么」写进项目文档,让 AI 也能读到。

3.5 平台差异

有些差异是平台本身带来的,需要在代码和配置里显式处理:

  • 路径用跨平台的方式拼接,不写死分隔符。
  • 文件名避免仅大小写不同的命名。
  • 换行符由编辑器配置 / .gitattributes 统一,而不是靠个人习惯。
  • 需要特定系统能力时,先在文档里写明,而不是让某台机器「碰巧满足」。

四、什么时候上容器

当「版本 + 命令 + 依赖」三层仍不足以描述环境时(多服务、系统级依赖、复杂构建工具链),可以把整个环境写成一份可复现的定义:

  • 容器镜像:把操作系统、运行时、系统库、工具链都打进镜像,本地和 CI 用同一个镜像。一致性最强,代价是镜像本身的维护。
  • Dev Container:项目里放一份 .devcontainer/devcontainer.json,定义开发环境(可基于镜像、Dockerfile 或 Compose)。VS Code 的 Dev Containers 扩展会按这份定义起容器,打开项目即进入一致环境。它遵循开放的 Dev Container 规范,因此不绑定单一工具。
  • 云端开发环境:GitHub Codespaces 这类服务直接读取同一份 .devcontainer 定义,在云端开一个一致的容器。对「换台电脑就能干活」和「让 AI 在一致环境里跑」都友好。

一句话判断:如果「装环境」这件事本身已经复杂到需要写文档,那就值得写成定义;否则先靠版本锁定和 lock 文件解决。 容器不是银弹——本地用 Docker、CI 却不用,反而会多出一层新的不一致。

五、反模式

  • CI 单独一套脚本,本地另一套命令,两边分叉。
  • 本地用全局工具,CI 装另一个版本,行为不同。
  • 依赖本地缓存 / 构建产物,CI 从零开始时缺东西。
  • 把「本地能跑」当成「应该能跑」,不写环境声明。
  • 忽略平台差异,等 CI 报错了再逐条打补丁。
  • 本地上容器、CI 不上(或反过来),把一致性问题从一层挪到另一层。

六、落地清单

  1. 让 CI 调用本地同一组命令,不自己拼步骤。
  2. 锁定运行时与工具链版本,CI 装指定版本而非最新版。
  3. 依赖按 lock 文件冻结安装,lock 文件入库。
  4. 显式列出环境变量与外部服务,CI 用服务容器或替身提供。
  5. 处理平台差异:路径、换行、大小写。
  6. 环境复杂时引入容器 / Dev Container,本地与 CI 用同一份定义。
  7. 把「CI 是什么环境」写进项目说明,让 AI 也能读到。

参考链接

系列文章


本地开发与 CI 的一致性
https://bubao.github.io/posts/3f7b2d9e.html
作者
一念
发布于
2026年11月21日
许可协议