Biome 安装及使用

发表于 分类于
从零上手 Biome，完成安装、初始化配置、格式化与代码检查，以及 VS Code 集成。

前言

前端工程里，ESLint 负责代码检查，Prettier 负责代码格式化，这是多年来的标准组合。
但两者需要各自独立配置，规则可能冲突，执行速度在大仓库下也越来越让人难以忍受。
Biome 是一个用 Rust 编写的统一工具链，将格式化、代码检查、导入排序整合到单个二进制文件中。
它比 Prettier 快约 25 倍，比 ESLint 快约 15 倍，且与 Prettier 有 97% 以上的输出兼容性。
这篇文章会带你完成 Biome 的安装、初始化配置、命令行使用以及 VS Code 集成。

后文

经测试后，目前不推荐Prettier+ESLint迁移到Biome，原因看使用总结。

安装

Biome 推荐作为项目的开发依赖安装，这样可以确保团队使用一致的版本。
同时也支持通过 Homebrew 或直接下载二进制文件的方式安装。

npm

1
npm install -D -E @biomejs/biome

pnpm

1
pnpm add -D -E @biomejs/biome

yarn

1
yarn add -D -E @biomejs/biome

bun

1
bun add -D -E @biomejs/biome

-E 参数用于锁定精确版本，避免不同版本间格式化输出不一致。

Homebrew

如果你不使用 Node.js 生态，也可以通过 Homebrew 直接安装 Biome 的独立二进制。

1
brew install biome

验证安装

安装完成后，先确认命令可用。
下面命令会输出版本信息。

1
npx @biomejs/biome --version

初始化配置

Biome 可以零配置直接运行，但建议生成配置文件以按需调整规则。
下面命令会在项目根目录生成 biome.json。

1
npx @biomejs/biome init

生成的 biome.json 内容类似下面这样，包含了默认的格式化与 lint 配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "tab",
    "indentWidth": 2,
    "lineWidth": 120
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double"
    }
  }
}

基本使用

Biome 提供了几个核心 CLI 命令，覆盖格式化、代码检查和综合检查。

格式化

下面命令会格式化所有文件并直接写入。

1
npx @biomejs/biome format --write

如果只想检查格式而不修改文件，去掉 --write 即可。

1
npx @biomejs/biome format

也可以指定目录或文件。

1
npx @biomejs/biome format --write ./src

代码检查

下面命令会对所有文件执行 lint 检查并应用安全修复。

1
npx @biomejs/biome lint --write

lint 命令也支持指定路径。

1
npx @biomejs/biome lint --write ./src

综合检查

check 命令会同时执行格式化、代码检查和导入排序，是日常最常用的命令。

1
npx @biomejs/biome check --write

CI 模式

在 CI 流水线中使用 ci 命令，它只报告问题而不修改文件，适合用于拦截不合规代码。

1
npx @biomejs/biome ci

配置详解

biome.json 支持多个配置块，下面介绍几个最常用的部分。

控制文件范围

通过 files 字段可以控制 Biome 处理哪些文件。

1
2
3
4
5
6
{
  "files": {
    "include": ["src/**/*.js", "src/**/*.ts"],
    "ignore": ["src/generated/**"]
  }
}

格式化配置

1
2
3
4
5
6
7
8
9
{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  }
}

代码检查配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noForEach": "off"
      },
      "style": {
        "noNonNullAssertion": "warn"
      }
    }
  }
}

导入排序

Biome 内置了导入排序功能，通过 organizeImports 开启。

1
2
3
4
5
{
  "organizeImports": {
    "enabled": true
  }
}

Scripts 集成

将常用命令收敛到 package.json 的 scripts 中，方便团队统一使用。

1
2
3
4
5
6
7
8
9
10
{
  "scripts": {
    "format": "biome format --write",
    "format:check": "biome format",
    "lint": "biome lint",
    "lint:fix": "biome lint --write",
    "check": "biome check --write",
    "ci": "biome ci"
  }
}

注意这里直接写 biome 而非 npx @biomejs/biome，因为 npm scripts 会自动查找 node_modules/.bin 下的命令。

VS Code 集成

在 VS Code 扩展市场搜索并安装 Biome 官方扩展，标识为 biomejs.biome。

安装后，将 Biome 设为默认格式化器。
下面配置会为 JavaScript 和 TypeScript 文件启用 Biome 格式化。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  }
}

如果之前安装了 Prettier 扩展，建议卸载以避免冲突，因为 Biome 已经覆盖了同样的功能。

总结

Biome 用一个工具、一个配置文件替代了 ESLint + Prettier 的组合，大幅简化了前端工具链。
它的核心优势在于速度极快、配置简单、格式化与 lint 不会冲突。
建议新项目直接使用 Biome，现有项目也可以逐步迁移。
迁移时可以先在 CI 中并行运行 Biome 和原有工具，确认输出一致后再完全切换。

AI迁移

1
把项目中的 Prettier 和 ESLint 换为 Biome,并调整配置以贴近原 ESLint 行为。

使用总结

不建议直接迁过来

目前发现以下几个问题

  • 优化引用功能会误删代码
  • Biome 对 Vue 模板里的 HTML 注释处理有 bug，导致格式检查失败。
  • 变量在 <template> 里通过 ref="formRef" 使用，但 Biome 的 script 分析检测不到，导致大量 noUnusedVariables 警告。