React / 系统课时
构建检查与持续集成
构建检查与持续集成
这一节把类型检查、自动化测试和生产构建收敛成一条可重复执行的质量门禁。完成后,你可以在本地先复现 CI,再让代码提交在进入主分支前自动接受同样的检查。
学习目标
- 为 React + TypeScript 项目定义稳定的类型检查、测试和生产构建入口。
- 理解质量门禁的执行顺序,以及任一步失败时为什么应立即停止。
- 用同一条脚本连接本地验证与持续集成,减少“本地能过、CI 失败”的差异。
把三类检查收敛成一个入口
持续集成最重要的不是“云端又跑了一遍命令”,而是所有人使用同一组确定性检查。类型检查负责发现静态类型问题;测试负责验证行为;生产构建负责确认模块解析、资源处理和打包过程能完成。三者职责不同,不能只保留其中一个。
对于使用 Vite、TypeScript 和 Vitest 的项目,可以在 package.json 中集中定义脚本。下面是配置片段,假设相关开发依赖已经安装。
{
"scripts": {
"typecheck": "tsc --noEmit",
"test": "vitest run",
"build": "vite build",
"ci": "npm run typecheck && npm run test && npm run build"
}
}这里把生产构建放在最后:类型错误或测试失败时没有必要继续消耗构建时间。&& 还保证前一个命令返回非零退出码后,后续步骤不会执行。若项目使用 TypeScript Project References,可以按现有 tsconfig 结构把类型检查命令替换为适合该项目的 tsc -b。
让本地与 CI 执行同一条脚本
不要在 CI 配置里重新拼一套与本地不同的命令。更稳妥的做法是把安装和质量门禁放进仓库脚本,让任意 CI 平台只负责在 push 或合并请求事件上调用它。
#!/usr/bin/env bash
set -euo pipefail
# 使用锁文件安装精确依赖,避免 CI 静默改写依赖版本。
npm ci
# 任一步失败都会终止脚本,并把非零退出码交给 CI 平台。
npm run ci把脚本保存为 scripts/ci.sh 后,可以先在本地执行:
bash scripts/ci.sh预期结果
dependency install: 退出码 0
typecheck: 退出码 0,无类型错误
test: 全部测试通过,退出码 0
build: 生成 dist/,退出码 0具体测试数量、构建耗时和文件名会随项目变化;验收重点是四个阶段均返回 0。CI 平台只要把脚本的非零退出码标记为失败,就能把同一套规则变成合并门禁。

失败时先看第一个红灯
CI 同时打印很多日志时,优先处理最先失败的阶段。类型检查失败就先修类型,不要研究后面没有执行的构建;测试失败则先确认断言、环境和测试数据;只有前两项通过而构建失败时,再检查导入路径、环境变量和生产构建配置。
把门禁设成可重复而不是偶尔成功
稳定的 CI 还依赖几个工程约束:提交锁文件,使用 npm ci 而不是让流水线更新依赖;测试不要依赖本机时区、随机端口或未声明的外部服务;生产构建需要的公开环境变量应由 CI 明确提供,而不是依赖开发者电脑上的 .env.local。
当开发者在提交前运行 bash scripts/ci.sh,CI 在相同代码和锁文件上也运行同一脚本时,质量门禁就具备了可复现性。此时 CI 的价值不是替代本地检查,而是把团队约定变成每次提交都必须通过的自动规则。