JavaScript / TypeScript / 系统课时

集成代码检查工具

集成代码检查工具

把类型检查、代码检查和格式校验串进同一条项目命令,可以让本地开发与持续集成都执行同一套质量门槛。本节完成一条可复用的 verify 流程,并说明哪些任务只检查、哪些任务可以在本地自动修复。

学习目标

  • 用 npm scripts 组合 TypeScript、ESLint 与 Prettier 检查
  • 区分本地修复命令与 CI 中的只读检查命令
  • 在持续集成中复用同一条质量检查入口

设计统一的检查入口

工程里最容易失控的情况不是“没有工具”,而是每个人运行的命令不同。建议把单项检查收敛到 package.json,再提供一个统一入口:typecheck 只做类型检查,lint 只做静态规则检查,format:check 只验证格式,verify 顺序执行三者。

下面是一个可直接放入项目的脚本配置。它假设项目已经安装并配置 TypeScript、ESLint 和 Prettier。

json
{
  "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 中共用同一条质量门槛

在本地验证脚本

先运行统一入口,而不是分别手动执行三条命令。这样开发者本地看到的结果与 CI 最接近。

bash
npm run verify

预期输出

text
> <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 片段展示最小接法;它安装锁定依赖后执行与本地完全相同的命令。

yaml
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 使用同一套规则。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

集成代码检查工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通