代码规范与检查链

学习目标

读完本课你能：说清本站检查链的每一环测什么、按什么顺序跑；区分「能自动修复的样式问题」和「必须人判断的语义问题」；让检查命令在任何干净环境（新机器、半年后的你自己）行为一致。

问题场景

半年后你换了台电脑，clone 项目跑 npm run lint，蹦出 40 个报错：30 个是引号分号，10 个是真问题——但你已经分不清哪些是老债哪些是新伤。更烦的是，另一台机器跑同一命令结果还不一样：那边全局装过不同版本的 ESLint。规范检查的价值不在「找出错误」，在于同一份代码在任何机器上得到同一个答案。

核心解释

本站的检查链就四条命令，全在 package.json 的 scripts 里：

{
  "scripts": {
    "lint": "eslint",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "content:check": "tsx scripts/content-check.ts"
  }
}

顺序有讲究：快的、便宜的在前。 typecheck 和 lint 秒级出结果，先跑；test 要起环境，次之；content:check 依赖内容目录完整，最后。失败定位从最快的一环开始。顺带说明：本站没有独立的格式化器（Prettier 之类），样式约束由 ESLint 规则承担——个人项目一种工具够用，规则少而稳。

两类问题，两种处理：

1. 可自动修复：引号风格、分号、缩进、import 排序——eslint --fix 一键解决。特征：改法唯一、不改行为。
2. 必须人判断：类型不匹配、未使用变量（删了可能正暴露 bug）、逻辑错误。tsc --noEmit 报的错没有「自动修复」这回事——它需要你决定这里到底该是什么类型。特征：多个改法、影响行为。

判断口诀：机器能唯一确定改法的交给 --fix，需要做决定的留给人。

可复现的三个条件：

• 命令走本地 node_modules（npm run 自动把 .bin 放进 PATH），不依赖全局安装的工具；
• 依赖版本由 package-lock.json 锁定，装依赖用 npm ci（精确按锁文件装）而不是 npm install（会重新解析版本范围）；
• tsc --noEmit 只检查不产出文件，检查本身不留副作用。

示例拆解

亲手制造两类问题，感受差异：

// 问题一（语义）：typecheck 抓住，没有自动修复
const total: number = "3" + 1;
// tsc 报错：Type 'string' is not assignable to type 'number'
// 你必须决定：到底要数字相加（Number("3") + 1）还是字符串拼接

// 问题二（样式）：lint 抓住，--fix 自动修复
const flag = 'single-quoted' // 项目规则要求双引号
// eslint --fix 之后：const flag = "single-quoted";

执行链路：

npm run typecheck   # 语义层：类型系统判断
npx eslint . --fix  # 样式层：自动修复能修的，剩下的报出来人看
npm run test        # 确认修复没改行为

关键点：--fix 之后必须跑测试——自动修复「应该」不改行为，「应该」不是验证；tsc 的报错逐条读，每条都是一个需要你做的决定。

动手任务

1. 本机依次跑 npm run typecheck、npm run lint、npm run content:check，记录三条命令的输出与耗时——这就是本站的检查链基线。
2. 在任意 .ts 文件里故意写一个类型错误和一个引号问题，分别验证：typecheck 抓前者、--fix 自动修后者——确认两类问题的边界。
3. 删掉 node_modules 后用 npm ci 重建依赖，重跑检查链，确认结果与之前一致。

常见错误

• 把 --fix 当万能钥匙：它只做「改法唯一」的修复，配置过宽时有些问题也会被它「顺手」改掉——修完必须过测试。
• 依赖全局安装的工具：本机版本和别人不一致，「我这能跑」就成了悬案；一切走项目内依赖。
• 检查链只在提交前人肉跑：记不住就漏跑。至少把四条命令写进文档流程，交付前按序执行（E08 的验收报告要引用这些结果）。
• 报错积压：「先关掉这条规则以后再修」——积到下次大重构前，谁都不敢动。

检查与复盘

• 能按顺序报出四条检查命令及各自测什么
• 遇到报错能先判断：这是 --fix 能解决的样式问题，还是需要人判断的语义问题
• 干净环境重建依赖后，检查链结果与原机器一致

参考资料

• TypeScript 官方：tsconfig 参考 —— --noEmit 等编译选项的权威定义
• ESLint 官方文档 —— 规则配置与 --fix 的行为边界
• npm 官方：npm ci —— 与 npm install 的差异及适用场景