第 1 章 · 认识 Biome 与安装

1.1 Lint 与 Format：两件经常被混淆的事

每个 JavaScript/TypeScript 项目几乎都要同时面对两件事：一是格式化（Formatting），二是静态检查（Linting）。它们的目标并不相同，只是经常捆绑执行。

Formatter（格式化工具）: 机械地重排代码外观——缩进、引号、逗号、行宽、换行等。不看"代码对不对"，只看"好不好看"。代表：Prettier、dprint。
Linter（静态检查工具）: 基于 AST 做逻辑/模式识别，报告潜在 Bug、反模式、不安全 API、可读性问题。通常可 auto-fix 其中一部分。代表：ESLint、Biome lint、Oxlint。
Type Checker（类型检查）: 以项目级类型图为依据，检查类型一致性。Biome 不做这件事——tsc 仍然是你的朋友。
Import Organizer（导入整理）: 对 import 语句排序、去重、分组。ESLint 时代由 eslint-plugin-import 做，Biome 内置为独立功能。

过去十年的"事实标准"组合是 ESLint + Prettier。但它有两个痛点：两份配置、两份运行成本；并且它们会在"分号该不该加"这类风格上互掐，人们只能引入 eslint-config-prettier 关掉冲突规则。Biome 的野心就是把这两件事合到一个工具里。

1.2 Biome 的来龙去脉

Biome 的前身叫 Rome——2020 年由 Babel 作者 Sebastian McKenzie 发起，目标是"一个二进制覆盖前端全部工具链"。2023 年 Rome 公司解散，原班核心成员 fork 出 Biome 继续维护。

2023-08：Biome 1.0 发布，格式化稳定，lint 规则起步
2024：规则数量追上 ESLint 常用子集（200+），Prettier 兼容度达 97%
2025：Biome 2.0 引入 domain（next/react/solid 等领域规则组）、基于 TS 类型的规则、CSS/GraphQL 支持、GritQL 自定义规则

官方口号是 One toolchain for your web project。在 2026 年，Next.js、Astro、Turborepo、Bun、Shadcn CLI 等脚手架的"推荐配置"一栏已经默认列出 Biome。

1.3 Biome vs ESLint / Prettier / Oxc / dprint

维度	Biome	ESLint + Prettier	Oxc / Oxlint	dprint
语言	Rust	JS	Rust	Rust
格式化	✅	✅（Prettier）	❌（只 lint）	✅
Lint 规则	280+	几百（需装 plugin）	400+（超集）	❌
配置数量	1 份	2 份	1 份	1 份
速度	快	慢（JS）	最快	快
生态成熟度	高	最高	中（2025 才 1.0）	中
IDE 生态	VSCode/Zed/JB	各 IDE	VSCode	VSCode

简单总结：

Biome——想"一个工具搞定 format+lint"、希望 Prettier 行为兼容、项目规模中大型——当前最平衡的选择。
ESLint + Prettier——已经深度依赖特定 plugin（例如 eslint-plugin-testing-library 的复杂规则）、短期不想动——继续用，Biome 可作为 format 子集叠加。
Oxc/Oxlint——只要 lint、追求极致速度（10M LOC 不到 1 秒）、愿意接受较新生态。
dprint——仅做格式化，且需要非 JS 语言（Markdown/TOML/JSON）时很好。

1.4 安装

Biome 以 npm 包 @biomejs/biome 发布，内部是预编译的 Rust 二进制，按平台自动挑选。

# 推荐：作为项目 devDependency（CI 可重现）
npm install --save-dev --save-exact @biomejs/biome

# 或使用 pnpm/yarn/bun
pnpm add -D --save-exact @biomejs/biome
bun add -d --exact @biomejs/biome

# 一次性试用（不装）
npx @biomejs/biome --version
bunx @biomejs/biome --version

为什么推荐 --save-exact

Biome 规则在小版本之间可能新增/收紧；锁死版本能避免 CI 某天突然报一堆 新的 lint error。升级时手动跑 biome migrate 迁移。

1.5 第一次 init

npx @biomejs/biome init

执行后项目根目录出现 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": "tab"
  }
}

这已经是一份能工作的配置：lint 开启官方推荐规则，formatter 开启使用 tab 缩进。后面章节会逐节扩展。

1.6 第一次跑 Biome

# 格式化 src 下所有文件（只预览，不改动）
npx biome format ./src

# 带 --write 真正落盘
npx biome format --write ./src

# 只跑 lint
npx biome lint ./src

# format + lint + import organize 一口气全做
npx biome check --write ./src

三个核心命令

format 只管格式化、lint 只管 lint、check 是两者组合（再加 organizeImports）。日常开发用 check 即可，format / lint 更多出现在 CI 分工里。

1.7 加到 package.json

{
  "scripts": {
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "format": "biome format --write .",
    "ci": "biome ci ."
  }
}

biome ci 是专为 CI 设计的命令——它在 check 基础上加了"任何格式化差异也算失败"的严格模式，且输出 GitHub Actions 注释格式。第 8 章会详细讲。

小结

Biome 用一个 Rust 二进制把 lint + format + import 组织合到一起，解决了 ESLint/Prettier 多配置、双运行、速度慢的老问题。通过 biome init 可以在 10 秒内拿到一份可用配置，日常用 biome check --write 就能同时完成格式化与修复。下一章我们把 biome.json 拆开讲清楚每个字段。