配置 Biome

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

¥This guide will help you to understand how to configure Biome. It explains the structure of a Biome configuration file and how Biome resolves its configuration. If you are already familiar with the configuration, you may want to take a look at the configuration reference, which details all the options available.

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

¥Biome allows you to customize its behavior using CLI options or a configuration file named biome.json or biome.jsonc. We recommend that you create a configuration file for each project. This ensures that each team member has the same configuration in the CLI and in any editor that allows Biome integration. Many of the options available in a configuration file are also available in the CLI.

配置文件结构

¥Configuration file structure

Biome 配置文件名为 biome.json 或 biome.jsonc。它通常放置在项目根目录下，与项目中的 package.json 文件位于同一目录下。

¥A Biome configuration file is named biome.json or biome.jsonc. It is usually placed in your project’s root folder, next to your project’s package.json.

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

¥Because Biome is a toolchain, its configuration is organized around the tools it provides. At the moment, Biome provides three tools: the formatter, the linter and the assist. All of these tools are enabled by default. You can disable one or several of them using the <tool>.enabled field:

biome.json

{
  "$schema": "https://biome.nodejs.cn/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 文件的格式化程序。

¥Options that apply to more than one language are placed in the corresponding tool field. Language-specific options of a tool are placed under a <language>.<tool> field. This also allows overriding general options for a given language. You can also enable or disable a tool based on the language. In the following example, we configure the general options formatter.indentStyle and formatter.lineWidth for all the languages. Also, we set the JavaScript-specific option quoteStyle in javascript.formatter and we override formatter.lineWidth. We disabled the formatter for JSON files.

biome.jsonc

{
  "formatter": {
    "indentStyle": "space", // default is `tab`
    "lineWidth": 100 // default is `80`
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single", // default is `double`
      "lineWidth": 120 // override `formatter.lineWidth`
    }
  },
  "json": {
    "formatter": {
      "enabled": false
    }
  }
}

Note

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

¥Biome refers to all variants of the JavaScript language as javascript. This includes TypeScript, JSX and TSX.

配置文件解析度

¥Configuration file resolution

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

¥Biome uses auto discovery to find the nearest configuration file. It looks in the working directory and its parent folders until it finds a biome.json or a biome.jsonc file. If no configuration is found, Biome’s default configuration is used. If both biome.json and biome.jsonc are present in the same folder, biome.json is used.

这是一个例子：

¥Here’s an example:

• Directory

  app/

  • Directory

    backend/

    • biome.json

    • package.json

  • Directory

    frontend/

    • Directory

      legacy/

      • package.json
    • Directory

      new/

      • package.json

    • biome.json

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

  ¥Biome commands that run in app/backend/package.json will use the configuration file app/backend/biome.json;

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

  ¥Biome commands that run in app/frontend/legacy/package.json and app/frontend/new/package.json will use the configuration file app/frontend/biome.json;

Note

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

¥Biome (since v2.0.0) supports nested biome.json files. For more information, read Use Biome in big projects.

指定要处理的文件

¥Specifying files to process

你可以使用不同的策略（例如 CLI、配置和版本控制系统）来控制要处理的文件/文件夹。

¥You can control the files/folders to process using different strategies, either CLI, configuration and VCS.

Note

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

¥By default, Biome always ignores some files that are said to be protected files. This means that no diagnostics will be ever emitted by Biome for those files. At the moment, the following files are protected:

• composer.lock

• npm-shrinkwrap.json

• package-lock.json

• yarn.lock

通过命令行包含文件

¥Include files via CLI

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

¥The first way to control which files and folders are processed by Biome is to list them in the CLI. In the following command, we only format file1.js and all the files in the src folder, because folders are recursively traversed.

biome format file1.js src/

Caution

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

¥Glob patterns used on the command line are not interpreted by Biome. They are expanded by your shell. Some shells don’t support the recursive glob **.

通过配置控制文件

¥Control files via configuration

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

¥The Biome configuration file can be used to refine which files are processed. You can explicitly list the files to be processed using the files.includes field. files.includes accepts glob patterns such as src/**/*.js. Negated patterns starting with ! can be used to exclude files.

Biome 配置文件中的路径和 glob 模式是相对于配置文件所在文件夹解析的。但如果一个配置文件被另一个配置文件使用 extended，则此规则不适用。

¥Paths and globs inside Biome’s configuration file are resolved relative to the folder the configuration file is in. An exception to this is when a configuration file is extended by another.

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

¥files.includes applies to all of Biome’s tools, meaning the files specified here are processed by the linter, the formatter and the assist, unless specified otherwise. For the individual tools, you can further refine the matching files using <tool>.includes.

通过配置包含文件

¥Include files via configuration

我们来看以下配置，其中我们只想包含位于 src/ 文件夹和 test/ 文件夹内的 JavaScript 文件 (.js)，并忽略名称中包含 .min.js 的文件：

¥Let’s take the following configuration, where we want to include only JavaScript files (.js) that are inside the src/ folder, the test/ folder, and ignore files that have .min.js in their name:

biome.json

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

运行以下命令：

¥And run the following command:

biome format test/

该命令会格式化 test/ 文件夹中以 .js 扩展名结尾但不以 .min.js 扩展名结尾的文件。

¥The command will format the files that end with the .js extension and don’t end with the .min.js extension from the test/ folder.

由于该文件夹未在 CLI 中列出，因此 src/ 中的文件未被格式化。

¥The files in src/ are not formatted because the folder is not listed in the CLI.

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

¥If we run the following command, no files are linted because files inside the test/ folder are explicitly ignored for the linter.

biome lint test/

Caution

全局变量 files.includes 的语义与更具体的 <tool>.includes 字段略有不同。任何不匹配 files.includes 的文件或文件夹都将被 Biome 的所有工具排除在外。这意味着任何工具特定的 includes 字段都无法匹配一个未与 files.includes 匹配的文件。

¥The global files.includes has slightly different semantics than the more specific <tool>.includes fields. Any file or folder that doesn’t match files.includes is excluded from use by any of Biome’s tools. This means that any tool-specific includes field can never match a file that doesn’t also match files.includes.

通过配置排除文件

¥Exclude files via configuration

如果你想排除某些文件和文件夹，使其不被 Biome 处理，可以使用 files.includes 配置并使用否定模式：

¥If you want to exclude files and folders from being processed by Biome, you can use the files.includes configuration and use the negated patterns:

• 使用前导 ! 来忽略需要进行代码检查/格式化的文件

  ¥use of the leading ! to ignore files from being linted/formatted

• 使用双前导 !! 来忽略任何与项目相关的操作中的文件

  ¥use of the double leading !! to ignore files from any project-related operation

项目相关操作包括：

¥Project-related operations are:

• 构建内部模块图，以便 一些项目规则 可以解析导入和导出中的信息。

  ¥Construction of the internal module graph, so that some project rules can resolve information from imports and exports.

• 类型推断，以便类型感知代码检查规则可以纠正类型推断错误。

  ¥Inference of types, so that type-aware lint rules can correct infer types.

用于项目相关操作的文件会被建立索引。

¥A file that is considered for project-related operations is indexed.

在列出否定通配符之前，它们必须以 ** 模式开头。

¥Before listing the negated globs, they must be preceded by the ** pattern.

在以下示例中，我们指示 Biome 包含所有文件，但以下文件除外：

¥In the following example, we tell Biome to include all files, except:

• dist/ 文件夹将被所有项目相关操作忽略，因此不会被索引。

  ¥dist/ folder, which will be ignored from any project-related operation, hence they aren’t indexed.

• 任何以 .generated.js 结尾的文件都会被忽略，不会被格式化和检查，但仍会被索引。

  ¥Any file that ends .generated.js, which are ignored from formatting and linting, by are still indexed.

biome.json

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

有关如何与扫描器交互以及如何索引文件的更多信息，请查看 相对参考页面 文档。

¥For more information on how interact with scanner and how it indexes your files, check the relative reference page

通过版本控制系统控制文件

¥Control files via VCS

你可以使用 忽略 VCS 忽略的文件。

¥You can ignore files ignored by your VCS.

知名文件

¥Well-known files

以下是一些众所周知的文件，我们根据它们的文件名而不是扩展名来专门处理它们。目前，众所周知的文件只是 JSON 类文件，但当我们支持新的解析器时，我们可能会扩大列表以包含其他类型。

¥Here are some well-known files that we specifically treat based on their file names, rather than their extensions. Currently, the well-known files are JSON-like files only, but we may broaden the list to include other types when we support new parsers.

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

¥The following files are parsed as JSON files with both the options json.parser.allowComments and json.parser.allowTrailingCommas set to 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。这是因为使用这些文件的工具只能删除注释。

¥The following files are parsed as JSON files with the options json.parser.allowComments set to true but json.parser.allowTrailingCommas set to false. This is because the tools consuming these files can only strip comments.

• .ember-cli

• .eslintrc.json

• .jscsrc

• .jshintrc

• tslint.json

• turbo.json

以下文件解析为 JSON 文件，选项 json.parser.allowComments 和 json.parser.allowTrailingCommas 设置为 true。这是因为使用这些文件的工具旨在适应此类设置。

¥The following files are parsed as JSON files with the options json.parser.allowComments and json.parser.allowTrailingCommas set to true. This is because the tools consuming these files are designed to accommodate such settings.

• .babelrc

• .babelrc.json

• .devcontainer.json

• .hintrc

• .hintrc.json

• .oxlintrc.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