biome

biome — SKILL.md

变体： 标准 · 适用场景： 使用 Biome v2 对 JS/TS 项目进行 lint 和格式化。

概述

Biome 是一个 Rust 单二进制工具，可对 JavaScript、TypeScript、JSX、JSON、CSS 和 GraphQL 进行 lint、格式化和导入整理——用一个工具和一个 biome.json 取代 ESLint + Prettier 技术栈。它相当于 JS/TS 领域的 Python ruff：速度快、默认配置有主见、只需一个配置文件。本技能涵盖 Biome（v2）的安装、biome.json 编写、当前 CLI（包括 biome ci 门禁）、从现有 ESLint/Prettier 配置迁移、容易让过时知识出错的 v1→v2 变更，以及使用 GritQL 插件编写自定义 lint 规则。已针对 Biome v2 验证；安装时请确认当前的确切版本。

何时启用

• ✅ 为 JS/TS 项目（新项目或替换 ESLint/Prettier）添加 lint + 格式化。
• ✅ 编写或修复 biome.json（格式化程序、lint 规则、导入整理、VCS、覆盖配置）。
• ✅ 配置 lint/格式化 CI 门禁。
• ✅ 从 ESLint/Prettier 迁移，或以 GritQL 插件形式编写自定义规则。

以下情况不要启用：

• 需要将 Biome 配置为 Turborepo/pnpm 流水线中的任务——请与 turborepo 技能组合使用；本技能负责 Biome 本身，不负责任务图。
• 项目使用 Python——请使用 ruff（Biome 是 JS/TS 对应工具，此处仅将其作为类比）。

工作流

步骤 1：安装 + 初始化

npm install --save-dev --save-exact @biomejs/biome   # i.e. -D -E
npx biome init                                        # writes biome.json

步骤 2：配置 biome.json

{
  "$schema": "https://biomejs.dev/schemas/<version>/schema.json",
  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
  "files": { "includes": ["src/**", "!**/dist"] },
  "formatter": { "enabled": true, "indentStyle": "space", "lineWidth": 100 },
  "linter": { "enabled": true, "rules": { "recommended": true } },
  "assist": { "enabled": true, "actions": { "source": { "organizeImports": "on" } } }
}

（biome init 会写入带版本固定 URL 的 $schema——不要直接发布 <version> 字面量。）完整架构说明——规则组 + linter.domains、语言区块、overrides、monorepo extends/root——见 references/config.md。

步骤 3：运行

npx biome check --write .          # lint + format + organize imports, apply SAFE fixes
npx biome check --write --unsafe . # also apply unsafe fixes
npx biome format --write .         # format only;  npx biome lint .  # lint only

biome check 会运行全部三项（格式化、lint、导入排序）。完整命令/标志参考及 v1→v2 CLI 差异：references/cli.md。

步骤 4：CI 门禁

npx biome ci .     # read-only: format + lint + import-sort checks, never writes

在 CI 中使用 biome ci（相当于 ruff check），绝不要使用会修改文件的 check --write。将其配置为 lint/格式化作业；流水线和缓存交由 turborepo 技能处理。

步骤 5：从 ESLint / Prettier 迁移（如适用）

npx biome migrate eslint --write     # ports .eslintrc / flat config + .eslintignore
npx biome migrate prettier --write   # ports .prettierrc

详情和注意事项：references/migration-monorepo.md。

步骤 6：自定义规则（可选）——GritQL 插件

在 biome.json 的 plugins 中注册 .grit 插件并编写模式；完整编写指南（模式语法、register_diagnostic、完整示例、限制）见 references/gritql-plugins.md。优先使用内置规则；只有在没有规则适用时才使用插件。

规则

硬性规则（绝不违反）：

• 使用 v2 CLI。 --write / --write --unsafe 用于应用修复；v1 的 --apply / --apply-unsafe 已移除。输出 --apply 是最常见的过时知识错误——参见“易错点”。
• CI 门禁应使用 biome ci，而不是 check --write。 CI 必须为只读；check --write 会修改工作树。
• 每个项目使用一个 biome.json（嵌套/monorepo 配置使用 extends）。不要针对相同事项同时运行 ESLint/Prettier——Biome 可取代它们。

偏好（可覆盖）：

• Biome 格式化程序默认使用 制表符，缩进宽度为 2，lineWidth 为 80。如果团队统一使用空格（例如从 Prettier 迁移而来），请显式设置 formatter.indentStyle / lineWidth。
• 启用 vcs.useIgnoreFile，让 Biome 遵循 .gitignore。
• 从 rules.recommended 开始，并按需收紧各规则组的设置。

易踩问题

• --apply 已移除（v1→v2）。 v1 使用 biome check --apply / --apply-unsafe；v2 使用 --write / --write --unsafe（--fix 是 --write 的别名）。过时的代码片段和旧习惯会产生 --apply，现在这会报错。请参阅 references/cli.md。
• 导入整理的位置已变更。 v1 的顶层 organizeImports 已移除；在 v2 中，它是 assist.actions.source.organizeImports 下的一个辅助操作。沿用 v1 格式的配置不会报错，但也不会整理导入。
• include/ignore → includes（v2）。 v2 的 files.includes 是一个使用 ! 前缀表示排除项的 glob 列表，取代了 v1 中分开的 include/ignore。沿用 v1 格式的 files 配置块是错误的。
• 格式化工具默认使用制表符。 Prettier 用户若期望使用空格，就会得到制表符，除非设置 indentStyle: "space"。biome migrate prettier 会保持原有设置，但全新运行 biome init 不会。
• GritQL 插件目前仅适用于 JS 和 CSS。 针对其他语言的插件不会运行。

反模式

• 对相同文件同时运行 ESLint + Prettier 和 Biome。 工具重复、修复相互冲突、运行更慢。Biome 可以取代它们——应迁移，而不是叠加使用。
• 在 CI 中运行 biome check --write。 CI 会修改代码树，还可能掩盖代码偏差。请使用 biome ci。
• 已有内置规则时仍使用 GritQL 插件。 先检查规则组；插件适用于确实需要自定义检查的情况。
• 在这里重复配置 Turborepo 流水线。 将 Biome 接入缓存任务属于 turborepo 技能的范围；本技能仅介绍 Biome 命令。

输出

配置好的 biome.json，以及在本地（biome check --write）和 CI（biome ci）中接入的 lint/格式化命令——也可从 ESLint/Prettier 配置迁移，并扩展自定义 GritQL 规则。使用方是开发工作流和 CI 门禁，它们负责确保代码库风格一致且通过 lint 检查。

相关内容

• turborepo — 将 biome ci/check 作为缓存流水线任务运行；本技能负责 Biome，该技能负责任务图。
• vite — 通常会在其中构建经 lint 和格式化的代码。
• ruff — Biome 在概念上对应的 Python lint+格式化工具（但工具不同）。

渐进式披露

• references/config.md — 编写 biome.json 时加载：完整的顶层 schema、格式化工具/linter/辅助操作选项、规则组、overrides、monorepo 的 extends/root，以及 v2 配置结构变更。
• references/cli.md — 运行 Biome 或接入 CI 时加载：所有命令和标志、--write/ci 的语义，以及 v1→v2 CLI 变更对照表。
• references/gritql-plugins.md — 编写自定义规则时加载：插件注册、GritQL 模式语法、register_diagnostic、完整示例和限制。
• references/migration-monorepo.md — 从 ESLint/Prettier 迁移或配置 monorepo 时加载：migrate 命令及注意事项，以及 extends/root monorepo 模型。
• references/sources.md — 研究来源。

正文篇幅预算

• description ≤ 1,024 个字符；正文 ≤ 约 500 行 / 5,000 个 token；大量内容放在 references/ 中。