跳转到内容
Biome
Docs Enterprise Playground
博客

配置 Biome

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

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

配置文件结构

Section titled “配置文件结构”

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

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

biome.json
{
  "$schema": "https://biomejs.dev/schemas/2.0.5/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
    }
  }
}

配置文件解析

Section titled “配置文件解析”

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

以下是一个示例：

  • 文件夹app/
    • 文件夹backend/
      • biome.json
      • package.json
    • 文件夹frontend/
      • 文件夹legacy/
        • package.json
      • 文件夹new/
        • 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；

指定要处理的文件

Section titled “指定要处理的文件”

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

通过 CLI 包含文件

Section titled “通过 CLI 包含文件”

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

Terminal window
biome format file1.js src/

通过配置控制文件

Section titled “通过配置控制文件”

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

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

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

通过配置包含文件

Section titled “通过配置包含文件”

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

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

并运行以下命令：

Terminal window
biome format test/

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

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

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

Terminal window
biome lint test/

通过配置排除文件

Section titled “通过配置排除文件”

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

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

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

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

通过 VCS 控制文件

Section titled “通过 VCS 控制文件”

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

知名文件

Section titled “知名文件”

以下是一些我们根据文件名而非扩展名特别处理的知名文件。 目前，知名文件仅为类 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

Copyright (c) 2023-present Biome Developers and Contributors.