Biome 工具链完全指南：用一个工具统一格式化、Lint、自动修复与 CI

很多团队的前端工具链是这样演进的：

一开始只需要格式化：Prettier
然后要代码规范：ESLint + 一堆插件
再然后要类型检查：TypeScript
最后要在 CI 里强制执行：lint/format/check 全跑一遍

到某个阶段，你会遇到几个典型痛点：

工具太多：配置分散、版本冲突、升级成本高
速度不够：CI 里跑一圈耗时明显
规则不一致：Prettier 与 ESLint“打架”，需要额外桥接
新人上手慢：不知道该修哪个、为什么失败

Biome 的目标很明确：用一个工具把“格式化 + Lint + 自动修复”合在一起，把开发和 CI 的“代码质量门禁”做得更简单、更快、更可控。

本文会从“适合谁用/怎么落地/怎么迁移/怎么在 CI 生效”四个层面讲清楚，保证你读完就能在项目里真正用起来。

1. Biome 是什么？它要解决的到底是哪类问题

你可以把 Biome 理解为一套集成式前端质量工具：

Formatter：类似 Prettier（但不是完全等价）
Linter：类似 ESLint（但规则集合与生态不同）
Fixer：自动修复（--write）

它适用于两类目标：

团队协作一致性：大家写出来的代码风格统一、提交前可自动修复
工程门禁：CI 在 PR 合并前做“最低质量保证”

需要强调：Biome 不取代 TypeScript 的类型系统，它解决的是“格式与代码质量规则层面”的问题。

2. 适合用 Biome 的团队画像（以及不适合的场景）

适合

你想减少 ESLint/Prettier 组合的复杂度，把常见规则交给一个工具
你的项目是 pnpm workspace / monorepo，希望统一规范并且跑得快
你希望把自动修复变成默认动作（而不是让大家手动修）

不适合（或需要谨慎）

你高度依赖某些 ESLint 插件生态（例如特别小众的框架规则、内部自定义规则）
你已经在 ESLint 上积累了大量“业务特化规则”，短期迁移会带来较多改动

现实策略往往是：

先用 Biome 负责格式化 + 一部分通用 Lint；ESLint 留作补充（如果确实需要）。

3. 在团队里落地 Biome：最小可行方案（MVP）

落地工具链时，不建议一步到位“全部替换”，最稳的顺序通常是：

让 Biome 先接管 format（格式化）
再接管 lint（检查 + 可修复项）
最后接管 CI 门禁

这样做的好处是：改动可控、回滚容易、失败也容易定位。

4. 配置文件：`biome.json`（建议从简单开始）

Biome 通常在仓库根目录放一个 biome.json（或者 biome.jsonc），让 monorepo 下的 package 统一遵守。

下面给你一份“足够通用”的示例（重点是结构，不必逐字照抄）：

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "files": {
    "ignore": [
      "**/node_modules/**",
      "**/.nuxt/**",
      "**/.output/**",
      "**/dist/**",
      "**/build/**"
    ]
  }
}

几个关键点：

- `rules.recommended: true` 是最稳的起点：覆盖大量通用问题，但不会太激进
- `organizeImports.enabled: true` 很适合和格式化一起做（但注意可能改变导入顺序）
- `files.ignore` 在 Nuxt/构建产物较多的项目里非常关键，否则会慢且噪音大

---

## 5. 命令与脚本：把“检查”和“修复”分开

团队协作里，最容易引起争议的是：到底什么时候该自动改代码？

建议脚本按用途拆分：

- `lint`：只检查（CI 用）
- `lint:fix`：检查 + 自动修复（本地用）
- `format`：格式化（本地/CI 都可用）

示例（以 pnpm 为例）：

```json
{
  "scripts": {
    "biome:check": "biome check .",
    "biome:fix": "biome check . --write",
    "biome:format": "biome format . --write"
  }
}

实践建议：

本地：优先让开发者跑 biome:fix（能修的尽量自动修）
CI：优先跑 biome:check（只做门禁，不改代码）

6. 在 VS Code 里用起来：让“保存即修复”成为默认体验

工具链成功与否，很大程度取决于“日常体验”。

建议做到两件事：

开发者安装 Biome 的 VS Code 扩展
项目提供统一的 workspace settings（可选，但强烈推荐）

一个常见做法是在仓库根目录放 .vscode/settings.json（如果团队接受）：

保存时格式化
保存时组织 imports

这样能把“格式化争论”直接消灭在源头：保存一次就统一了。

7. CI 门禁：只做检查，不做修复

CI 的最佳实践是：

失败要清晰
不要在 CI 里改代码（否则会引入“CI 提交”或者状态漂移）

以 GitHub Actions 为例（示意）：

name: quality
on:
  pull_request:

jobs:
  biome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm biome:check

如果你是 monorepo，并且不同 package 有不同需求，可以进一步细化为：