第 5 章 · check 与自动修复

5.1 check 是什么

biome check 是 Biome 提供的复合命令——等价于依次跑：

biome format
biome lint
organizeImports

默认只报告问题，退出码体现是否有问题。加 --write 会尝试把能自动修复的都改掉。

biome check ./src              # 只报告
biome check --write ./src      # 安全修复
biome check --write --unsafe ./src  # 安全 + 不安全修复

5.2 安全修复 vs 不安全修复

Biome 把每条规则的 auto-fix 分为两档：

Safe fix（安全修复）: 修改前后的代码语义保证等价——格式化、import 排序、var → const、!= null → !== null 等。--write 会应用。
Unsafe fix（不安全修复）: 语义可能有细微差别（虽然多数仍然正确）。例如 forEach → for...of 会改变抛错穿透行为；删除未使用变量可能误删副作用代码。要 --unsafe 才应用。
No fix（不可修）: 规则没有自动修复，需要人工。

--unsafe 不是 yolo

不要无脑在 CI 用 unsafe。建议流程：本地手动跑一次 biome check --write --unsafe，仔细 review diff，再提交。

5.3 查看修复预览：--diagnostic-level

# 只显示 error 级别（过滤掉 info/warn 噪声）
biome check --diagnostic-level=error ./src

# 看每个 diagnostic 的完整上下文
biome check --verbose ./src

5.4 典型工作流

日常开发

VSCode 保存时 format（第 7 章配置）
终端写代码间隙随手 pnpm lint（= biome check）

提交前

biome check --write .
git add -u
git commit -m "feat: xxx"

CI

biome ci .   # 严格模式，见第 8 章

5.5 lint-staged 集成

lint-staged 在 git commit 时只对本次暂存的文件跑命令，避免对整个仓库全量格式化。

# package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,css}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

搭配 husky 的 pre-commit：

# .husky/pre-commit
npx lint-staged

--no-errors-on-unmatched 重要——当本次提交没有 Biome 支持的文件时，避免报错退出。

5.6 仅处理变更文件：--changed / --staged

# 所有相对 base 分支有变更的文件（CI 常用）
biome check --changed --since=main

# 所有 staged 的文件（本地 hook 用）
biome check --staged --write

# 打开 vcs.useIgnoreFile 配合

--since 适合超大仓库

百万行 monorepo 里全量 check 也有 10 秒量级；用 --since=origin/main 只检查 PR 改动文件，能把 CI 时间拉到 1 秒内。

5.7 修复粒度：单条规则开火

# 只跑某条规则（临时 audit）
biome lint --only=style/useConst ./src

# 跳过某条规则
biome lint --skip=suspicious/noExplicitAny ./src

5.8 处理大规模首次引入

给已有千文件项目接入 Biome 的常见脚本：

安装 + biome init
biome format --write . 单独一个 commit："chore: format with biome"
biome check --write . 做安全修复，再 commit
手动 review 剩余 lint 报错，逐条决定修/关/biome-ignore
最后开启 pre-commit hook 保持新代码达标

小结

biome check --write 是 Biome 的日常核心命令：一口气完成 format + lint + import 整理的安全修复；--unsafe 是大改神器但要 review；配合 lint-staged + husky 就能把代码规范内嵌进 git 工作流。下一章看如何从 ESLint/Prettier 平滑迁移过来。