biome-tooling

Biome Tooling 介绍的是 Biome——一个用于 JavaScript/TypeScript 代码格式化与 Linting 的快速一体化工具链。

用途与定位

Biome 是一个性能优秀的工具链，提供格式化（替代 Prettier）和 Linting（替代 ESLint）。其特点包括：用 Rust 编写，速度较快；零配置（提供合理的默认值）；单一工具（避免工具之间的冲突）。

安装

使用 npm install --save-dev @biomejs/biome 安装。

配置

在项目根目录创建 biome.json，可配置 $schema、organizeImports、linter、formatter 以及 javascript.formatter 等选项，具体字段与示例值以资料中的 JSON 为准。

Package.json Scripts

可配置 format（就地格式化所有文件）、format:check（检查格式，用于 CI）、lint（显示 Linting 错误）、lint:fix（修复可自动修复的问题）、check（格式化 + Linting + 整理 import，推荐）、ci（不修改文件地检查所有内容，用于 CI）。

基本用法

格式化文件：npm run format；或针对特定文件 npx biome format --write src/；不修改地检查 npx biome format src/。

Linting 文件：npm run lint；修复 npm run lint:fix；针对特定文件 npx biome lint src/。

一体化检查：npm run check 执行格式化、Linting 与 import 整理；npm run ci 不修改文件地检查（用于 CI）。

文件配置

可通过 files.include 与 files.ignore 包含/排除文件；可用 overrides 针对特定文件覆盖规则。

Linter 规则

支持启用推荐规则（rules.recommended），并可自定义规则组，涵盖 Complexity、Correctness、Performance、Security、Style、Suspicious 等类别，资料中列出了各类别下的具体规则名称（如 noExcessiveCognitiveComplexity、noUnreachable、noDangerouslySetInnerHtml、noExplicitAny 等）。

Formatter 配置

基础选项包括 enabled、formatWithErrors、indentStyle、indentWidth、lineWidth、lineEnding；JavaScript 专属选项包括 quoteStyle、jsxQuoteStyle、quoteProperties、trailingComma、semicolons、arrowParentheses、bracketSpacing、bracketSameLine。

Import 整理

启用 organizeImports 后，Biome 会移除未使用的 import、排序 import，并对 import 分组（内置、外部、内部）。

VSCode 集成

从 VSCode marketplace 安装 “Biome” 扩展；在 VSCode 设置中可将默认格式化器设为 biomejs.biome，并开启保存时格式化、保存时代码操作（quickfix.biome、source.organizeImports.biome），以及针对 javascript、typescript、typescriptreact 的默认格式化器设置。

Git Hooks

可使用 Husky + lint-staged：安装 husky 与 lint-staged，在 lint-staged 中对 *.{js,jsx,ts,tsx} 执行 biome check --apply --no-errors-on-unmatched，并通过 npx husky init 与 echo "npx lint-staged" > .husky/pre-commit 设置 pre-commit。

CI/CD 集成

给出了 GitHub Actions 与 GitLab CI 的示例配置，均通过 npm ci 后运行 npm run ci（即 biome ci .）。

从 ESLint + Prettier 迁移

步骤包括：卸载旧工具（eslint、prettier 及相关 @typescript-eslint 包）、删除旧配置文件（.eslintrc.js、.prettierrc、.prettierignore、.eslintignore）、安装 Biome、通过 npx @biomejs/biome init 初始化配置、更新 scripts（用 check 与 ci 替代 lint 与 format）。

常见模式

包括忽略生成文件（如 *.generated.ts、build/、.sst/、coverage/）；生产环境严格模式（将 noExplicitAny、noArrayIndexKey 设为 error）；测试文件放宽规则（关闭 noExplicitAny、noExcessiveCognitiveComplexity 等）。

最佳实践

在 pre-commit 钩子中使用（npx lint-staged）；在 CI/CD 中运行 npm run ci 并在检查不通过时使构建失败；配置编辑器保存时格式化；保持配置最小化（从默认值开始，仅配置需要的项）；与 TypeScript 一起使用时可通过 javascript.parser.unsafeParameterDecoratorsEnabled 等选项配置。

性能收益

资料给出对比：格式化 5000 个文件时 Prettier 约 30 秒、Biome 约 1 秒；Linting 5000 个文件时 ESLint 约 45 秒、Biome 约 2 秒。

故障排查

涵盖 “Command not found: biome”（本地安装或使用 npx）、合法代码出现 “Parse errors”（检查 biome.json 的 parser 选项）、VSCode 不格式化（安装扩展、确认默认格式化器、重载 VSCode）、与现有工具冲突（卸载 ESLint 与 Prettier）。

高级配置

支持通过 extends 继承共享配置（如 @company/biome-config）、按项目覆盖设置，以及自定义规则严重级别（如为 noExplicitAny 设置 level 与 fix）。

Biome 与 ESLint + Prettier 对比

资料以表格形式比较了 Speed（Biome 快 25 倍）、Setup（单一工具 vs 两个工具加配置）、Conflicts（无 vs 可能）、Rules（不断增长 vs 丰富）、Plugins（有限 vs 很多）、Memory（较低 vs 较高）等方面。

何时使用 Biome

适合：启动新项目、重视速度、希望更简单的工具链、可以接受有主见的默认值。需要考虑替代方案：需要特定 ESLint 插件、有复杂的自定义规则、团队已深度投入 ESLint。

迁移检查清单

包括安装 Biome、创建 biome.json、更新 package.json scripts、移除 ESLint/Prettier、更新 pre-commit 钩子、更新 CI/CD 流水线、配置 VSCode、在现有代码上测试、更新团队文档。

技能介绍