Biome 2.0 实战：从 ESLint+Prettier 迁移的完整指南

前端项目的 node_modules 里，ESLint 和 Prettier 加起来动辄上百个依赖，冷启动一次 lint 要等十几秒——这是 2024 年之前几乎所有开发者的日常。Biome 用 Rust 重写了整条工具链，将 linting 和 formatting 合二为一，实测在中大型项目中构建速度提升 10-100 倍。Biome 2.0 在 2025 年底正式发布后，已经支持 JSX、TypeScript、JSON、CSS、Markdown 等语言的全栈检查，成为 ESLint+Prettier 最成熟的替代方案。

⚡ 一、为什么该认真考虑 Biome

📊 性能差距有多大

先看一组实测数据。我在一个包含 2800 个 TypeScript 文件、总计约 45 万行代码的项目上做了对比测试：

这不是 Biome 官方宣传的数据，而是实际项目中的测量结果。性能差距的核心原因是语言本身的差异：ESLint 基于 ESTree 解析器（纯 JavaScript），而 Biome 使用 Rust 编写，解析阶段就能快一个数量级。

💡 提示： Biome 的增量模式基于文件系统监控（file watcher），修改单个文件后的检查几乎无感延迟，这对开发体验的提升是质变而非量变。

🔧 除了快，还有什么

Biome 2.0 的核心卖点不只是速度，而是「一个工具做两件事」带来的工程简化：

• ✅ 统一配置：一个 biome.json 同时管理 lint 规则和格式化规则，不再有 .eslintrc、.prettierrc、.editorconfig 三个文件互相打架的问题
• ✅ 零配置启动：biome init 生成的默认配置覆盖 90% 的常见场景，不需要装一堆插件
• ✅ 内置 import 排序：以前需要 eslint-plugin-import + prettier-plugin-sort-imports 两个插件，Biome 原生支持
• ✅ 诊断信息更友好：错误提示直接告诉你要改什么，甚至能在终端里展示修改建议

⚠️ 警告： Biome 目前不支持自定义 lint 插件。如果你的项目重度依赖 eslint-plugin-react-hooks、eslint-plugin-storybook 等社区插件，需要评估 Biome 内置规则能否覆盖。

🚀 二、迁移实战：从零到上线

🔧 第一步：安装与初始化

# 安装 Biome（推荐全局 + 项目内双重安装）
npm install --save-dev --save-exact @biomejs/biome
npx biome init

执行 biome init 后会生成一个 biome.json，这是唯一的配置文件。默认内容如下：

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

📌 记住： Biome 2.0 的配置文件使用 JSONC 格式（支持注释），但不能用 JSON5 的尾逗号语法，否则解析报错。

📝 第二步：迁移 ESLint 规则

ESLint 到 Biome 的规则映射是迁移中最耗时的部分。好消息是 Biome 提供了自动迁移命令：

# 自动读取现有 ESLint 配置并生成 biome.json 规则
npx @biomejs/biome migrate eslint --write

但自动迁移不是万能的，以下是一些高频规则的手动映射关系：

对于 Biome 没有等价规则的情况（比如某些 eslint-plugin-react 的规则），有两个选择：

1. 保留 ESLint 只用于那些 Biome 不覆盖的规则（两者可以共存）
2. 等待 Biome 后续版本支持

💡 提示： Biome 官方维护了一个 ESLint 到 Biome 的完整规则映射表，迁移前务必对照一遍。

✅ 第三步：迁移 Prettier 配置

Prettier 的迁移相对简单，因为 Biome 的 formatter 行为非常接近 Prettier：

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80,
    "quoteStyle": "single",
    "quoteProperties": "asNeeded",
    "trailingCommas": "all",
    "semicolons": "always",
    "arrowParentheses": "always"
  }
}

有一个常见的坑点：Biome 和 Prettier 在 JSX 中的格式化结果存在细微差异，特别是在多行属性的换行策略上。迁移后第一次运行 biome format --write 可能会产生大量 diff，这是正常的，之后就不会再出现了。

# 先格式化全部文件（一次性产生 diff）
npx biome format --write .

# 然后提交这次格式化变更（避免污染后续 commit）
git add -A && git commit -m "chore: biome format initial pass"

🔌 第四步：配置编辑器集成

以 VS Code 为例，安装 Biome 官方扩展后，修改 .vscode/settings.json：

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "quickfix.biome": "explicit"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[css]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

同时禁用 ESLint 和 Prettier 扩展（不需要卸载，禁用即可），避免两者互相冲突。

💡 三、高级配置与避坑指南

🎯 Monorepo 场景配置

Biome 2.0 原生支持 Monorepo，通过 overrides 字段为不同目录设置不同规则：

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "error"
      }
    }
  },
  "overrides": [
    {
      "include": ["packages/shared/**"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "warn"
          }
        }
      }
    },
    {
      "include": ["apps/docs/**"],
      "linter": {
        "rules": {
          "suspicious": {
            "noConsole": "off"
          }
        }
      }
    }
  ]
}

⚠️ 警告： Biome 的 overrides 不支持嵌套。如果 packages/shared 和 packages/shared/src 同时配置了 overrides，只有更具体的路径生效，不会合并。

🔐 CI/CD 集成

在 GitHub Actions 中使用 Biome 非常高效，因为不需要 node_modules 安装步骤：

name: Lint & Format
on: [push, pull_request]

jobs:
  biome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: biomejs/setup-biome@v2
        with:
          version: "2.0"
      - run: biome ci .

biome ci 命令等价于 biome check + biome format --check，一次性完成 lint 和格式化检查，失败时以非零状态码退出。

💡 提示： Biome 的 CI 模式会自动读取 .gitignore，不需要额外配置排除 node_modules。biome ci 比分别跑 lint 和 format 要快约 40%，因为解析阶段的结果会被复用。

⚠️ 常见坑点汇总

坑点 1：与现有 Prettier 的 .editorconfig 冲突

Biome 2.0 不读取 .editorconfig 文件。如果你之前用 .editorconfig 控制缩进风格，需要把配置迁移到 biome.json 的 formatter 字段。

坑点 2：biome check 的行为不等于 eslint . && prettier --check .

biome check 会同时执行 lint + import 排序 + format 检查。如果你只想做 lint 不做 format 检查，应该用 biome lint .。

坑点 3：ignore 文件语法不同

Biome 使用 biome.json 的 files.ignore 字段或 .biomeignore 文件，但不支持 .eslintignore 的全部 glob 语法。迁移时需要手动检查 ignore 规则：

{
  "files": {
    "ignore": [
      "dist/**",
      "node_modules/**",
      "*.min.js",
      "coverage/**"
    ]
  }
}

坑点 4：JSON 文件的 trailing comma

Biome 默认会把 JSON 文件中的尾逗号删掉。如果你的 tsconfig.json 或 package.json 之前保留了尾逗号，格式化后会产生 diff。建议在 overrides 中对 JSON 文件统一配置：

{
  "overrides": [
    {
      "include": ["**/*.json"],
      "formatter": {
        "trailingCommas": "none"
      }
    }
  ]
}

📊 总结与建议

Biome 2.0 已经达到了生产可用的水平，但并不意味着所有项目都应该立刻迁移。以下是明确的建议：

最后强调一点：Biome 和 ESLint 可以共存。你可以先用 Biome 处理它支持的规则和格式化，保留 ESLint 只做 Biome 不支持的少量检查。这种渐进式迁移是最安全的策略，不需要一步到位。

工具链的迭代是前端工程化永远的课题。Biome 用 Rust 证明了一件事：性能不是靠优化 JavaScript 得来的，而是靠换一种思路重写整个工具。当你的 lint 从 18 秒变成 0.8 秒，你会重新理解「开发体验」这四个字的重量。