biome

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Biome

Biome

Fast, unified linting, formatting, and import organization for JavaScript, TypeScript, JSX, CSS, and GraphQL. Biome 2.4 provides type-aware linting without the TypeScript compiler, GritQL plugins for custom rules, and domain-based rule grouping. Single binary, zero config by default, 97% Prettier compatibility.
针对JavaScript、TypeScript、JSX、CSS和GraphQL的快速、统一lint、格式化与导入整理工具。Biome 2.4无需TypeScript编译器即可提供类型感知lint能力,支持用于自定义规则的GritQL插件,以及基于领域的规则分组。单二进制文件,默认零配置,与Prettier兼容性达97%。

Critical Rules

关键规则

files.ignore
DOES NOT EXIST - use
files.includes
with negation

files.ignore
不存在 - 请使用带否定模式的
files.includes

Biome 2.x only supports
files.includes
(with an
s
). There is NO
files.ignore
, NO
files.include
(without
s
), NO
files.exclude
. Using any of these will throw
Found an unknown key
errors.
The only valid keys under
files
are:
includes
,
maxSize
,
ignoreUnknown
,
experimentalScannerIgnores
.
To exclude files (generated code, vendored files, etc.), use negation patterns in
files.includes
:
json
{
  "files": {
    "includes": ["**", "!**/routeTree.gen.ts", "!**/generated/**"]
  }
}
Do NOT use
overrides
with
linter/formatter/assists: { enabled: false }
to skip generated files - that approach is fragile (easy to miss a subsystem like assists/import organizer) and unnecessarily complex. Just exclude via
files.includes
.
Biome 2.x仅支持
files.includes
(末尾带s)。不存在
files.ignore
files.include
(末尾不带s)、
files.exclude
这类配置项,使用任何不存在的配置项都会抛出
Found an unknown key
错误。
files
下仅支持以下合法配置项:
includes
maxSize
ignoreUnknown
experimentalScannerIgnores
如果需要排除文件(生成的代码、外部引入的vendored文件等),请在
files.includes
中使用否定模式:
json
{
  "files": {
    "includes": ["**", "!**/routeTree.gen.ts", "!**/generated/**"]
  }
}
请勿通过
overrides
配置
linter/formatter/assists: { enabled: false }
来跳过生成文件,这种方式非常脆弱(很容易漏掉assists/导入整理这类子系统)且不必要的复杂。直接通过
files.includes
排除即可。

Always use
biome check
, not separate lint + format

始终使用
biome check
,不要分开调用lint和format命令

biome check
runs formatter, linter, and import organizer in one pass. Never call
biome lint
and
biome format
separately in CI - use
biome check
(or
biome ci
for CI mode).
biome check
会一次执行格式化、lint检查和导入整理。永远不要在CI中分开调用
biome lint
biome format
,直接使用
biome check
(CI场景下使用
biome ci
)即可。

biome.json lives at project root

biome.json需放在项目根目录

Every project needs one
biome.json
at the root. Monorepo packages use nested configs with
"extends": "//"
to inherit from root. Never use relative paths like
"extends": ["../../biome.json"]
.
每个项目都需要在根目录放置一个
biome.json
。Monorepo的子包可以使用嵌套配置,通过
"extends": "//"
继承根目录的配置,不要使用
"extends": ["../../biome.json"]
这类相对路径。

Use
--write
to apply fixes, not
--fix

使用
--write
参数应用修复,不要用
--fix

bash
biome check --write .            # Apply safe fixes
biome check --write --unsafe .   # Apply all fixes (review changes)
bash
biome check --write .            # 应用安全修复
biome check --write --unsafe .   # 应用所有修复(请review修改内容)

Pin exact versions and migrate after upgrades

锁定精确版本,升级后执行迁移命令

bash
pnpm add --save-dev --save-exact @biomejs/biome@latest
pnpm biome migrate --write
bash
pnpm add --save-dev --save-exact @biomejs/biome@latest
pnpm biome migrate --write

Quick Start

快速开始

bash
pnpm add --save-dev --save-exact @biomejs/biome
pnpm biome init    # Creates default biome.json with recommended rules
bash
pnpm add --save-dev --save-exact @biomejs/biome
pnpm biome init    # 生成带推荐规则的默认biome.json

IDE Setup

IDE配置

VS Code - Install
biomejs.biome
extension:
json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit"
  }
}
Zed - Biome extension available natively. The
inline_config
feature (v2.4) lets editors override rules without affecting
biome.json
:
json
{
  "formatter": { "language_server": { "name": "biome" } },
  "lsp": {
    "biome": {
      "settings": {
        "inline_config": {
          "linter": { "rules": { "suspicious": { "noConsole": "off" } } }
        }
      }
    }
  }
}
VS Code - 安装
biomejs.biome
扩展:
json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit"
  }
}
Zed - 原生支持Biome扩展。v2.4新增的
inline_config
特性允许编辑器覆盖规则,不会影响
biome.json
配置:
json
{
  "formatter": { "language_server": { "name": "biome" } },
  "lsp": {
    "biome": {
      "settings": {
        "inline_config": {
          "linter": { "rules": { "suspicious": { "noConsole": "off" } } }
        }
      }
    }
  }
}

CI Integration

CI集成

bash
pnpm biome ci .                                  # No writes, non-zero exit on errors
pnpm biome ci --reporter=default --reporter=github .  # GitHub Actions annotations
bash
pnpm biome ci .                                  # 不写入文件,出现错误时返回非0退出码
pnpm biome ci --reporter=default --reporter=github .  # 生成GitHub Actions注解

Configuration (biome.json)

配置(biome.json)

Recommended config for React/TypeScript projects

React/TypeScript项目推荐配置

json
{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "includes": [
      "src/**/*.ts", "src/**/*.tsx",
      "tests/**/*.ts", "**/*.config.ts", "**/*.json",
      "!**/generated", "!**/components/ui"
    ]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 120
  },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true },
    "domains": { "react": "recommended" }
  },
  "javascript": {
    "formatter": { "quoteStyle": "double" }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": { "organizeImports": "on" }
    }
  }
}
json
{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "includes": [
      "src/**/*.ts", "src/**/*.tsx",
      "tests/**/*.ts", "**/*.config.ts", "**/*.json",
      "!**/generated", "!**/components/ui"
    ]
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 120
  },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true },
    "domains": { "react": "recommended" }
  },
  "javascript": {
    "formatter": { "quoteStyle": "double" }
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": { "organizeImports": "on" }
    }
  }
}

Formatter options

格式化选项

Key options:
indentStyle
(
"space"
/
"tab"
),
indentWidth
,
lineWidth
,
lineEnding
(
"lf"
/
"crlf"
),
trailingNewline
. JS-specific:
quoteStyle
,
trailingCommas
,
semicolons
,
arrowParentheses
,
bracketSpacing
.
核心选项:
indentStyle
"space"
/
"tab"
)、
indentWidth
lineWidth
lineEnding
"lf"
/
"crlf"
)、
trailingNewline
。JS专属选项:
quoteStyle
trailingCommas
semicolons
arrowParentheses
bracketSpacing

Linter rule configuration

Lint规则配置

Rules use severity levels
"error"
,
"warn"
,
"info"
, or
"off"
. Some accept options:
json
{
  "linter": {
    "rules": {
      "recommended": true,
      "style": {
        "noRestrictedGlobals": {
          "level": "error",
          "options": {
            "deniedGlobals": {
              "Buffer": "Use Uint8Array for browser compatibility."
            }
          }
        },
        "useComponentExportOnlyModules": "off"
      }
    }
  }
}
规则支持
"error"
"warn"
"info"
"off"
四种严重级别,部分规则支持自定义参数:
json
{
  "linter": {
    "rules": {
      "recommended": true,
      "style": {
        "noRestrictedGlobals": {
          "level": "error",
          "options": {
            "deniedGlobals": {
              "Buffer": "Use Uint8Array for browser compatibility."
            }
          }
        },
        "useComponentExportOnlyModules": "off"
      }
    }
  }
}

Import organizer

导入整理

The import organizer (Biome Assist) merges duplicates, sorts by distance, and supports custom grouping:
json
{
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              { "source": "builtin" },
              { "source": "external" },
              { "source": "internal", "match": "@company/*" },
              { "source": "relative" }
            ]
          }
        }
      }
    }
  }
}
导入整理功能(Biome Assist)会合并重复导入、按路径距离排序,支持自定义分组:
json
{
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": {
          "level": "on",
          "options": {
            "groups": [
              { "source": "builtin" },
              { "source": "external" },
              { "source": "internal", "match": "@company/*" },
              { "source": "relative" }
            ]
          }
        }
      }
    }
  }
}

Per-subsystem includes

子系统级别的includes配置

Each subsystem (
linter
,
formatter
,
assist
) has its own
includes
for fine-grained scoping. Applied after
files.includes
- can only narrow, not widen.
json
{
  "files": {
    "includes": ["**", "!**/dist"]
  },
  "linter": {
    "includes": ["**", "!**/components/ui"]
  },
  "formatter": {
    "includes": ["**", "!**/components/ui"]
  }
}
This lints and formats everything except
dist/
and
components/ui
, while assists (import organizer) still run on
components/ui
.
每个子系统(
linter
formatter
assist
)都有独立的
includes
配置用于细粒度控制作用范围,该配置会在
files.includes
之后生效,只能缩小范围不能扩大。
json
{
  "files": {
    "includes": ["**", "!**/dist"]
  },
  "linter": {
    "includes": ["**", "!**/components/ui"]
  },
  "formatter": {
    "includes": ["**", "!**/components/ui"]
  }
}
上述配置会对除了
dist/
components/ui
之外的所有文件执行lint和格式化,而导入整理(assist)仍然会对
components/ui
生效。

Overrides

Overrides配置

Overrides apply different settings to specific file patterns. Use for per-file rule tweaks (e.g., relaxing rules for vendored/shadcn components). The field is
includes
(with
s
).
json
{
  "overrides": [
    {
      "includes": ["**/components/ui/**"],
      "linter": {
        "rules": {
          "suspicious": { "noDocumentCookie": "off" },
          "style": { "useComponentExportOnlyModules": "off" }
        }
      }
    },
    {
      "includes": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": { "noConsole": "off" }
        }
      }
    }
  ]
}
Overrides可以为特定文件模式应用不同的配置,用于针对单个文件调整规则(比如放宽对外部引入/shadcn组件的规则限制)。对应的配置项是
includes
(末尾带s)。
json
{
  "overrides": [
    {
      "includes": ["**/components/ui/**"],
      "linter": {
        "rules": {
          "suspicious": { "noDocumentCookie": "off" },
          "style": { "useComponentExportOnlyModules": "off" }
        }
      }
    },
    {
      "includes": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": { "noConsole": "off" }
        }
      }
    }
  ]
}

Monorepo configuration

Monorepo配置

Root
biome.json
holds shared config. Package configs inherit with
"extends": "//"
:
json
{
  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
  "extends": "//"
}
Override specific rules per package by adding a
linter.rules
section alongside
"extends": "//"
.
根目录的
biome.json
存放共享配置,子包的配置通过
"extends": "//"
继承根配置:
json
{
  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
  "extends": "//"
}
可以在
"extends": "//"
旁新增
linter.rules
配置,为单个子包覆盖特定规则。

Configuration file discovery (v2.4)

配置文件查找顺序(v2.4)

Search order:
biome.json
->
biome.jsonc
->
.biome.json
->
.biome.jsonc
-> platform config home (
~/.config/biome
on Linux,
~/Library/Application Support/biome
on macOS).
查找顺序:
biome.json
->
biome.jsonc
->
.biome.json
->
.biome.jsonc
-> 平台配置目录(Linux下为
~/.config/biome
,macOS下为
~/Library/Application Support/biome
)。

Domains

领域规则

Domains group lint rules by technology. Enable only what your stack needs:
json
{
  "linter": {
    "domains": {
      "react": "recommended",
      "next": "recommended",
      "test": "recommended",
      "types": "all"
    }
  }
}
DomainPurposeAuto-detected
react
React hooks, JSX patterns
react
dependency
next
Next.js-specific rules
next >= 14.0.0
solid
Solid.js rules
solid-js
dependency
test
Testing best practices (any framework)-
playwright
Playwright test rules
@playwright/test
project
Cross-file analysis (noImportCycles, noUnresolvedImports)-
types
Type inference rules (noFloatingPromises, noMisusedPromises)-
Activation levels:
"recommended"
(stable rules only),
"all"
(includes nursery),
"none"
(disable).
The
project
domain enables rules needing the module graph. The
types
domain (v2.4) enables rules requiring type inference. Both trigger a file scan that adds a small overhead.
领域规则按技术栈对lint规则进行分组,你可以只启用你技术栈需要的规则:
json
{
  "linter": {
    "domains": {
      "react": "recommended",
      "next": "recommended",
      "test": "recommended",
      "types": "all"
    }
  }
}
领域用途自动检测条件
react
React hooks、JSX规范检查存在
react
依赖
next
Next.js专属规则存在
next >= 14.0.0
solid
Solid.js规则存在
solid-js
依赖
test
通用测试最佳实践(兼容所有测试框架)-
playwright
Playwright测试规则存在
@playwright/test
project
跨文件分析(noImportCycles、noUnresolvedImports)-
types
类型推导规则(noFloatingPromises、noMisusedPromises)-
启用级别:
"recommended"
(仅启用稳定规则)、
"all"
(包含实验性nursery规则)、
"none"
(禁用)。
project
领域会启用需要模块依赖图的规则,
types
领域(v2.4新增)会启用需要类型推导的规则,两者都会触发文件扫描,会带来极小的性能开销。

Type-Aware Linting

类型感知Lint

Biome 2.0 introduced type-aware linting without the TypeScript compiler. Biome has its own type inference engine in Rust - no
typescript
dependency needed.
Biome 2.0引入了无需TypeScript编译器的类型感知lint能力,Biome使用Rust自研的类型推导引擎,不需要依赖
typescript
包。

How it works

工作原理

Enable the
types
domain to activate file scanning and type inference. Performance impact is minimal compared to typescript-eslint because inference runs natively.
启用
types
领域即可激活文件扫描和类型推导,相比typescript-eslint,由于推导是原生执行的,性能影响极小。

Key rules

核心规则

RuleWhat it catches
noFloatingPromises
Unhandled promises (missing await/return/void)
noMisusedPromises
Promises in conditionals, array callbacks
useAwaitThenable
Awaiting non-thenable values
noUnnecessaryConditions
Conditions that are always true/false
useRegexpExec
string.match()
where
regexp.exec()
is better
useFind
array.filter()[0]
instead of
array.find()
useArraySortCompare
Array.sort()
without compare function
规则检查内容
noFloatingPromises
未处理的promise(缺少await/return/void标记)
noMisusedPromises
在条件判断、数组回调中错误使用promise
useAwaitThenable
对非thenable的值使用await
noUnnecessaryConditions
永远为真/假的条件判断
useRegexpExec
应该使用
regexp.exec()
的场景下使用了
string.match()
useFind
应该使用
array.find()
的场景下使用了
array.filter()[0]
useArraySortCompare
调用
Array.sort()
时未传入比较函数

noFloatingPromises

noFloatingPromises

The most impactful type-aware rule. Detects unhandled promises:
ts
// ERROR: floating promise
async function loadData() {
  fetch("/api/data");
}

// VALID: awaited
async function loadData() {
  await fetch("/api/data");
}

// VALID: explicitly voided (fire-and-forget)
async function loadData() {
  void fetch("/api/data");
}
Detects ~75% of cases compared to typescript-eslint, improving each release.
最有价值的类型感知规则,可以检测未处理的promise:
ts
// 报错:floating promise
async function loadData() {
  fetch("/api/data");
}

// 合法:加了await
async function loadData() {
  await fetch("/api/data");
}

// 合法:显式void标记(发后不管场景)
async function loadData() {
  void fetch("/api/data");
}
相比typescript-eslint,该规则可以检测约75%的场景,每个版本都会持续优化。

Limitations vs typescript-eslint

与typescript-eslint相比的局限

  • Complex generic type inference may miss some cases
  • Not a full type checker - handles common patterns, not every edge case
  • Rules still in nursery - expect improvements with each release
  • Major performance advantage: fraction of tsc-based linting time
  • 复杂的泛型推导可能会漏掉部分场景
  • 不是完整的类型检查器,仅覆盖常见场景,不会处理所有边界case
  • 规则仍在迭代中,每个版本都会持续优化
  • 巨大的性能优势:耗时仅为基于tsc的lint的几分之一

GritQL Custom Rules

GritQL自定义规则

GritQL is a declarative pattern-matching language for custom lint rules. Create
.grit
files and register them as plugins.
json
{ "plugins": ["./lint-rules/no-object-assign.grit"] }
GritQL是用于编写自定义lint规则的声明式模式匹配语言,你可以创建
.grit
文件并将其注册为插件。
json
{ "plugins": ["./lint-rules/no-object-assign.grit"] }

Examples

示例

Ban
Object.assign
:
grit
`$fn($args)` where {
    $fn <: `Object.assign`,
    register_diagnostic(
        span = $fn,
        message = "Prefer object spread instead of `Object.assign()`"
    )
}
CSS - enforce color classes:
grit
language css;
`$selector { $props }` where {
    $props <: contains `color: $color` as $rule,
    not $selector <: r"\.color-.*",
    register_diagnostic(
        span = $rule,
        message = "Don't set explicit colors. Use `.color-*` classes instead."
    )
}
禁止使用
Object.assign
grit
`$fn($args)` where {
    $fn <: `Object.assign`,
    register_diagnostic(
        span = $fn,
        message = "Prefer object spread instead of `Object.assign()`"
    )
}
CSS - 强制使用颜色类:
grit
language css;
`$selector { $props }` where {
    $props <: contains `color: $color` as $rule,
    not $selector <: r"\.color-.*",
    register_diagnostic(
        span = $rule,
        message = "Don't set explicit colors. Use `.color-*` classes instead."
    )
}

Plugin API

插件API

register_diagnostic()
arguments:
  • severity
    -
    "hint"
    ,
    "info"
    ,
    "warn"
    ,
    "error"
    (default:
    "error"
    )
  • message
    (required) - diagnostic message
  • span
    (required) - syntax node to highlight
Supported target languages: JavaScript (default), CSS, JSON (v2.4). Profile with
biome lint --profile-rules .
.
register_diagnostic()
参数:
  • severity
    -
    "hint"
    "info"
    "warn"
    "error"
    (默认:
    "error"
  • message
    (必填) - 诊断提示信息
  • span
    (必填) - 需要高亮的语法节点
支持的目标语言:JavaScript(默认)、CSS、JSON(v2.4新增)。可以通过
biome lint --profile-rules .
分析规则性能。

Suppression Patterns

忽略规则的方式

Single-line

单行忽略

ts
// biome-ignore lint/suspicious/noConsole: needed for debugging
console.log("debug info");
ts
// biome-ignore lint/suspicious/noConsole: 用于调试
console.log("debug info");

File-level

整个文件忽略

ts
// biome-ignore-all lint/suspicious/noConsole: logger module
ts
// biome-ignore-all lint/suspicious/noConsole: 日志模块

Range

范围忽略

ts
// biome-ignore-start lint/style/useConst: legacy code
let x = 1;
let y = 2;
// biome-ignore-end lint/style/useConst
const a = 4; // this line IS checked
biome-ignore-end
is optional - omit to suppress until end of file. Biome requires explanation text after the colon.
ts
// biome-ignore-start lint/style/useConst: 遗留代码
let x = 1;
let y = 2;
// biome-ignore-end lint/style/useConst
const a = 4; // 该行仍会被检查
biome-ignore-end
是可选的,省略的话会忽略到文件末尾。Biome要求忽略注释的冒号后必须填写说明文字。

Migration

迁移指南

From ESLint

从ESLint迁移

bash
pnpm biome migrate eslint --write
pnpm biome migrate eslint --write --include-inspired  # Include non-identical rules
Supports legacy and flat configs,
extends
resolution, plugins (typescript-eslint, react, jsx-a11y, unicorn),
.eslintignore
.
bash
pnpm biome migrate eslint --write
pnpm biome migrate eslint --write --include-inspired  # 包含非完全等价的规则
支持legacy和flat配置、
extends
解析、插件(typescript-eslint、react、jsx-a11y、unicorn)、
.eslintignore
文件。

From Prettier

从Prettier迁移

bash
pnpm biome migrate prettier --write
Maps
tabWidth
->
indentWidth
,
useTabs
->
indentStyle
,
singleQuote
->
quoteStyle
,
trailingComma
->
trailingCommas
.
bash
pnpm biome migrate prettier --write
自动映射配置:
tabWidth
->
indentWidth
useTabs
->
indentStyle
singleQuote
->
quoteStyle
trailingComma
->
trailingCommas

From ESLint + Prettier combo

从ESLint + Prettier组合迁移

bash
pnpm biome migrate eslint --write
pnpm biome migrate prettier --write
pnpm remove eslint prettier eslint-config-prettier eslint-plugin-prettier \
  @typescript-eslint/parser @typescript-eslint/eslint-plugin
rm .eslintrc* .prettierrc* .eslintignore .prettierignore
Enable VCS integration since ESLint respects gitignore by default:
json
{ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true } }
bash
pnpm biome migrate eslint --write
pnpm biome migrate prettier --write
pnpm remove eslint prettier eslint-config-prettier eslint-plugin-prettier \
  @typescript-eslint/parser @typescript-eslint/eslint-plugin
rm .eslintrc* .prettierrc* .eslintignore .prettierignore
由于ESLint默认会遵循gitignore,所以请开启VCS集成:
json
{ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true } }

CLI Reference

CLI参考

biome check (primary command)

biome check(核心命令)

bash
biome check .                    # Check all files
biome check --write .            # Apply safe fixes
biome check --write --unsafe .   # Apply all fixes
biome check --changed .          # Only VCS-changed files
biome check --staged .           # Only staged files
bash
biome check .                    # 检查所有文件
biome check --write .            # 应用安全修复
biome check --write --unsafe .   # 应用所有修复
biome check --changed .          # 仅检查VCS修改过的文件
biome check --staged .           # 仅检查暂存区的文件

biome ci (CI mode)

biome ci(CI模式)

bash
biome ci .                                           # No writes, exit code on errors
biome ci --reporter=github .                         # GitHub annotations
biome ci --reporter=sarif --reporter-file=report.sarif .  # SARIF output
bash
biome ci .                                           # 不写入文件,出现错误时返回非0退出码
biome ci --reporter=github .                         # 生成GitHub注解
biome ci --reporter=sarif --reporter-file=report.sarif .  # 输出SARIF格式报告

biome lint

biome lint

bash
biome lint --only=suspicious/noDebugger .    # Single rule
biome lint --skip=project .                  # Skip domain
biome lint --only=types .                    # Only type-aware rules
biome lint --error-on-warnings .             # Warnings become errors
bash
biome lint --only=suspicious/noDebugger .    # 仅执行单个规则
biome lint --skip=project .                  # 跳过指定领域的规则
biome lint --only=types .                    # 仅执行类型感知规则
biome lint --error-on-warnings .             # 将警告视为错误

Other commands

其他命令

bash
biome format --write .                       # Format only
biome search '`console.$method($args)`' .    # GritQL pattern search
biome rage                                   # Debug info for bug reports
biome explain noFloatingPromises             # Explain a rule
bash
biome format --write .                       # 仅执行格式化
biome search '`console.$method($args)`' .    # 执行GritQL模式搜索
biome rage                                   # 导出用于提交bug报告的调试信息
biome explain noFloatingPromises             # 查看规则说明

Best Practices

最佳实践

  1. Use
    biome check
    as your single command
    - combines format, lint, and import organization
  2. Start with
    recommended: true
    - disable individual rules as needed
  3. Enable relevant domains -
    react
    ,
    next
    ,
    test
    ,
    types
    based on your stack
  4. Enable VCS integration - respects
    .gitignore
    , enables
    --changed
    /
    --staged
  5. Use
    biome ci
    in pipelines
    - never writes files, clear exit codes
  6. Pin exact versions - avoid surprise rule changes between releases
  7. Run
    biome migrate --write
    after every upgrade
  8. Use
    --staged
    in pre-commit hooks
    :
    biome check --staged --write --no-errors-on-unmatched .
  9. Profile slow rules with
    biome lint --profile-rules
    (v2.4)
  10. Use GritQL plugins for project-specific patterns instead of disabling rules globally
  1. 使用
    biome check
    作为统一命令
    - 整合了格式化、lint和导入整理功能
  2. recommended: true
    开始
    - 按需禁用单个规则即可
  3. 启用相关领域规则 - 根据你的技术栈启用
    react
    next
    test
    types
    等领域
  4. 开启VCS集成 - 自动遵循
    .gitignore
    ,支持
    --changed
    /
    --staged
    参数
  5. 在CI流程中使用
    biome ci
    - 不会写入文件,退出码清晰
  6. 锁定精确版本 - 避免版本升级带来的规则意外变更
  7. 每次升级后执行
    biome migrate --write
  8. 在pre-commit钩子中使用
    --staged
    参数
    biome check --staged --write --no-errors-on-unmatched .
  9. 使用
    biome lint --profile-rules
    分析慢规则
    (v2.4新增)
  10. 使用GritQL插件实现项目专属规则,不要全局禁用规则

Gotchas

注意事项

These are real mistakes that have caused broken configs, dirty working trees, and wasted debugging time. Read before writing any Biome config.
  1. files.ignore
    ,
    files.include
    ,
    files.exclude
    do not exist.
    Only
    files.includes
    (with
    s
    ). Biome will throw
    Found an unknown key
    for anything else. See the first critical rule above.
  2. organizeImports
    is NOT a top-level config key.
    In Biome 2.x it moved under
    assist.actions.source.organizeImports
    . Using it at the top level is a config error.
  3. overrides
    that disable
    linter
    +
    formatter
    still run
    assist
    .
    If you use overrides to skip a generated file, the import organizer (an assist action) will still rewrite it. This silently dirties your working tree. Use
    files.includes
    negation to fully exclude a file instead.
  4. overrides
    field is
    includes
    (with
    s
    ), not
    include
    .
    Same naming as
    files.includes
    .
  5. biome check --write
    runs formatter + linter + assists in one pass.
    Any of these three can modify files. If a generated file keeps getting dirtied after
    check --write
    , check which subsystem is touching it - it's often the import organizer (assist), not the formatter or linter.
  6. --fix
    does not exist.
    The flag is
    --write
    .
    --fix
    will silently do nothing or error.
这些都是实际出现过的错误,会导致配置失效、工作区被意外修改、浪费调试时间,编写Biome配置前请仔细阅读。
  1. files.ignore
    files.include
    files.exclude
    不存在
    ,仅支持
    files.includes
    (末尾带s),使用其他配置项Biome会抛出
    Found an unknown key
    错误,参考上文第一条关键规则。
  2. organizeImports
    不是顶层配置项
    ,在Biome 2.x中该配置已经移动到
    assist.actions.source.organizeImports
    下,在顶层使用会触发配置错误。
  3. 禁用
    linter
    formatter
    overrides
    配置仍然会执行
    assist
    ,如果你使用overrides跳过生成文件,导入整理(assist动作)仍然会修改该文件,会悄无声息地污染你的工作区。请使用
    files.includes
    否定模式来完全排除文件。
  4. overrides
    的匹配字段是
    includes
    (末尾带s),不是
    include
    ,命名规则和
    files.includes
    一致。
  5. biome check --write
    会一次执行格式化、lint和assist
    ,三个子系统都可能修改文件。如果某个生成文件在执行
    check --write
    后总是被修改,请检查是哪个子系统修改了它,通常是导入整理(assist)而不是格式化或lint。
  6. --fix
    参数不存在
    ,对应的参数是
    --write
    ,使用
    --fix
    会静默无响应或者报错。

Resources

参考资源

For detailed lint rules by category with code examples, see rules-reference.md.
如需查看按分类整理的带代码示例的lint规则详情,请参考rules-reference.md