JavaScript / TypeScript / 系统课时
集成代码检查工具
集成代码检查工具
把类型检查、代码检查和格式校验串进同一条项目命令,可以让本地开发与持续集成都执行同一套质量门槛。本节完成一条可复用的 verify 流程,并说明哪些任务只检查、哪些任务可以在本地自动修复。
学习目标
- 用 npm scripts 组合 TypeScript、ESLint 与 Prettier 检查
- 区分本地修复命令与 CI 中的只读检查命令
- 在持续集成中复用同一条质量检查入口
设计统一的检查入口
工程里最容易失控的情况不是“没有工具”,而是每个人运行的命令不同。建议把单项检查收敛到 package.json,再提供一个统一入口:typecheck 只做类型检查,lint 只做静态规则检查,format:check 只验证格式,verify 顺序执行三者。
下面是一个可直接放入项目的脚本配置。它假设项目已经安装并配置 TypeScript、ESLint 和 Prettier。
{
"scripts": {
"typecheck": "tsc --noEmit",
"lint": "eslint . --max-warnings=0",
"format:check": "prettier . --check",
"format:write": "prettier . --write",
"verify": "npm run typecheck && npm run lint && npm run format:check"
}
}verify 使用 && 串联任务:前一项失败时立即停止,CI 日志能直接看到最早出现的问题。format:write 只供开发者主动修复格式,不应作为 CI 的检查步骤,因为 CI 不应该偷偷修改仓库内容。

在本地验证脚本
先运行统一入口,而不是分别手动执行三条命令。这样开发者本地看到的结果与 CI 最接近。
npm run verify预期输出
> <VALUE> verify
> npm run typecheck && npm run lint && npm run format:check
> <VALUE> typecheck
> tsc --noEmit
> <VALUE> lint
> eslint . --max-warnings=0
> <VALUE> format:check
> prettier . --check
Checking formatting...
All matched files use Prettier code style!其中 <VALUE> 代表 npm 输出中的项目名、版本或脚本前缀,实际值可能不同。命令整体退出码为 0 才表示三项检查全部通过;TypeScript 报错、ESLint warning 被 --max-warnings=0 拦截,或 Prettier 检测到格式差异,都会让流程失败。
接入持续集成
CI 不需要重新拼装质量规则,只调用仓库里的 verify。以下 GitHub Actions 片段展示最小接法;它安装锁定依赖后执行与本地完全相同的命令。
name: quality
on:
pull_request:
push:
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run verify生效行为是:任意一步返回非零退出码,verify job 就失败,后续合并策略可以据此阻止未通过检查的变更。验证时提交一个故意违反 ESLint 规则或格式规则的分支,确认 CI 失败;修复后再次推送,job 应恢复通过。
处理常见集成问题
如果本地通过而 CI 失败,先检查 Node.js 版本和依赖安装方式是否一致。CI 应优先使用 npm ci 按锁文件安装,避免因依赖漂移导致规则或编译行为变化。
如果格式检查在不同系统反复失败,检查仓库的换行符策略,并让 Prettier 配置与 .gitattributes 保持一致。不要在 CI 中改成 prettier --write 掩盖问题,否则流水线可能“通过”了,但提交内容仍未真正修复。
对于大型项目,可以把三项检查拆成并行 job 提高反馈速度;但仍建议保留 npm run verify 作为本地统一入口。无论串行还是并行,关键是让工具配置只有一份,让开发者和 CI 使用同一套规则。