shared-tooling-biome

Biome

**快速指南：**Biome 是适用于 JavaScript、TypeScript、JSX、TSX、JSON、CSS 和 GraphQL 的统一代码检查器、格式化工具和导入整理器。单个 Rust 二进制文件即可替代 ESLint + Prettier，兼容 Prettier 的程度达到 97%。使用 biome.json 进行所有配置。运行 biome check --write，即可一次性完成代码检查、格式化和导入整理。在流水线中使用 biome ci。

**当前稳定版本：**Biome v2.4.x（2026 年 3 月）。Biome v2 引入了类型感知代码检查、嵌套配置和经过改版的导入整理器。

---

<critical_requirements>

重要：使用此技能前

（必须使用 biome.json 或 biome.jsonc 进行所有配置——Biome 不使用 JavaScript 配置文件）

（必须使用 --save-exact 将 Biome 固定到确切版本——不同版本之间的 Biome 格式化结果可能有所变化）

（必须在 CI 流水线中使用 biome ci，而不是 biome check——ci 为只读命令，没有 --write 标志）

（本地开发必须使用 biome check --write——一次性运行代码检查器、格式化工具和导入整理器）

（必须在 biome.json 中包含 $schema，以便在编辑器中使用自动补全和验证）

</critical_requirements>

---

**自动检测：**Biome、biome.json、biome.jsonc、@biomejs/biome、biome check、biome lint、biome format、biome ci、biome-ignore、organizeImports、biome migrate

适用场景：

• 为 JavaScript/TypeScript 项目设置统一的代码检查器和格式化工具
• 使用单个、更快速的工具替代 ESLint + Prettier
• 为全新项目设置零配置或最简配置
• 用于重视代码检查和格式化速度的大型代码库
• 配置带有自定义分组顺序的导入整理
• 从 ESLint 和/或 Prettier 迁移到 Biome
• 使用 biome ci 设置 CI 流水线
• 使用 Biome 的 --staged 标志配置提交前钩子

不适用场景：

• 需要使用 Biome 没有对应功能的 ESLint 插件（例如特定框架的自定义插件）的项目
• 大量依赖无法复现的自定义 ESLint 规则的项目
• 需要格式化 Markdown、YAML 或 TOML 的项目（Biome 目前尚不支持这些格式）
• 运行时代码（这仅是构建时工具）
• Git 钩子框架配置（Husky/Lefthook 配置属于独立事项）
• TypeScript 编译器配置（tsconfig.json 属于独立事项）

涵盖的主要模式：

• 配置包含格式化工具、代码检查器和辅助功能设置的 biome.json
• 代码检查规则组（recommended、all、nursery）和严重级别
• 格式化工具配置（缩进样式、行宽、引号、分号）
• 使用自定义分组顺序的导入整理器
• CLI 命令：check、format、lint、ci、migrate
• 从 ESLint + Prettier 迁移
• Git 钩子集成（Husky、Lefthook、--staged 标志）
• 与 GitHub Actions 和 GitLab CI 集成
• 编辑器集成（VS Code、JetBrains）
• 抑制注释（biome-ignore、biome-ignore-all、范围抑制）
• 单体仓库的嵌套配置
• 针对特定文件的覆盖设置

---

示例

• 设置与配置 — 安装、biome.json、VS Code、单体仓库、框架配置
• 代码检查规则 — 规则组、领域、抑制、覆盖设置、导入排序
• 格式化 — 格式化工具选项、与 Prettier 的兼容性、选项映射
• CI 与 Git 钩子 — GitHub Actions、GitLab CI、Husky、Lefthook、暂存文件
• 从 ESLint/Prettier 迁移 — 自动迁移、规则映射、清理软件包

其他资源：

• CLI 快速参考 — 所有 CLI 命令、标志和配置选项表格

---

## 理念

Biome 将 lint、格式化和导入整理整合为一个工具，使用一个配置文件。它基于 Rust 构建，性能比 ESLint + Prettier 快 20 倍，同时保持 97% 的 Prettier 兼容性。

核心原则：

1. 一个工具，一个配置 — biome.json 可替代 .eslintrc、prettier.config 和导入排序插件
2. 合理的默认设置 — Biome 开箱即用，并启用推荐规则；零配置也是有效的设置方式
3. 速度即特性 — 由 Rust 驱动的二进制程序可在毫秒而非秒级处理大型代码库
4. 统一命令 — biome check --write 一次完成所有操作（lint + 格式化 + 导入整理）
5. 默认安全 — 安全修复会自动应用；不安全修复需要显式指定 --unsafe 标志

---

核心模式

模式 1：基本 biome.json 配置

每个 Biome 项目都从项目根目录下的 biome.json 开始。使用 biome init 创建初始配置，然后进行自定义。

# Install Biome (always pin exact version)
npm install --save-dev --save-exact @biomejs/biome

# Create default biome.json
npx @biomejs/biome init

// biome.json — minimal recommended setup
{
  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "linter": { "rules": { "recommended": true } },
  "assist": {
    "enabled": true,
    "actions": { "source": { "organizeImports": "on" } },
  },
}

优点： $schema 可启用编辑器自动补全，VCS 集成会遵循 .gitignore，显式设置 indentStyle: "space" 可避免 Biome 默认使用制表符，推荐规则能提供可靠的基准配置

// BAD: No schema, no VCS, relying on defaults that differ from Prettier
{ "linter": { "enabled": true } }

缺点： 缺少 $schema 会失去自动补全功能；未启用 VCS 会导致对 node_modules 进行 lint；Biome 默认使用制表符，这会让从 Prettier 迁移的用户感到意外

完整示例： 请参阅 examples/core.md，其中包含适用于生产环境的 biome.json，以及覆盖配置、框架配置和 monorepo 设置。

---

模式 2：Linter 规则配置

Biome 提供 8 个分组中的 459+ 条规则（accessibility、complexity、correctness、nursery、performance、security、style、suspicious）。规则默认设为 recommended，即经过精选的一组安全且稳定的规则。严重级别包括："off"、"on"、"info"、"warn"、"error"。完整的规则分组和严重级别表请参阅 reference.md。

Domains（特定技术的规则）

Biome v2 引入了按技术对规则分组的 domains。Domains 会根据 package.json 中的依赖项自动检测。

{ "linter": { "domains": { "react": "recommended", "test": "recommended" } } }

完整示例： 请参阅 examples/linting.md，了解规则配置、抑制、覆盖配置和导入排序。

---

模式 3：格式化程序配置

Biome 的格式化程序实现了 97% 的 Prettier 兼容性。全局设置适用于所有语言；特定语言的设置会覆盖全局设置。Biome 默认使用制表符 — 从 Prettier 迁移时，请显式设置 indentStyle: "space"。

{
  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
  "javascript": {
    "formatter": { "quoteStyle": "double", "semicolons": "always" },
  },
  "json": { "formatter": { "trailingCommas": "none" } },
  "css": { "formatter": { "enabled": true } },
}

完整参考： 请参阅 examples/formatting.md，了解所有选项、Prettier 映射和特定语言的设置。

---

模式 4：导入整理器

Biome v2 重新设计了导入整理器，支持自定义分组排序。在 assist.actions.source.organizeImports 下进行配置。

{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              [":BUN:", ":NODE:"],
              ":PACKAGE:",
              ":BLANK_LINE:",
              ["@company/**"],
              ":BLANK_LINE:",
              ":ALIAS:",
              ":PATH:",
              ":BLANK_LINE:",
              { "type": true },
            ],
            "identifierOrder": "natural",
          },
        },
      },
    },
  },
}

主要选项： identifierOrder 控制命名导入的排序 — "natural"（默认，例如 var1, var2, var11）或 "lexicographic"（严格按字母顺序）。分组支持预定义匹配器、glob 模式（"@my/lib/**"）、对象匹配器（{ "type": true, "source": ["@my/lib"] }），或组合使用以上任意匹配器的数组。

#### 预定义分组

分组	匹配内容
:NODE:	Node.js 内置模块和 node: 协议
:BUN:	Bun 专用模块
:PACKAGE:	带作用域和普通 npm 包
:PACKAGE_WITH_PROTOCOL:	带协议前缀的包
:ALIAS:	使用别名的导入（@/、#、~、$、%）
:PATH:	绝对和相对路径导入
:URL:	HTTP/HTTPS 导入
:BLANK_LINE:	分组之间的视觉分隔符

完整示例： 请参阅 examples/linting.md，了解带结果的导入排序示例。

---

模式 5：CLI 命令

本地使用 check，在流水线中使用 ci。主要命令：

npx biome check --write .          # Lint + format + organize imports (auto-fix)
npx biome ci .                     # CI mode (read-only, optimized for pipelines)
npx biome check --staged --write . # Pre-commit hooks (only staged files)
npx biome check --changed --since=main .  # Changed files only

完整参考： 请参阅 examples/ci.md，了解完整的 CLI 用法、筛选和报告选项。

---

模式 6：抑制注释

Biome 使用 biome-ignore 注释，并要求提供解释。

// biome-ignore lint/suspicious/noDebugger: needed for local debugging
debugger;

// biome-ignore-all lint/style/noDefaultExport: framework requires default export (top of file only)

// biome-ignore-start lint/suspicious/noDoubleEquals: legacy section
// biome-ignore-end lint/suspicious/noDoubleEquals: legacy section

请参阅 reference.md，了解完整的抑制语法表和说明符级别。请参阅 examples/linting.md，了解行内、文件级和范围抑制示例。

---

模式 7：嵌套配置（Monorepo）

Biome v2 支持嵌套的 biome.json 文件。每个子目录都可以覆盖根配置。

// packages/my-app/biome.json — inherits from root
{ "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json", "extends": "//" }

// packages/legacy-lib/biome.json — relaxes rules
{
  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
  "root": false,
  "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } },
}

优点： "extends": "//" 简写可继承根配置，"root": false 用于标记子配置，每个包都可以独立放宽或收紧规则

完整示例： 请参阅 examples/core.md，了解根配置和子配置模式。

---

模式 8：覆盖项（针对特定文件的规则）

使用 overrides 设置针对文件模式的配置，无需嵌套配置文件。

{
  "overrides": [
    {
      "includes": ["**/*.test.ts", "**/*.test.tsx"],
      "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } },
    },
    {
      "includes": ["**/app/**/page.tsx", "**/app/**/layout.tsx"],
      "linter": { "rules": { "style": { "noDefaultExport": "off" } } },
    },
  ],
}

优点： 覆盖项无需在每个文件中添加抑制注释，测试文件可以使用更宽松的规则，框架约定可以通过声明式配置处理

完整示例： 请参阅 examples/linting.md，了解针对测试、配置和生成文件的覆盖项。

---

性能

Biome 使用 Rust 编写，并行处理文件，因此比基于 JavaScript 的替代方案快得多。

工具	格式化时间（1000 个文件）	lint 时间（1000 个文件）
Biome	~100ms	~200ms
Prettier	~2000ms	N/A
ESLint	N/A	~3000ms
ESLint + Prettier	~5000ms	~5000ms

基准数据为近似值。实际性能因项目大小和规则配置而异。

性能提示：

• 使用 biome check，而不是分别运行 biome format 和 biome lint——单次处理速度更快
• 启用 VCS 集成，自动跳过忽略的文件（.gitignore）
• 在钩子和 CI 中使用 --staged 或 --changed，仅处理受影响的文件
• 谨慎选择 nursery 规则——部分实验性规则可能会影响性能
• 使用 --profile-rules（v2.4+）找出配置中速度较慢的 lint 规则

类型感知 lint 的性能：

Biome v2 引入了无需 TypeScript 编译器的类型感知 lint。请按需启用：

• 默认扫描仅发现嵌套配置（速度快）
• 项目域扫描会索引完整的模块图（速度较慢，但仍比 tsc 快）
• 类型域扫描会增加类型推断（最全面，也最耗费资源）

---

<decision_framework>

决策框架

Biome 与 ESLint + Prettier

Need linting and formatting?
|-- Greenfield project?
|   |-- Want simplest possible setup? -> Biome (one tool, one config)
|   |-- Need niche ESLint plugins? -> ESLint + Prettier
|   +-- Speed is important? -> Biome (20x faster)
|-- Existing ESLint + Prettier project?
|   |-- Happy with current setup? -> Stay with ESLint + Prettier
|   |-- Config complexity is a pain? -> Migrate to Biome
|   |-- Need ESLint plugins without Biome equivalents? -> Stay
|   +-- Want faster CI/pre-commit hooks? -> Biome (or hybrid)
+-- Monorepo?
    |-- Need per-package lint configs? -> Biome v2 nested configs or ESLint 10
    +-- Speed bottleneck in CI? -> Biome

配置复杂度

How to configure Biome?
|-- Just starting out? -> Run `biome init`, use defaults with recommended: true
|-- Migrating from ESLint? -> Run `biome migrate eslint --write`
|-- Migrating from Prettier? -> Run `biome migrate prettier --write`
|-- Need per-file rules?
|   |-- Different rules for test files? -> Use `overrides` in biome.json
|   +-- Different rules per package? -> Use nested biome.json with "root": false
+-- Need custom import ordering? -> Configure organizeImports.options.groups

完整迁移决策树： 请参阅 examples/migration.md。

</decision_framework>

---

集成指南

适用范围：

• JSX/TSX：完整支持，并提供 react 域，用于 React 专属的 lint 规则
• TypeScript：无需依赖 tsc 的类型感知 lint（Biome v2+）
• CSS：默认启用 lint，格式化需选择启用
• JSON/JSONC：完整支持，包括 tsconfig.json、package.json
• GraphQL：默认启用 lint，格式化需选择启用
• Vue/Svelte/Astro：通过 html.experimentalFullSupportEnabled 提供实验性支持（v2.4+）

替代 / 冲突项：

• ESLint：Biome 可替代 ESLint 执行 lint（也可采用混合方案）
• Prettier：Biome 可替代 Prettier 执行格式化
• eslint-plugin-import：Biome 的导入整理器可替代导入排序插件
• eslint-config-prettier：无需使用——Biome 不存在格式化器与 lint 规则冲突的问题

CI/编辑器集成： 请参阅 examples/ci.md 和 examples/core.md。

---

<red_flags>

严重问题

高优先级问题：

• 在 CI 中使用 biome check，而不是 biome ci（check 允许使用 --write，在流水线中有风险；ci 为只读）
• 未使用 --save-exact 固定 Biome 版本（格式化可能因次要版本而变化，导致差异噪声）
• biome.json 中缺少 $schema（会失去编辑器自动补全、验证和可发现性）
• 使用 JavaScript 配置文件而非 biome.json（Biome 仅支持 JSON/JSONC 配置）
• 在 biome check 已同时执行两者的情况下，仍分别运行 biome format 和 biome lint（浪费时间，并重复解析文件）

中优先级问题：

• 从 Prettier 迁移时忘记设置 indentStyle: "space"（Biome 默认使用制表符）
• 未启用 VCS 集成（否则 Biome 可能会处理 node_modules 和 dist）
• 未审核更改就使用 --unsafe（不安全修复可能改变程序行为）
• 在 git hooks 中未加入 --no-errors-on-unmatched（暂存区没有匹配文件时会导致失败）
• 启用所有 nursery 规则（这些规则仍处于实验阶段，可能存在 bug 或性能问题）

常见错误：

• 在嵌套配置中使用 "root": true（这是默认值；子配置应使用 "root": false）
• 期待 Biome 支持 Markdown/YAML 格式化（Biome 目前尚不支持这些语言）
• 升级主要版本时未运行 biome migrate --write（v1 和 v2 之间的配置架构有所变化）
• 抑制注释未附带说明（biome-ignore lint: 的冒号后必须有文字）

易忽略之处与边缘情况：

• Biome 默认使用制表符，而非空格——从 Prettier 迁移时务必显式设置 indentStyle
• CSS 和 GraphQL 格式化默认处于禁用状态——必须通过 "formatter": { "enabled": true } 选择启用
• biome-ignore-all 必须位于文件顶部——放在文件中间会触发未使用的抑制警告
• 导入整理器属于 assist，而非 linter——应在 assist.actions.source.organizeImports 下进行配置
• --staged 标志使仅使用 Biome 的配置无需 lint-staged（Biome v1.7.0+）
• 类型感知 lint（project/types 域）会触发文件扫描，可能拖慢大型项目的首次运行
• biome migrate eslint --write 默认不会迁移受启发的规则——使用 --include-inspired 将其纳入
• 范围抑制（biome-ignore-start/biome-ignore-end）必须包含相匹配的规则标识符
• Biome 将 javascript 配置键下的所有 JS/TS/JSX/TSX 统一处理——没有单独的 typescript 部分
• 以点号开头的配置文件名 .biome.json 也会被发现（v2.4+）

</red_flags>

---

<critical_reminders>

重要提醒

（必须使用 biome.json 或 biome.jsonc 进行所有配置——Biome 不使用 JavaScript 配置文件）

（必须使用 --save-exact 将 Biome 固定为精确版本——不同版本的 Biome 格式化结果可能不同）

（CI 流水线中必须使用 biome ci，而非 biome check——ci 为只读模式，且没有 --write 标志）

（本地开发必须使用 biome check --write——一次性运行代码检查器、格式化程序和导入整理器）

（必须在 biome.json 中包含 $schema，以启用编辑器自动补全和验证）

未遵守这些规则会导致格式不一致、CI 流水线损坏以及代码检查错误遗漏。

</critical_reminders>