Back to Details

biome

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Biome Configuration

Biome配置

Deep Knowledge: Use 
mcp__documentation__fetch_docs
with technology: 
biome
for comprehensive documentation.
深度参考：使用
mcp__documentation__fetch_docs
工具，指定技术为
biome
以获取完整文档。

When NOT to Use This Skill

本技能的不适用场景

This skill is specific to Biome tooling. Do NOT use for:
  • ESLint configuration - Biome replaces ESLint; migrate or use ESLint skills
  • Prettier configuration - Biome replaces Prettier; migrate or use Prettier docs
  • TypeScript type checking - Use 
    tsc
    , not Biome (Biome doesn't type check)
  • Build process - Use bundler skills (Vite, Webpack, etc.)
  • Testing setup - Use testing framework skills (Vitest, Jest, etc.)
  • Code quality principles - Use 
    clean-code
    skill for what to fix, not how to configure
本技能仅针对Biome工具。请勿用于以下场景：
  • ESLint配置 - Biome可替代ESLint；如需配置ESLint请迁移至Biome或使用ESLint相关技能
  • Prettier配置 - Biome可替代Prettier；如需配置Prettier请迁移至Biome或查阅Prettier文档
  • TypeScript类型检查 - 使用
    tsc
    工具，Biome不提供类型检查功能
  • 构建流程 - 使用打包工具相关技能（如Vite、Webpack等）
  • 测试环境搭建 - 使用测试框架相关技能（如Vitest、Jest等）
  • 代码质量原则 - 如需了解代码优化方向，请使用
    clean-code
    技能，本技能仅负责配置实现

Anti-Patterns

反模式

Anti-PatternWhy It's BadBiome Best Practice
Disabling recommended rulesMisses important issuesKeep recommended, customize only what's needed
Ignoring all warningsWarnings indicate real issuesFix warnings or suppress with reason
No CI integrationIssues slip throughUse 
biome ci
in CI pipeline
Manual formattingInconsistent, waste timeUse format on save + pre-commit hooks
Mixing ESLint + BiomeConflicting rules, confusionFully migrate to Biome or stay with ESLint
No VS Code integrationManual CLI runsInstall Biome extension, enable format on save
Ignoring complexity rulesAllows unmaintainable codeSet cognitive complexity limits
Committing formatting issuesMessy diffsUse pre-commit hooks with lint-staged
反模式问题所在Biome最佳实践
禁用推荐规则遗漏重要代码问题保留推荐规则，仅按需自定义必要规则
忽略所有警告警告通常指向真实问题修复警告或附带原因后再忽略
未集成至CI代码问题可能流入生产在CI流水线中使用
biome ci
命令
手动格式化代码格式不一致且浪费时间开启保存时格式化 + 提交前钩子
同时使用ESLint与Biome规则冲突且易混淆完全迁移至Biome或继续使用ESLint
未配置VS Code集成需手动执行CLI命令安装Biome扩展并开启保存时格式化
忽略复杂度规则代码可维护性下降设置认知复杂度上限
提交存在格式问题的代码版本差异混乱使用lint-staged配合提交前钩子

Quick Troubleshooting

快速排查指南

IssueCheckSolution
Biome not formattingVS Code extension installed?Install 
biomejs.biome
, set as default formatter
Format on save not workingSettings.json configured?Add 
"editor.formatOnSave": true
Rules not applyingbiome.json syntax valid?Run 
biome check
to validate config
Too many warningsRules too strict?Adjust severity levels or disable specific rules
CI failingDifferent results locally?Ensure same Biome version, check ignore patterns
Conflicts with PrettierBoth running?Remove Prettier, Biome replaces it
Slow on large codebaseChecking too many files?Add ignore patterns in biome.json
Can't migrate from ESLintComplex config?Use 
biome migrate eslint
, review output
问题检查项解决方案
Biome未执行格式化是否已安装VS Code扩展？安装
biomejs.biome
扩展并设为默认格式化工具
保存时未自动格式化是否已配置settings.json？添加
"editor.formatOnSave": true
配置
规则未生效biome.json语法是否合法？执行
biome check
命令验证配置有效性
警告过多规则是否过于严格？调整规则严重级别或禁用特定规则
CI执行失败本地与CI结果是否一致？确保Biome版本一致，检查忽略规则配置
与Prettier冲突是否同时运行两者？移除Prettier，Biome可完全替代它
大型代码库运行缓慢是否检查了过多文件？在biome.json中添加忽略文件配置
无法从ESLint迁移配置是否过于复杂？使用
biome migrate eslint
命令并检查输出结果

Installation

安装

bash
npm install --save-dev @biomejs/biome
bash
npm install --save-dev @biomejs/biome

Initialize configuration

初始化配置

npx @biomejs/biome init
undefined
npx @biomejs/biome init
undefined

biome.json Configuration

biome.json配置

json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": {
            "maxAllowedComplexity": 15
          }
        }
      },
      "correctness": {
        "noUnusedVariables": "warn",
        "noUnusedImports": "warn",
        "useExhaustiveDependencies": "warn"
      },
      "style": {
        "noNonNullAssertion": "off",
        "useImportType": "warn"
      },
      "suspicious": {
        "noExplicitAny": "warn"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      "build",
      ".next",
      "coverage",
      "*.gen.ts"
    ]
  }
}
json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": {
            "maxAllowedComplexity": 15
          }
        }
      },
      "correctness": {
        "noUnusedVariables": "warn",
        "noUnusedImports": "warn",
        "useExhaustiveDependencies": "warn"
      },
      "style": {
        "noNonNullAssertion": "off",
        "useImportType": "warn"
      },
      "suspicious": {
        "noExplicitAny": "warn"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      "build",
      ".next",
      "coverage",
      "*.gen.ts"
    ]
  }
}

Package.json Scripts

package.json脚本

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

Common Rules

常用规则

RuleLevelDescription
noUnusedVariables
warnFlag unused variables
noUnusedImports
warnFlag unused imports
noExplicitAny
warnDiscourage 
any
type
useExhaustiveDependencies
warnCheck React hook deps
noNonNullAssertion
offAllow 
!
operator
useImportType
warnPrefer 
import type
规则级别描述
noUnusedVariables
warn标记未使用的变量
noUnusedImports
warn标记未使用的导入
noExplicitAny
warn不鼓励使用
any
类型
useExhaustiveDependencies
warn检查React钩子依赖项
noNonNullAssertion
off允许使用
!
操作符
useImportType
warn优先使用
import type

VS Code Integration

VS Code集成

json
// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}
json
// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

Pre-commit Hook

提交前钩子

bash
undefined
bash
undefined

Install husky

安装husky

npm install --save-dev husky lint-staged
npm install --save-dev husky lint-staged

package.json

package.json

{ "lint-staged": { "*.{js,jsx,ts,tsx}": [ "biome check --write --no-errors-on-unmatched" ] } }
undefined
{ "lint-staged": { "*.{js,jsx,ts,tsx}": [ "biome check --write --no-errors-on-unmatched" ] } }
undefined

Migration from ESLint/Prettier

从ESLint/Prettier迁移

bash
undefined
bash
undefined

Biome can migrate your config

Biome可自动迁移配置

npx @biomejs/biome migrate eslint --write npx @biomejs/biome migrate prettier --write
undefined
npx @biomejs/biome migrate eslint --write npx @biomejs/biome migrate prettier --write
undefined

CLI Commands

CLI命令

bash
undefined
bash
undefined

Check all files

检查所有文件

biome check .
biome check .

Fix issues

修复问题

biome check --write .
biome check --write .

Format only

仅执行格式化

biome format --write .
biome format --write .

Lint only

仅执行代码检查

biome lint .
biome lint .

Check specific files

检查指定文件

biome check src/components/**/*.tsx
biome check src/components/**/*.tsx

CI mode (exit with error)

CI模式（出错时终止流程）

biome ci .
undefined
biome ci .
undefined

Ignoring Code

忽略代码

typescript
// Ignore next line
// biome-ignore lint/suspicious/noExplicitAny: needed for legacy API
const data: any = await fetch('/api');

// Ignore whole file (at top)
// biome-ignore-all lint/style/useImportType
typescript
// 忽略下一行
// biome-ignore lint/suspicious/noExplicitAny: needed for legacy API
const data: any = await fetch('/api');

// 忽略整个文件（置于文件顶部）
// biome-ignore-all lint/style/useImportType

Production Readiness

生产环境就绪指南

Recommended Configuration

推荐配置

json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "a11y": {
        "recommended": true
      },
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "error",
          "options": { "maxAllowedComplexity": 15 }
        },
        "noExcessiveNestedTestSuites": "warn"
      },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "useExhaustiveDependencies": "error"
      },
      "performance": {
        "noAccumulatingSpread": "warn",
        "noDelete": "warn"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error",
        "noGlobalEval": "error"
      },
      "suspicious": {
        "noExplicitAny": "warn",
        "noConsoleLog": "warn"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}
json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "a11y": {
        "recommended": true
      },
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "error",
          "options": { "maxAllowedComplexity": 15 }
        },
        "noExcessiveNestedTestSuites": "warn"
      },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "useExhaustiveDependencies": "error"
      },
      "performance": {
        "noAccumulatingSpread": "warn",
        "noDelete": "warn"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error",
        "noGlobalEval": "error"
      },
      "suspicious": {
        "noExplicitAny": "warn",
        "noConsoleLog": "warn"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}

CI Integration

CI集成

yaml
undefined
yaml
undefined

.github/workflows/lint.yml

.github/workflows/lint.yml

name: Lint
on: [push, pull_request]
jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - run: npm ci

  - name: Biome CI
    run: npx @biomejs/biome ci .

  # Or with caching
  - name: Cache Biome
    uses: actions/cache@v4
    with:
      path: ~/.cache/biome
      key: ${{ runner.os }}-biome-${{ hashFiles('biome.json') }}

  - name: Check
    run: npx @biomejs/biome check --diagnostic-level=error .
undefined
name: Lint
on: [push, pull_request]
jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

  - run: npm ci

  - name: Biome CI
    run: npx @biomejs/biome ci .

  # 或启用缓存
  - name: Cache Biome
    uses: actions/cache@v4
    with:
      path: ~/.cache/biome
      key: ${{ runner.os }}-biome-${{ hashFiles('biome.json') }}

  - name: Check
    run: npx @biomejs/biome check --diagnostic-level=error .
undefined

Git Hooks

Git钩子

json
// package.json
{
  "scripts": {
    "prepare": "husky install",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "lint:ci": "biome ci ."
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json}": [
      "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
    ]
  }
}
bash
undefined
json
// package.json
{
  "scripts": {
    "prepare": "husky install",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "lint:ci": "biome ci ."
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json}": [
      "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
    ]
  }
}
bash
undefined

.husky/pre-commit

.husky/pre-commit

#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh"
npx lint-staged
undefined
#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh"
npx lint-staged
undefined

Error Handling

错误处理

typescript
// biome.json - Configure severity levels
{
  "linter": {
    "rules": {
      // Block CI on these
      "correctness": {
        "noUnusedVariables": "error",
        "useExhaustiveDependencies": "error"
      },
      // Allow in development, fail in CI
      "suspicious": {
        "noConsoleLog": {
          "level": "warn",
          "options": {}
        }
      }
    }
  }
}

// Stricter CI check
// package.json
{
  "scripts": {
    "lint:dev": "biome check .",
    "lint:ci": "biome check --diagnostic-level=error --max-diagnostics=50 ."
  }
}
typescript
// biome.json - 配置规则严重级别
{
  "linter": {
    "rules": {
      // 阻塞CI流程的规则
      "correctness": {
        "noUnusedVariables": "error",
        "useExhaustiveDependencies": "error"
      },
      // 开发环境允许，CI环境报错
      "suspicious": {
        "noConsoleLog": {
          "level": "warn",
          "options": {}
        }
      }
    }
  }
}

// 更严格的CI检查
// package.json
{
  "scripts": {
    "lint:dev": "biome check .",
    "lint:ci": "biome check --diagnostic-level=error --max-diagnostics=50 ."
  }
}

Testing Integration

测试集成

typescript
// vitest.config.ts - Run biome before tests
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globalSetup: './src/test/global-setup.ts',
  },
});

// src/test/global-setup.ts
import { execSync } from 'child_process';

export default function setup() {
  try {
    execSync('npx @biomejs/biome check .', { stdio: 'pipe' });
  } catch (error) {
    console.error('Biome check failed. Fix linting issues before running tests.');
    process.exit(1);
  }
}
typescript
// vitest.config.ts - 运行测试前先执行Biome检查
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globalSetup: './src/test/global-setup.ts',
  },
});

// src/test/global-setup.ts
import { execSync } from 'child_process';

export default function setup() {
  try {
    execSync('npx @biomejs/biome check .', { stdio: 'pipe' });
  } catch (error) {
    console.error('Biome检查未通过，请先修复代码检查问题再运行测试。');
    process.exit(1);
  }
}

Monitoring Metrics

监控指标

MetricTarget
Lint errors0
Warnings< 10
Format issues0
Cognitive complexity< 15
指标目标值
代码检查错误0
警告数量< 10
格式问题0
认知复杂度< 15

Checklist

检查清单

  • Recommended rules enabled
  • Security rules enabled
  • a11y rules enabled
  • Cognitive complexity limit
  • CI integration with biome ci
  • Pre-commit hooks with lint-staged
  • VS Code extension configured
  • Console.log warnings
  • Unused variables as errors
  • VCS integration enabled
  • 已启用推荐规则
  • 已启用安全规则
  • 已启用无障碍（a11y）规则
  • 已设置认知复杂度上限
  • 已通过biome ci集成至CI
  • 已配置lint-staged配合提交前钩子
  • 已配置VS Code扩展
  • 已设置console.log为警告级别
  • 已将未使用变量设为错误级别
  • 已启用VCS集成

Reference Documentation

参考文档

  • Rules Reference
  • VS Code Setup
  • 规则参考
  • VS Code设置指南