配置 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.

配置文件结构

Section titled 配置文件结构

¥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 directory, next to your project’s package.json.

因为 Biome 是一个工具链，所以它的配置是围绕它提供的工具组织的。目前，Biome 提供三种工具：格式化程序、linter 和导入排序器（也称为导入组织器）。所有这些工具都是默认启用的。你可以使用 <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 import sorter (also called the import organizer). 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/1.8.3/schema.json",
  "formatter": {
    "enabled": false
  },
  "linter": {
    "enabled": false
  },
  "organizeImports": {
    "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 as javascript all variants of the JavaScript language. This includes TypeScript, JSX and TSX.

配置文件解析度

Section titled 配置文件解析度

¥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 in the parent directories until it finds a biome.json or a biome.jsonc file. If no configuration is found, then it applies Biome’s defaults. If both biome.json and biome.jsonc are present in the same folder, the priority will be given to biome.json.

这是一个例子：

¥Here’s an example:

• Directory

  app

  • Directory

    backend

    • biome.json

    • package.json

  • Directory

    frontend

    • biome.json

    • Directory

      legacy

      • package.json
    • Directory

      new

      • package.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;

Caution

Biome 不支持嵌套的 biome.json 文件，无论是在 CLI 还是在 LSP 中。关注并帮助相关问题中的支持

¥Biome doesn’t support nested biome.json files, neither in CLI nor in LSP. Follow and help the support in the related issue

Note

Biome 命令支持使用 --config-path 选项和 BIOME_CONFIG_PATH 环境变量。这允许你指定自定义配置文件或 Biome 可以在其中查找 biome.json 或 biome.jsonc 文件的目录。当你使用 --config-path 或 BIOME_CONFIG_PATH 时，标准配置文件解析过程被禁用。

¥Biome commands support using the --config-path option and the BIOME_CONFIG_PATH environment variable. This allows you to specify a custom configuration file or a directory where Biome can look for a biome.json or biome.jsonc file. When you use --config-path or BIOME_CONFIG_PATH, the standard configuration file resolution process is disabled.

如果 --config-path 或 BIOME_CONFIG_PATH 直接指向文件，则可以使用除 biome.json 或 biome.jsonc 之外的名称。Biome 将使用标准 JSON 解析器读取 .json 文件。对于具有其他扩展名的文件，Biome 会将它们视为 .jsonc 文件，使用更灵活的 JSON 解析器，允许注释和尾随逗号。

¥If --config-path or BIOME_CONFIG_PATH points directly to a file, you can use names other than biome.json or biome.jsonc. Biome will read a .json file using a standard JSON parser. For files with other extensions, Biome will treat them as .jsonc files, using a more flexible JSON parser that allows comments and trailing commas.

共享配置文件

Section titled 共享配置文件

¥Share a configuration file

extends 字段允许你将配置拆分到多个文件中。这样，你可以在不同的项目或文件夹之间共享通用设置。

¥The extends field allows you to split your configuration across multiple files. This way, you can share common settings across different projects or folders.

以下是你可能如何设置配置以扩展 common.json 配置文件的示例：

¥Here’s an example of how you might set up your configuration to extend a common.json configuration file:

biome.json

{
  "extends": ["./common.json"]
}

从定义 biome.json 文件的路径解析 extends 中定义的条目。它们按照列出的顺序进行处理，后面文件中的设置将覆盖前面的设置。

¥The entries defined in extends are resolved from the path where the biome.json file is defined. They are processed in the order they are listed, with settings in later files overriding earlier ones.

Biome 能够解析来自 node_modules/ 目录的配置文件。这样你就可以从包中导出配置文件，并将其导入到多个项目中。

¥Biome is able to resolve configuration files from the node_modules/ directory. So you can export your configuration file from a package, and import it in multiple projects.

为此，首先要做的是以某种方式设置 “shared” Biome 配置。假设你想使用说明符 @org/shared-configs/biome 共享来自名为 @org/shared-configs 的包的配置。你必须在此包的 package.json 中创建一个 exports 条目：

¥In order to do so, the first thing to do is to set up your “shared” Biome configuration in a certain way. Let’s suppose that you want to share a configuration from a package called @org/shared-configs, using the specifier @org/shared-configs/biome. You have to create an exports entry in the package.json of this package:

package.json

{
  "name": "@org/shared-configs",
  "type": "module",
  "exports": {
    "./biome": "./biome.json"
  }
}

确保 @org/shared-configs 已正确安装在你的项目中，并更新 biome.json 文件以使其看起来像以下代码片段：

¥Make sure that @org/shared-configs is correctly installed in your project, and update the biome.json file to look like the following snippet:

biome.json

{
  "extends": ["@org/shared-configs/biome"]
}

Biome 将尝试从你的工作目录中解析库 @org/shared-configs/。工作目录是：

¥Biome will attempt to resolve your library @org/shared-configs/ from your working directory. The working directory is:

• 使用 CLI 时，你从中执行脚本的目录。通常它与你的 package.json 文件的位置相匹配；

  ¥when using the CLI, the directory where you execute your scripts from. Usually it matches the location of your package.json file;

• 使用 LSP 时，项目的根目录。

  ¥when using the LSP, the root directory of your project.

Caution

为了避免对现有解析方式产生重大更改，以点 . 开头或以 .json 或 .jsonc 结尾的路径将不会从 node_modules/ 解析。

¥To avoid a breaking change with how the existing resolution works, paths starting with a dot . or ending with .json or .jsonc won’t be resolved from node_modules/.

有关解析算法的更多信息，请参阅 Node.js 文档。

¥For more information about the resolution algorithm, refer to the Node.js documentation.

忽略文件

Section titled 忽略文件

¥Ignore files

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

¥The first way to control which files and directories are processed by Biome is to list them in the CLI. In the following command, we format only file1.js and all the files in the src directory. The directories 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 **.

Biome 配置文件可用于优化要处理的文件。你可以明确列出要使用 include 处理的文件和不使用 ignore 处理的文件。include 和 ignore 接受诸如 src/**/*.js 之类的 glob 模式。有关支持哪些 glob 语法，请参阅 相关部分。在应用 ignore 之前，始终先应用 include。这允许你包含一些文件并忽略你包含的某些文件。

¥The Biome configuration file can be used to refine which files are processed. You can explicitly list the files to be processed using include and the files not to be processed using ignore. include and ignore accepts globs patterns such as src/**/*.js. See the related section for which glob syntaxes are supported. include is always applied first before applying ignore. This allows you to include some files and to ignore some of the file you included.

Note

include 和 ignore 的语义略有不同。include 不会阻止 Biome 遍历文件夹。这意味着如果你想阻止 Biome 遍历文件夹，则必须将该文件夹添加到 ignore。

¥include and ignore have a slightly different semantics. include doesn’t prevent Biome of traversing a folder. This means that if you want to prevent Biome from traversing a folder, you have to add the folder to ignore.

Biome 提供适用于所有工具的全局 files.include 和 files.ignore 字段。你还可以使用 <tool>.include 和 <tool>.ignore 在工具级别包含和忽略文件。请注意，它们不会覆盖全局 X​​X1 和 files.ignore。files.include 和 files.ignore 首先在工具的 include 和 ignore 之前应用。

¥Biome provides global files.include and files.ignore fields that apply to all tools. You can also include and ignore files at tool level using <tool>.include and <tool>.ignore. Note that they don’t override the global files.include and files.ignore. files.include and files.ignore are applied first before a tool’s include and ignore.

让我们采用以下配置：

¥Let’s take the following configuration:

biome.json

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

运行以下命令：

¥And run the following command:

biome format test/

该命令将格式化 test 目录中以 .js 扩展名结尾但不以 .min.js 扩展名结尾的文件。src 中的文件未格式化，因为目录未在 CLI 中列出。

¥The command will format the files that end with the .js extension and doesn’t end with the .min.js extension from the test directory. The files in src are not formatted because the directory is not listed in the CLI.

如果我们运行以下命令，则不会对任何文件进行 lint，因为 test 目录被 linter 明确忽略。

¥If we run the following command, no files are linted because the test directory is explicitly ignored for the linter.

biome lint test/

Biome 从工作目录中相对解析 glob。工作目录是你通常运行 CLI 命令的目录。这意味着当配置文件放在与执行命令不同的目录中时，你必须特别注意。对于编辑器 (LSP)，工作目录是项目的根目录。

¥Biome resolves the globs relatively from the working directory. The working directory is the directory where you usually run a CLI command. This means that you have to place particular attention when the configuration file is placed in a different directory from where you execute your command. In the case of an editor (LSP) the working directory is the root directory of your project.

让我们以一个包含两个目录 backend/ 和 frontend/ 的项目以及我们之前介绍的 Biome 配置文件为例。在 frontend/ 目录中，package.json 指定运行 Biome 格式化程序的 format 脚本。

¥Let’s take a project that contains two directories backend/ and frontend/, and the Biome configuration file that we introduced earlier. Inside the frontend/ directory, a package.json specifies a format script that runs the Biome formatter.

• Directory

  backend

  • …

• biome.json

• Directory

  frontend

  • package.json

  • Directory

    src

    • …
  • Directory

    test

    • …

frontend/package.json

{
  "name": "frontend-project",
  "scripts": {
    "format": "biome format --write ./"
  }
}

当你从 frontend/package.json 运行脚本 format 时，该脚本解析的工作目录将是 frontend/。globs src/**/*.js 和 test/**/*.js 将具有 “base” 目录 frontend/。因此，只有来自 frontend/src/ 和 frontend/test/ 的文件才会被格式化。

¥When you run the script format from frontend/package.json, the working directory resolved by that script will be frontend/. The globs src/**/*.js and test/**/*.js will have as “base” directory frontend/. Thus, only the files from frontend/src/ and frontend/test/ will be formatted.

biome.json

{
  "files": {
    "include": ["src/**/*.js", "src/**/*.ts"],
    "ignore": ["test"]
  },
  "formatter": {
    "indentStyle": "space"
  }
}

Caution

overrides 内的 ignore 和 include 具有不同的语义：

¥ignore and include inside overrides have a different semantics:

• 对于 ignore：如果文件与 glob 匹配，则不要应用此覆盖中的配置，并继续应用下一个覆盖；

  ¥for ignore: if a file matches the globs, don’t apply the configuration inside this override, and keep apply the next overrides;

• 对于 include：如果文件与 glob 匹配，则应用此覆盖中的配置，并继续应用下一个覆盖；

  ¥for include: if a file matches the globs, apply the configuration inside this override, and keep apply the next overrides;

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

Note

你也可以 忽略 VCS 忽略的文件。

¥You can also ignore files ignored by your VCS.

知名文件

Section titled 知名文件

¥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

• .swcrc

• api-documenter.json

• api-extractor.json

• babel.config.json

• deno.json

• devcontainer.json

• dprint.json

• jsconfig.json

• jsr.json

• language-configuration.json

• tsconfig.json

• typedoc.json

• typescript.json

Glob 语法说明

Section titled Glob 语法说明

¥Glob syntax explained

glob 模式指定一组文件名。Biome 支持以下 glob：

¥A glob pattern specifies a set of filenames. Biome supports the following globs:

• * 匹配零个或多个字符。它无法匹配路径分隔符 /。

  ¥* matches zero or more characters. It cannot match the path separator /.

• ** 递归匹配目录和文件。此序列必须形成单个路径组件，因此 **a 和 b** 都无效并将导致错误。连续两个以上的 * 字符序列也是无效的。

  ¥** recursively matches directories and files. This sequence must form a single path component, so both **a and b** are invalid and will result in an error. A sequence of more than two consecutive * characters is also invalid.

• [...] 匹配括号内的任何字符。还可以指定字符范围，按 Unicode 排序，例如 [0-9] 指定 0 到 9 之间的任何字符（含）。

  ¥[...] matches any character inside the brackets. Ranges of characters can also be specified, as ordered by Unicode, so e.g. [0-9] specifies any character between 0 and 9 inclusive.

• [!...] 是 [...] 的否定，即它匹配括号中没有的任何字符。

  ¥[!...] is the negation of [...], i.e. it matches any characters not in the brackets.

一些示例：

¥Some examples:

• dist/** 匹配 dist 目录和此目录中的所有文件。

  ¥dist/** matches the dist directory and all files in this directory.

• **/test/** 匹配名为 test 的任何目录下的所有文件，无论它们位于何处。例如dist/test, src/test.

  ¥**/test/** matches all files under any directory named test, regardless of where they are. E.g. dist/test, src/test.

• **/*.js 匹配所有目录中以扩展名 .js 结尾的所有文件。

  ¥**/*.js matches all files ending with the extension .js in all directories.

Biome 使用 glob 库，将所有 glob 视为具有 **/ 前缀。这意味着 src/**/*.js 和 **/src/**/*.js 被视为相同。它们与 src/file.js 和 test/src/file.js 匹配。

¥Biome uses a glob library that treats all globs as having a **/ prefix. This means that src/**/*.js and **/src/**/*.js are treated as identical. They match both src/file.js and test/src/file.js.

Caution

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

¥These patterns can be used in a Biome configuration file. 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 **