本地开发与 CI 的一致性
本地能跑、CI 挂掉(或者反过来)——这是协作里最浪费时间的报错之一。它的根因通常不在代码,而在环境:操作系统、工具链、依赖、环境变量、缓存,任何一处不同,都会让同一段代码在两个地方表现不同。这个问题在 AI 参与开发后被放大了:AI 往往在本地或沙箱里把代码跑通,却不知道 CI 用的是什么环境;等流水线一挂,来回定位的成本全落在人身上。前面几篇分别收敛了版本、依赖、命令与卡口,本文处理最后一道裂缝:本地开发与 CI 的一致性。它承接命令收口与检查左移,系列最后一篇是 AI 生成代码的评审清单。完整导航见文末。
一、不一致从哪来
把「本地能跑、CI 挂掉」拆开看,差异基本落在这几类:
- 操作系统差异:本地可能是 macOS,CI 是 Linux。文件系统大小写、路径分隔符、系统库版本都不同。
- 工具链版本差异:本地装了某个版本的编译器 / 运行时,CI 装的是另一个版本;本地用全局命令,CI 里没有。
- 依赖与缓存差异:本地
node_modules、构建缓存是攒出来的;CI 每次都是干净环境,缺一个包就挂。 - 环境变量与外部服务差异:本地连着某个数据库、某个代理,CI 里没有;
*.env文件本地有、仓库里没有。 - 「脏」与「干净」的差异:本地环境里积累了大量未提交、未声明的状态,CI 每次从零开始——本地能跑,是因为它「记得」你手动做过的步骤。
这些差异的共同点是:它们都没有被写进仓库。没有被写进仓库的约定,换一台机器就消失;AI 读不到,也一样会踩。
二、原则:CI 是同一份定义在干净机器上的执行
收敛不一致,最核心的一条心智模型是:
CI 不是「另一套环境」,而是同一份定义在干净机器上的执行。
本地和 CI 的差别应该只在于「干净程度」,而不在于「定义不同」。按这个原则,收敛顺序通常是:
- 命令同源:CI 调用的,就是本地开发用的那组命令(见命令收口)。
- 工具链同源:运行时、编译器、核心工具的版本被显式锁定(见各语言环境配置)。
- 依赖同源:依赖版本由 lock 文件固定,CI 用冻结安装,而不是临时解析(见依赖治理)。
- 环境定义同源:当上面三层仍不够时,把整个环境写成一份可复现的定义——容器镜像。
前三层做完,绝大多数「本地能跑 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 不上(或反过来),把一致性问题从一层挪到另一层。
六、落地清单
- 让 CI 调用本地同一组命令,不自己拼步骤。
- 锁定运行时与工具链版本,CI 装指定版本而非最新版。
- 依赖按 lock 文件冻结安装,lock 文件入库。
- 显式列出环境变量与外部服务,CI 用服务容器或替身提供。
- 处理平台差异:路径、换行、大小写。
- 环境复杂时引入容器 / Dev Container,本地与 CI 用同一份定义。
- 把「CI 是什么环境」写进项目说明,让 AI 也能读到。
参考链接
- VS Code Dev Containers 文档:开发容器与
devcontainer.json。 - GitHub Codespaces 文档:基于 dev container 的云端开发环境。
- Dev Container 规范:开放的 dev container 标准。
- Docker 文档:容器与镜像。
系列文章
- 总述:代码规范工具到底在解决什么问题
- 环境配置:Node.js · Go · C/C++
- 协作机制:给 AI 编码助手补上项目上下文 · 把检查左移到提交前 · 依赖治理 · 命令收口
- 一致性与评审:本地开发与 CI 的一致性 · AI 生成代码的评审清单
