Biome 入门：现代 Web 开发工具链 🚀

更新于 2026-01-22

简介

JavaScript 和 TypeScript 开发通常需要多种工具来保证代码质量：使用 linter（代码检查器）捕获错误，使用 formatter（格式化工具）确保一致的代码风格，以及其他各种实用程序来维护项目的健康状态。传统上，开发者依赖于 ESLint、Prettier 以及各种插件——每种工具都需要单独配置和维护。

Biome 是一个用 Rust 编写的统一、高性能工具链，旨在简化这种碎片化的生态系统。Biome 在一个单一、连贯的软件包中提供 linting（代码检查）、formatting（格式化）及其他开发者工具，既快速又易于使用。

Biome 源自 Rome Tools 项目，并延续了其核心理念：Web 开发工具应当统一且简洁。通过在一个软件包中提供全面的功能集合，Biome 消除了在使用多个独立工具时经常出现的配置冲突和兼容性问题。

按 Enter 键或单击以全屏查看图片

为什么选择 Biome？

  • 性能卓越：使用 Rust 编写，Biome 相较于基于 JavaScript 的替代方案，在分析和格式化方面显著更快
  • 统一体验：一个工具取代多个工具，配置和行为保持一致
  • 零配置理念：开箱即用，内置合理默认值
  • 现代标准：基于当前 JavaScript/TypeScript 最佳实践构建
  • 积极维护：定期更新与改进
  • 安全检查：内置安全分析功能
  • 无障碍支持：内置 a11y（可访问性）规则

安装

让我们开始安装 Biome。你可以使用 npm、yarn 或 pnpm 将其添加到你的项目中：

# 使用 npm
npm install --save-dev @biomejs/biome

# 使用 yarn
yarn add --dev @biomejs/biome

# 使用 pnpm
pnpm add --save-dev @biomejs/biome

要验证安装是否成功，请运行：

npx biome --version

基础设置

初始化 Biome

Biome 无需配置即可运行，但建议在项目中初始化以自定义其行为。运行以下命令创建基本配置：

npx biome init

这将在项目根目录生成一个 biome.json 文件，包含默认设置。该文件大致如下所示：

{
  "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "correctness": {
        "noUnusedVariables": "error"
      },
      "suspicious": {
        "noExplicitAny": "error"
      },
      "style": {
        "useConst": "error"
      },
      "a11y": {
        "recommended": true
      },
      "complexity": {
        "recommended": true
      },
      "performance": {
        "recommended": true
      },
      "security": {
        "recommended": true
      }
    }
  },
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingComma": "es5",
      "semicolons": "always"
    }
  }
}

默认配置启用了以下功能：

  • 导入组织：自动对导入语句进行排序和分组
  • 代码检查：启用推荐规则以捕获常见问题
  • 代码格式化：使用 2 个空格缩进设置一致的代码风格

然后我们需要更新 package.json。

按 Enter 键或单击以全屏查看图片

使用 Biome 的核心功能 🔧

代码格式化

使用以下命令格式化你的代码：

npm run format

// 或

npx biome format ./app

// 自动修复格式问题：
npx biome format --write ./app

代码检查（Linting）

检查代码质量问题：

npm run lint:check

// 或
npx biome lint ./app

// 自动修复某些代码检查问题：
npx biome lint --apply ./app

示例：

按 Enter 键或单击以全屏查看图片

同时运行代码检查和格式化

Biome 提供了一种便捷的方式来同时运行代码检查和格式化检查：

npm run check

// 或

npx biome check ./app

配置 Biome ⚙️

虽然 Biome 在默认配置下表现良好，但你可以通过 biome.json 文件对其进行自定义，以满足项目需求。

调整格式化选项

{
  "formatter": {
    "enabled": true,
    "indentStyle": "tab",
    "indentWidth": 4,
    "lineWidth": 100
  }
}

自定义代码检查规则

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "style": {
        "noNonNullAssertion": "off"
      },
      "suspicious": {
        "noExplicitAny": "error"
      }
    }
  }
}

忽略文件

你可以在 biome.json 中指定要忽略的文件：

{
  "files": {
    "ignore": ["dist/**", "build/**", "node_modules/**"]
  }
}

IDE 集成

Visual Studio Code

Biome 提供了官方的 VS Code 扩展：

  1. 从 VS Code 市场安装 “Biome” 扩展
  2. 在 settings.json 中进行配置：
{
  "editor.formatOnSave": true,
  "[javascript][typescript][javascriptreact][typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

WebStorm/IntelliJ IDEA

虽然目前还没有官方插件，但你可以将 Biome 设置为外部工具：

  1. 进入 Preferences > Tools > External Tools
  2. 添加一个新工具，指向你的 Biome 安装路径
  3. 将程序参数设置为 format --write $FilePathRelativeToProjectRoot$
  4. 将工作目录设置为 $ProjectFileDir$

将 Biome 与 Git Hooks 集成

将 Biome 与 Git hooks 结合使用，可以在提交前确保代码质量。安装 Husky 并使用 Biome 进行配置：

npm install --save-dev husky lint-staged
npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

然后在 package.json 中配置 lint-staged：

{
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": ["biome check --apply"]
  }
}

从 ESLint 和 Prettier 迁移

移除旧工具

如果你正从 ESLint 和 Prettier 迁移，可以移除它们：

npm uninstall eslint prettier eslint-config-* eslint-plugin-*

然后删除配置文件：

rm .eslintrc.* .prettierrc.*

规则差异

某些规则在 Biome 中的行为可能与 ESLint 或 Prettier 不同。请查阅 Biome 文档以了解规则的对应关系。

常见问题排查

配置未生效

如果你的配置未被应用：

  • 确认 biome.json 位于项目根目录
  • 检查配置文件中是否存在语法错误
  • 尝试使用 --verbose 标志运行以获取更多信息

性能问题

如果 Biome 运行缓慢：

  • 检查是否分析了过多文件（尤其是 node_modules 中的文件）
  • 确保 ignore 模式已正确设置

与其他工具冲突

如果你遇到冲突：

  • 确保没有对同一文件运行多个格式化工具
  • 移除其他 linting/formatting 工具，或为 Biome 处理的文件禁用它们
  • 检查是否存在冲突的编辑器扩展

结论

Biome 代表了 JavaScript/TypeScript 开发工具向前迈出的重要一步，它通过提供一个统一、高性能的解决方案来管理代码质量。通过用单一、连贯的系统取代多个工具，它简化了开发工作流并减少了配置开销。