配置 Biome

本指南将帮助您理解如何配置 Biome。 它解释了 Biome 配置文件的结构以及 Biome 如何解析其配置。 如果您已经熟悉配置，您可能希望查看配置参考，其中详细介绍了所有可用选项。

Biome 允许您使用名为 biome.json 或 biome.jsonc 的配置文件来自定义其行为。 我们建议您为每个项目创建一个配置文件。 这确保了每个团队成员在 CLI 和任何允许 Biome 集成的编辑器中都有相同的配置。 配置文件中的许多选项在 CLI 中也可用。

配置文件结构

Biome 配置文件命名为 biome.json 或 biome.jsonc。通常放置在项目根文件夹中，与项目的 package.json 相邻。

由于 Biome 是一个工具链，其配置围绕它提供的工具组织。 目前，Biome 提供三种工具：格式化器、检查器和辅助工具。 所有这些工具默认都是启用的。 您可以使用 <tool>.enabled 字段禁用其中一个或多个工具：

biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
  "formatter": {
    "enabled": false
  },
  "linter": {
    "enabled": false
  },
  "assist": {
    "enabled": false
  }
}

适用于多种语言的选项放置在相应的工具字段中。 特定语言的工具选项放置在 <language>.<tool> 字段下。 这也允许为特定语言覆盖通用选项。 您还可以基于语言启用或禁用工具。 在以下示例中，我们配置了适用于所有语言的通用选项 formatter.indentStyle 和 formatter.lineWidth。 同时，我们在 javascript.formatter 中设置了 JavaScript 特定选项 quoteStyle 并覆盖了 formatter.lineWidth。 我们为 JSON 文件禁用了格式化器。

biome.jsonc

{
  "formatter": {
    "indentStyle": "space", // 默认为 `tab`
    "lineWidth": 100 // 默认为 `80`
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single", // 默认为 `double`
      "lineWidth": 120 // 覆盖 `formatter.lineWidth`
    }
  },
  "json": {
    "formatter": {
      "enabled": false
    }
  }
}

Note

Biome 将所有 JavaScript 语言的变体都称为 javascript。 这包括 TypeScript、JSX 和 TSX。

配置文件解析

Biome 使用自动发现来找到最近的配置文件。 它在工作目录及其父文件夹中查找，直到找到 biome.json 或 biome.jsonc 文件。 如果未找到配置，则使用 Biome 的默认配置。 如果同一个文件夹中同时存在 biome.json 和 biome.jsonc，则使用 biome.json。

以下是一个示例：

• Folderapp/

  • Folderbackend/

    • biome.json
    • package.json
  • Folderfrontend/

    • Folderlegacy/

      • package.json
    • Foldernew/

      • package.json
    • biome.json

• 在 app/backend/package.json 中运行的 Biome 命令将使用配置文件 app/backend/biome.json；
• 在 app/frontend/legacy/package.json 和 app/frontend/new/package.json 中运行的 Biome 命令将使用配置文件 app/frontend/biome.json；

Note

Biome（自 v2.0.0 起）支持嵌套的 biome.json 文件。 欲了解更多信息，请阅读在大型项目中使用 Biome。

指定要处理的文件

您可以使用不同的策略控制要处理的文件/文件夹，包括 CLI、配置和 VCS。

Note

默认情况下，Biome 总是忽略一些被称为受保护文件的文件。 这意味着 Biome 永远不会为这些文件发出诊断信息。 目前，以下文件受到保护：

• composer.lock
• npm-shrinkwrap.json
• package-lock.json
• yarn.lock

通过 CLI 包含文件

控制 Biome 处理哪些文件和文件夹的第一种方法是在 CLI 中列出它们。 在以下命令中，我们只格式化 file1.js 和 src 文件夹中的所有文件，因为文件夹是递归遍历的。

biome format file1.js src/

Caution

命令行中使用的 glob 模式不由 Biome 解释。 它们由您的 shell 扩展。 某些 shell 不支持递归 glob **。

通过配置控制文件

Biome 配置文件可用于细化要处理的文件。 您可以使用 files.includes 字段显式列出要处理的文件。 files.includes 接受诸如 src/**/*.js 的 glob 模式。 以 ! 开头的否定模式可用于排除文件。

Biome 配置文件中的路径和 glob 相对于配置文件所在的文件夹解析。 一个例外是当配置文件被另一个文件 扩展时。

files.includes 适用于 Biome 的所有工具，这意味着指定的文件由检查器、格式化器和辅助工具处理，除非另有指定。 对于各个工具，您可以使用 <tool>.includes 进一步细化匹配的文件。

通过配置包含文件

让我们采用以下配置，其中我们只想包含 src/ 文件夹和 test/ 文件夹内的 JavaScript 文件（.js）， 并忽略文件名中包含 .min.js 的文件：

biome.json

{
  "files": {
    "includes": ["src/**/*.js", "test/**/*.js", "!**/*.min.js"]
  },
  "linter": {
    "includes": ["**", "!test/**"]
  }
}

并运行以下命令：

biome format test/

该命令将格式化 test/ 文件夹中以 .js 结尾且不以 .min.js 结尾的文件。

src/ 中的文件不会被格式化，因为 CLI 中未列出该文件夹。

如果我们运行以下命令，则不会检查任何文件，因为 test/ 文件夹中的文件在检查器中被显式忽略。

biome lint test/

Caution

全局 files.includes 与更具体的 <tool>.includes 字段的语义略有不同。 任何不匹配 files.includes 的文件或文件夹都会被排除在 Biome 的所有工具使用之外。 这意味着任何特定工具的 includes 字段永远无法匹配不匹配 files.includes 的文件。

通过配置排除文件

如果您想从 Biome 处理中排除文件和文件夹，可以使用 files.includes 配置并使用前导 ! 的否定模式。

在列出否定的 glob 之前，它们必须以 ** 模式开头。

在以下示例中，我们告诉 Biome 包含所有文件，除了任何 dist/ 文件夹中的文件以及以 .generated.js 结尾的文件：

biome.json

{
  "files": {
    "includes": [
      "**",
      "!**/dist",
      "!**/*.generated.js"
    ]
  }
}

通过 VCS 控制文件

您可以 忽略 VCS 忽略的文件。

知名文件

以下是一些我们根据文件名而非扩展名特别处理的知名文件。 目前，知名文件仅为类 JSON 文件，但当我们支持新解析器时，可能会扩展列表以包含其他类型。

以下文件被解析为 JSON 文件，且选项 json.parser.allowComments 和 json.parser.allowTrailingCommas 均设置为 false。

• .all-contributorsrc
• .arcconfig
• .auto-changelog
• .bowerrc
• .c8rc
• .htmlhintrc
• .imgbotconfig
• .jslintrc
• .nycrc
• .tern-config
• .tern-project
• .vuerc
• .watchmanconfig
• mcmod.info

以下文件被解析为 JSON 文件，其中 json.parser.allowComments 设置为 true，但 json.parser.allowTrailingCommas 设置为 false。 这是因为消费这些文件的工具只能剥离注释。

• .ember-cli
• .eslintrc.json
• .jscsrc
• .jshintrc
• tslint.json
• turbo.json

以下文件被解析为 JSON 文件，其中 json.parser.allowComments 和 json.parser.allowTrailingCommas 均设置为 true。 这是因为消费这些文件的工具被设计为适应此类设置。

• .babelrc
• .babelrc.json
• .devcontainer.json
• .hintrc
• .hintrc.json
• .swcrc
• api-documenter.json
• api-extractor.json
• babel.config.json
• deno.json
• devcontainer.json
• dprint.json
• jsconfig.json
• jsr.json
• language-configuration.json
• nx.json
• project.json
• tsconfig.json
• typedoc.json
• typescript.json