biome

Biome 2.x

概述

用于检查和格式化 JavaScript、TypeScript、JSX 和 JSON 的快速一体化工具链。Biome 2.x 用一个高性能的 Rust 工具取代 ESLint 和 Prettier。

安装：pnpm add -D @biomejs/biome

**API 参考：**使用 Context7 MCP 查看完整规则参考和 CLI 标志（mcp__context7__resolve-library-id → @biomejs/biome）。

工作流

初始设置：

1. 安装 Biome：pnpm add -D @biomejs/biome
2. 初始化配置：pnpm biome init
3. 使用项目规范配置 biome.json
4. 安装 VS Code 扩展：biomejs.biome
5. 将 npm 脚本添加到 package.json
6. 测试：pnpm biome check .

从 ESLint/Prettier 迁移：

1. 运行迁移辅助工具：pnpm biome migrate eslint --write
2. 检查生成的 biome.json
3. 移除 ESLint/Prettier 配置和依赖项
4. 更新提交前钩子和 CI 脚本
5. 运行完整检查：pnpm biome check --write .

日常使用：

1. 保存时格式化（VS Code 集成）
2. 提交前运行 pnpm biome check .
3. 修复可自动修复的问题：pnpm biome check --write .
4. 检查剩余问题并手动修复

配置

biome.json 结构

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "always",
      "trailingCommas": "es5",
      "arrowParentheses": "asNeeded"
    }
  },
  "files": {
    "ignore": ["dist", "build", "node_modules", "*.min.js", "coverage"]
  }
}

TypeScript / React 项目配置

{
  "linter": {
    "rules": {
      "recommended": true,
      "a11y": { "noBlankTarget": "error", "useAltText": "error", "useButtonType": "error" },
      "complexity": { "noExcessiveCognitiveComplexity": "warn", "noUselessFragments": "error" },
      "correctness": { "noUnusedVariables": "error", "useExhaustiveDependencies": "warn", "useHookAtTopLevel": "error" },
      "performance": { "noAccumulatingSpread": "warn" },
      "security": { "noDangerouslySetInnerHtml": "warn" },
      "style": { "noNonNullAssertion": "warn", "useConst": "error", "useImportType": "error" },
      "suspicious": { "noExplicitAny": "error", "noDebugger": "error", "noConsoleLog": "warn" }
    }
  },
  "javascript": {
    "formatter": { "jsxQuoteStyle": "double", "quoteStyle": "single" }
  }
}

按文件覆盖配置

{
  "overrides": [
    {
      "include": ["tests/**/*.ts"],
      "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } }
    },
    {
      "include": ["scripts/**/*.js"],
      "formatter": { "lineWidth": 120 }
    }
  ]
}

CLI 命令

# Check (lint + format) — use this for most tasks
pnpm biome check .
pnpm biome check --write .          # auto-fix
pnpm biome check --write --dry-run . # preview changes

# Lint or format only
pnpm biome lint --write .
pnpm biome format --write .

# Diagnostics
pnpm biome rage                     # effective config + diagnostics
pnpm biome explain src/App.tsx      # explain failures for a file
pnpm biome migrate eslint --write   # migrate from ESLint
pnpm biome migrate prettier --write # migrate from Prettier

Package.json 脚本

{
  "scripts": {
    "lint": "biome lint .",
    "format": "biome format --write .",
    "check": "biome check .",
    "fix": "biome check --write .",
    "typecheck": "tsc --noEmit",
    "quality": "pnpm lint && pnpm typecheck && pnpm build"
  }
}

编辑器集成

VS Code settings.json

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "eslint.enable": false,
  "prettier.enable": false,
  "[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[json]": { "editor.defaultFormatter": "biomejs.biome" },
  "biome.lspBin": "./node_modules/@biomejs/biome/bin/biome"
}

忽略代码

// biome-ignore lint/suspicious/noExplicitAny: legacy code
function legacy(param: any) { return param; }

// biome-ignore format: preserve matrix formatting
const matrix = [
  1, 0, 0,
  0, 1, 0,
  0, 0, 1,
];

忽略整个目录时，优先在 biome.json 中使用 files.ignore，而不是内联注释。

Git 钩子集成

使用 lint-staged + Husky：

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

使用 Lefthook（lefthook.yml）：

pre-commit:
  parallel: true
  commands:
    biome:
      glob: "*.{js,ts,jsx,tsx,json}"
      run: biome check --write --no-errors-on-unmatched {staged_files}

CI/CD 集成

GitHub Actions

name: Code Quality
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: 10 }
      - uses: actions/setup-node@v4
        with: { node-version: '24', cache: 'pnpm' }
      - run: pnpm install --frozen-lockfile
      - run: pnpm biome check .
      - run: pnpm typecheck

ESLint 规则对应项

ESLint 规则	Biome 规则
no-unused-vars	correctness/noUnusedVariables
@typescript-eslint/no-explicit-any	suspicious/noExplicitAny
react-hooks/exhaustive-deps	correctness/useExhaustiveDependencies
no-console	suspicious/noConsoleLog
prefer-const	style/useConst
jsx-a11y/alt-text	a11y/useAltText

最佳实践

• 以推荐规则集为基础，再自定义特定规则
• 在 VS Code 中启用保存时格式化，实现流畅的工作流
• 通过 Git 钩子（Husky/Lefthook）在提交前运行检查
• 使用 biome check（而不是分别运行 lint 和 format），实现统一工作流
• 在 biome.json 中忽略生成的文件，而不是使用内联注释
• 使用覆盖配置，为测试和源代码设置不同规则
• 将 biome.json 提交到版本控制，确保团队配置一致
• 为自定义规则添加注释，说明其必要性

反模式

• 分别运行 lint 和 format（改用 check）
• 无正当理由禁用推荐规则
• 过度使用 biome-ignore（应修复根本问题）
• 不将 biome.json 提交到版本控制
• 在同一项目中混用 ESLint 和 Biome
• 通过内联注释而非配置来忽略文件
• 未充分测试迁移就移除 ESLint/Prettier
• 为了“快速修复”而跳过提交前钩子
• 在 biome.json 中使用过时的架构版本

反馈循环

# Preview formatting changes without writing
pnpm biome format --write --dry-run .

# Diagnose config issues
pnpm biome rage

# CI test locally (exit code 0 = success)
pnpm biome check . --error-on-warnings && echo "OK"

验证 VS Code 集成：命令面板 → “Biome: Show Output Channel” → 应显示 LSP 服务日志。