Biome 完全指南：超快的 Linter 和 Formatter

Biome（前身为 Rome）是一个用于 JavaScript、TypeScript、JSX、TSX、JSON 和 CSS 的高性能工具链。它使用 Rust 编写，将格式化、代码检查和导入排序合并到一个二进制文件中，运行速度比 ESLint 和 Prettier 组合快 35 倍。Biome 的格式化与 Prettier 97% 兼容，提供超过 280 条 Lint 规则，并且开箱即用无需配置。如果你想用一个快速工具替换整个代码质量管道，Biome 是 2026 年的首选。

什么是 Biome？

Biome 是一个面向 Web 开发的开源工具链，为 JavaScript、TypeScript、JSX、TSX、JSON、CSS 和 GraphQL 提供格式化器、代码检查器和导入组织器。它作为 Rome 项目的延续创建，于 2023 年 8 月发布首个稳定版本（1.0）。该项目由 Biome 核心团队和不断增长的贡献者社区维护。

与传统的 JavaScript 工具栈不同（需要 ESLint 进行代码检查、Prettier 进行格式化、eslint-plugin-import 进行导入排序），Biome 用单个二进制文件处理所有三项工作。这消除了依赖冲突，简化了配置，并大幅减少了执行时间。Biome 只解析一次代码，在单次遍历中运行所有检查。

为什么 Biome 如此快速？

Biome 使用 Rust 编写，Rust 是一种以内存安全和零开销抽象著称的系统编程语言。Rust 让 Biome 实现了基于 JavaScript 的工具无法达到的性能。其速度的关键技术原因是：

• Rust compiled binary:
• Single-pass architecture:
• Parallel processing:
• Zero-copy parsing:
• No plugin overhead:

安装和入门

Biome 可以作为项目依赖安装或独立使用。推荐方法是作为开发依赖安装，以确保每个团队成员使用相同版本。

# Install as a dev dependency (recommended)
npm install --save-dev --save-exact @biomejs/biome

# Or with other package managers
pnpm add --save-dev --save-exact @biomejs/biome
yarn add --dev --exact @biomejs/biome
bun add --dev --exact @biomejs/biome

# Initialize biome.json
npx @biomejs/biome init

# Run formatter
npx @biomejs/biome format --write ./src

# Run linter
npx @biomejs/biome lint ./src

# Run everything (format + lint + import sorting)
npx @biomejs/biome check --write ./src

biome.json 配置

biome.json 文件是所有 Biome 功能的单一配置文件。它控制格式化设置、Lint 规则、导入排序行为和文件处理。Biome 无需配置即可工作，但 biome.json 让你可以自定义每个方面。

运行 biome init 可以生成初始 biome.json。该文件支持带注释的 JSON。配置组织为顶级部分：formatter、linter、organizeImports、javascript、typescript、json 和 css。

// biome.json - Complete configuration example
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",

  // Formatter settings
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  },

  // Linter settings
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "warn",
        "noDoubleEquals": "error"
      },
      "style": {
        "useConst": "error",
        "noVar": "error",
        "useTemplate": "error"
      },
      "complexity": {
        "noForEach": "warn"
      }
    }
  },

  // Import sorting
  "organizeImports": {
    "enabled": true
  },

  // JavaScript-specific options
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always"
    }
  },

  // Files configuration
  "files": {
    "ignore": [
      "dist/",
      "build/",
      "node_modules/",
      "*.min.js",
      "coverage/"
    ],
    "maxSize": 1048576
  }
}

格式化规则和选项

Biome 格式化器与 Prettier 输出 97% 兼容。它支持 Prettier 提供的所有格式化选项，包括缩进样式、缩进宽度、行宽、引号样式、分号和尾逗号。格式化器适用于 JavaScript、TypeScript、JSX、TSX、JSON 和 CSS 文件。

与 Prettier 不同，Biome 不需要单独的 .prettierrc 文件。所有格式化选项都在 biome.json 的 formatter 和语言特定部分中。如果你要从 Prettier 迁移，Biome 可以自动读取并转换你的 .prettierrc。

// Formatting options in biome.json
{
  "formatter": {
    "indentStyle": "space",     // "space" | "tab"
    "indentWidth": 2,           // 1-24 (default: 2)
    "lineWidth": 80,            // 1-320 (default: 80)
    "lineEnding": "lf"          // "lf" | "crlf" | "cr"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",   // "double" | "single"
      "jsxQuoteStyle": "double",// "double" | "single"
      "semicolons": "always",   // "always" | "asNeeded"
      "trailingCommas": "all",  // "all" | "es5" | "none"
      "arrowParentheses": "always", // "always" | "asNeeded"
      "bracketSpacing": true,   // true | false
      "bracketSameLine": false  // true | false
    }
  }
}

// Run formatter in check mode (no writes)
// npx @biomejs/biome format ./src

// Run formatter and apply changes
// npx @biomejs/biome format --write ./src

代码检查规则

Biome 提供超过 280 条 Lint 规则，按组分类。每组专注于特定的代码质量类别。规则可以启用、禁用或设置为警告级别。许多规则包含安全的自动修复。

• recommended:
• suspicious:
• correctness:
• style:
• complexity:
• performance:
• a11y:
• security:

// Linter configuration examples in biome.json
{
  "linter": {
    "enabled": true,
    "rules": {
      // Enable all recommended rules
      "recommended": true,

      // Customize individual groups
      "suspicious": {
        "noExplicitAny": "warn",
        "noDoubleEquals": "error",
        "noShadowRestrictedNames": "error",
        "noImplicitAnyLet": "error"
      },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "useExhaustiveDependencies": "warn"
      },
      "style": {
        "useConst": "error",
        "noVar": "error",
        "useTemplate": "error",
        "useOptionalChain": "error",
        "useNullishCoalescing": "error"
      },
      "performance": {
        "noAccumulatingSpread": "error",
        "noDelete": "warn"
      },
      "a11y": {
        "useAltText": "error",
        "useAriaPropsForRole": "error",
        "noBlankTarget": "error"
      }
    }
  }
}

// Run linter
// npx @biomejs/biome lint ./src

// Run linter and apply safe fixes
// npx @biomejs/biome lint --write ./src

// Run linter with unsafe fixes (may change semantics)
// npx @biomejs/biome lint --write --unsafe ./src

导入排序

Biome 包含内置的导入排序，替代 eslint-plugin-import-sort 和 trivial-import-sort 等工具。启用后，Biome 自动按照一致的约定分组和排序导入语句。它将外部依赖与内部模块分开，并在每组内按字母排序。

运行 biome check --write 或 biome format --write 时默认启用导入排序。副作用导入（如 "import ./polyfills"）保持在原始位置。

// Before: unsorted imports
import { useState, useEffect } from "react";
import "./styles.css";
import { Button } from "@/components/Button";
import axios from "axios";
import { z } from "zod";
import { formatDate } from "@/utils/date";
import React from "react";

// After: Biome-sorted imports
import React, { useEffect, useState } from "react";
import axios from "axios";
import { z } from "zod";

import { Button } from "@/components/Button";
import { formatDate } from "@/utils/date";

import "./styles.css";

// biome.json import sorting config
// {
//   "organizeImports": {
//     "enabled": true
//   }
// }

从 ESLint 和 Prettier 迁移

Biome 提供专门的 migrate 命令，读取现有的 ESLint 和 Prettier 配置文件并转换为 biome.json 等效配置。这自动化了迁移过程中最繁琐的部分。

迁移工具处理 .eslintrc、eslint.config.js（扁平配置）、.prettierrc 和 prettier.config.js 文件。它将 ESLint 规则映射到对应的 Biome 规则，并对没有对应项的规则发出警告。

迁移后，你可以从 package.json 中移除 eslint、prettier 及其插件依赖。这通常从依赖树中移除 10-30 个包，简化维护并减少安装时间。

# Step 1: Install Biome
npm install --save-dev --save-exact @biomejs/biome

# Step 2: Migrate ESLint config to biome.json
npx @biomejs/biome migrate eslint
# Reads .eslintrc.json / eslint.config.js and updates biome.json

# Step 3: Migrate Prettier config to biome.json
npx @biomejs/biome migrate prettier
# Reads .prettierrc and updates biome.json formatter section

# Step 4: Verify no regressions
npx @biomejs/biome check ./src

# Step 5: Apply formatting with Biome
npx @biomejs/biome check --write ./src

# Step 6: Remove old dependencies
npm uninstall eslint prettier eslint-config-prettier \
  eslint-plugin-react eslint-plugin-react-hooks \
  @typescript-eslint/parser @typescript-eslint/eslint-plugin \
  eslint-plugin-import

# Step 7: Update package.json scripts
# Replace:
#   "lint": "eslint . && prettier --check ."
# With:
#   "lint": "biome check ./src",
#   "lint:fix": "biome check --write ./src"

# Step 8: Delete old config files
# rm .eslintrc.json .prettierrc .eslintignore .prettierignore

CI/CD 集成

Biome 无缝集成到 CI/CD 管道中。biome ci 命令专为持续集成环境设计。它以检查模式运行格式化器、运行所有启用的 Lint 规则并验证导入排序。任何检查失败时命令以非零退出码退出。

Biome 还提供 GitHub Action（biomejs/setup-biome），为快速 CI 运行安装和缓存 Biome 二进制文件。该 Action 支持版本固定。

# GitHub Actions workflow (.github/workflows/ci.yml)
name: CI
on: [push, pull_request]

jobs:
  biome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Biome
        uses: biomejs/setup-biome@v2
        with:
          version: latest

      - name: Run Biome checks
        run: biome ci ./src

# Or using npm in your CI pipeline:
# npx @biomejs/biome ci ./src
#
# biome ci exits with code 1 if any check fails:
#   - Formatting violations
#   - Lint errors
#   - Unsorted imports

Pre-commit Hook

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

# Or using lefthook (lefthook.yml)
pre-commit:
  commands:
    biome:
      glob: "*.{js,ts,jsx,tsx,json,css}"
      run: npx @biomejs/biome check --write --no-errors-on-unmatched --staged {staged_files}

编辑器集成

Biome 为 VS Code、基于 IntelliJ 的 IDE 和 Neovim 提供官方扩展。VS Code 扩展功能最完整，提供实时 Lint 诊断、保存时格式化、快速修复代码操作和导入排序。

VS Code

从 VS Code 扩展市场安装 Biome 扩展。然后将以下设置添加到 .vscode/settings.json 中启用保存时格式化。

// .vscode/settings.json
{
  // Set Biome as default formatter
  "editor.defaultFormatter": "biomejs.biome",

  // Format on save
  "editor.formatOnSave": true,

  // Enable code actions on save
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },

  // Language-specific overrides
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[css]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

Neovim

对于 Neovim，Biome 支持语言服务协议（LSP）。你可以使用 nvim-lspconfig 或任何 LSP 客户端配置它。

-- Neovim LSP config for Biome (nvim-lspconfig)
require("lspconfig").biome.setup({
  cmd = { "npx", "@biomejs/biome", "lsp-proxy" },
  root_dir = require("lspconfig.util").root_pattern("biome.json"),
  single_file_support = false,
})

-- Format on save with Biome
vim.api.nvim_create_autocmd("BufWritePre", {
  pattern = { "*.js", "*.ts", "*.jsx", "*.tsx", "*.json", "*.css" },
  callback = function()
    vim.lsp.buf.format({ async = false })
  end,
})

Biome 与 ESLint + Prettier 对比

了解 Biome 和传统 ESLint + Prettier 之间的权衡有助于你为项目选择正确的工具。

如果速度、简洁和最少配置是优先事项，且不需要 React 以外的框架插件或自定义规则，选择 Biome。如果需要 Vue/Angular/Svelte 插件、自定义规则或完整的 ESLint 生态，选择 ESLint + Prettier。许多团队在新项目中使用 Biome，在有复杂插件依赖的现有项目中使用 ESLint。

高级配置

Biome 支持 Monorepo、按目录覆盖和语言特定设置的高级配置模式。biome.json 中的 overrides 部分让你可以对不同的文件模式应用不同的规则。

// biome.json - Advanced overrides
{
  "linter": {
    "rules": {
      "recommended": true
    }
  },

  "overrides": [
    {
      // Relax rules for test files
      "include": ["**/*.test.ts", "**/*.spec.ts", "**/*.test.tsx"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          },
          "complexity": {
            "noForEach": "off"
          }
        }
      }
    },
    {
      // Different formatting for JSON config files
      "include": ["*.json"],
      "formatter": {
        "indentWidth": 4
      }
    },
    {
      // Disable formatting for generated files
      "include": ["src/generated/**"],
      "formatter": { "enabled": false },
      "linter": { "enabled": false }
    }
  ]
}

Monorepo 设置

在 Monorepo 中，你可以在根目录放置 biome.json 用于共享设置，在包特定的 biome.json 文件中使用 extends 属性继承和覆盖规则。Biome 在处理文件时自动发现最近的 biome.json。

// Root biome.json (shared settings)
{
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "rules": {
      "recommended": true
    }
  },
  "organizeImports": { "enabled": true }
}

// packages/frontend/biome.json
{
  "extends": ["../../biome.json"],
  "linter": {
    "rules": {
      "a11y": {
        "useAltText": "error",
        "useAriaPropsForRole": "error"
      }
    }
  }
}

// packages/api/biome.json
{
  "extends": ["../../biome.json"],
  "linter": {
    "rules": {
      "a11y": {
        "recommended": false
      }
    }
  }
}

性能基准测试

Biome 在各种规模的项目基准测试中始终优于 ESLint 和 Prettier。在一个典型的包含 1,000 个 TypeScript 文件的 React 项目中，Biome 在 500ms 内完成格式化和代码检查，而 ESLint + Prettier 需要 10-15 秒。速度优势随项目规模增长而增大。

在 CI 环境中，Biome 将代码质量检查时间从分钟级缩短到秒级。团队报告迁移到 Biome 后 Lint/格式化 CI 步骤持续时间减少 90-95%。

# Benchmark: 1,000 TypeScript files (React project)
#
# Tool                    Time         Files/sec
# ----                    ----         ---------
# Biome (format+lint)     0.45s        2,222
# Prettier (format)       4.2s         238
# ESLint (lint)           8.7s         115
# ESLint+Prettier         12.9s        78
#
# Speedup: Biome is ~29x faster than ESLint+Prettier
#
# CI impact (real-world monorepo, 5,000 files):
#   Before (ESLint+Prettier): 47s
#   After (Biome):            1.8s
#   Reduction:                96%

最佳实践

• 从推荐规则预设开始定制。默认值经过精心选择，能捕获最重要的问题而不会过于严格。
• 从一开始就启用导入排序。它消除导入块中的合并冲突并保持代码库一致。
• 在 pre-commit hook 中使用 biome check --write，在每次提交前自动格式化、修复和排序导入。
• 在 package.json 中固定 Biome 版本，避免团队成员间的格式化差异。
• 在 CI 管道中使用 biome ci 命令。它针对非交互式环境优化。
• 配置编辑器扩展保存时格式化，立即捕获问题。
• 每次更新时查看 Biome 发布说明。新规则和格式化器改进定期添加。
• 使用 overrides 部分为需要宽松规则的测试文件配置，如允许魔法数字或 console 语句。

常见问题