构建环境与持续集成：为什么你电脑上能跑还不够
你把收藏功能交给同事，他安装以后却打不开。原来你电脑用的是一个 Node 版本，他用另一个；你本地还有没提交的文件。要交付软件，不只需要源代码，还要让别人按照明确步骤得到能运行的结果。
1. 先分清源码、依赖和构建结果
源码是我们编辑的程序；依赖是程序使用的外部库；构建将这些输入处理成目标环境可以运行的产物。不同技术栈的构建动作不同，可能包括编译、打包、生成资源或检查类型。
不是所有项目都需要同样的打包过程。一个小 Node 脚本可能直接运行；一个网页应用可能需要把源码组织成浏览器资源与服务端产物。关键是说明实际步骤，而不是为了显得工程化强行增加工具。
2. 把运行条件写下来
这个知识库声明 Node.js 版本范围，并提供锁文件。锁文件记录具体依赖解析结果，能减少不同安装时间带来的差异；它不能独自保证所有机器生成的文件字节完全一致，操作系统、构建工具、环境变量和外部下载也可能影响结果。
在本项目根目录，常见检查命令是：
npm ci
npm run typecheck
npm test
npm run build
npm ci 使用已有锁文件安装，在清洁安装中更适合复现；它会移除已有 node_modules，且要求锁文件与 package.json 相符。执行前要确认当前目录正确。环境变量里的秘密另行配置，不能为了方便运行就写进公开仓库。
3. 让机器对每次改动重复检查
持续集成简称 CI。其核心是经常把小改动合入共享主线，并用自动构建和检查尽早发现整合问题。安装了 CI 服务但几周才合一次代码，仍会积累很大的整合风险。
一个适合入门的检查顺序是：安装确定的依赖、快速静态检查、关键测试、生产构建。较慢的测试可以另设阶段，但必须清楚哪些检查是合并或发布的门槛。检查失败时，要先判断是产品缺陷还是环境问题，不能默认重试到绿色即可。
4. 先把这次课程的例子自动跑起来
仓库附带的收藏规则示例只依赖 Node.js。进入 examples/software-engineering，执行：
node --test favorites.test.mjs
它应报告全部测试通过。现在把“重复保存”实现故意改坏，再执行一次，应看到明确失败。恢复代码以后再次执行，结果回到通过。这个小实验帮助理解自动检查怎样阻止一个已知缺陷混入代码，而无需先掌握流水线配置语言。
本地通过后，才把同样命令放进 CI。不要让本地和 CI 跑两套完全不同、又没有说明的验证步骤，否则同一个“通过”会表达不同含义。
5. 缓存帮助加速，不能替代正确输入
缓存依赖可以减少重复下载，但缓存键应反映锁文件、运行时或平台等必要差异。缓存失效时应能重新安装，不能只有某个旧缓存存在项目才能成功构建。
构建结果也应关联提交 ID 与环境配置版本。上线出错后，我们才能回答现在跑的是哪份代码。发布前临时手工改服务器文件，会让仓库、构建产物和线上行为分离，后续排查会很困难。
练习与参考答案
CI 全绿能否证明线上一定正常？不能。检查只覆盖已经写出的规则和环境；生产权限、数据规模、网络、外部服务仍可能不同。CI 是重要证据，之后仍要做发布验证和运行观察。
阅读依据
再看流水线运行的第三方代码
npm 锁文件管理项目依赖，不会自动固定 GitHub Actions 工作流里所有第三方步骤。审查一次流水线时，还要看 action 来自哪个仓库、运行哪个版本、获得了什么权限。
当前 GitHub 官方说明优先介绍工作流依赖锁文件，但该能力仍处于公开预览。它覆盖已接入工作流的 action 及其传递依赖；可复用工作流内部的依赖由其所在仓库的锁文件管理，不能假定一份锁文件覆盖所有仓库。尚不能采用时，再将 action 固定到确认来源的完整提交 SHA。即使固定版本，也要审查源码、控制令牌权限，并定期评估更新。练习可以从只读的检查任务开始，说明为什么它不需要生产发布凭据。
本节的核验依据
2026-10-25 查阅。下面的链接支持本节的机制说明；练习场景和选型建议是本教程的教学设计。