升级到 Biome v2

如果你有一个使用 Biome v1 的项目，并且想要升级到 v2，本指南将提供你所需的所有信息。

¥If you have a project that uses Biome v1, and you want to upgrade to v2, this guide will provide all the information you need.

通过 CLI 升级

¥Upgrade via CLI

使用你的包管理器安装 Biome 的 2.0.6 版本：
¥Use your package manager to install the version 2.0.6 of Biome:
- npm
- pnpm
- bun
- deno
- yarn
1 npm install --save-dev --save-exact @biomejs/biome@2.0.6
1 pnpm add --save-dev --save-exact @biomejs/biome@2.0.6
1 bun add --dev --exact @biomejs/biome@2.0.6
1 deno add --dev npm:@biomejs/biome@2.0.6
1 yarn add --dev --exact @biomejs/biome@2.0.6

运行 migrate 命令更新配置：

¥Run the migrate command to update the configuration:

1
npx @biomejs/biome migrate --write

1
pnpm exec biome migrate --write

1
bunx --bun biome migrate --write

1
deno run -A npm:@biomejs/biome migrate --write

1
yarn exec biome migrate --write

一切就绪！migrate 命令应该已经更新了你的配置，以缓解可能出现的重大变更问题。不过，请务必检查命令的输出；在某些情况下，你可能需要执行一些手动步骤。如果出现这种情况，迁移命令会指出错误所在。
¥You’re all set! The migrate command should have updated your configuration to mitigate possible breaking changes. Do check the output of the command however; in some cases it’s possible that you need to perform some manual steps. If so, the migrate command will point them out to you.

重大变更

¥Breaking changes

虽然项目和团队致力于减少破坏性变更的数量，但 v2 版本仍然存在一些值得解释的破坏性变更。本节将介绍最相关的设置，解释变更原因，并在适用情况下提供解决方案。

¥While the project and team are committed to reducing the number of breaking changes, v2 comes with some breakages that are worth explaining. This section will walk through the most relevant ones, and it will explain the reasons of the breaking change and provide a solution, if applicable.

不再支持 Rome 相关功能

¥Rome-related features aren’t supported anymore

所有与旧 Rome 项目相关的功能均不再受支持。如果你仍然依赖这些功能，则必须升级你的项目：

¥All features related to the old Rome project aren’t supported anymore. If you still relied on those features, you must upgrade your project:

将 rome.json 重命名为 biome.json。

¥rename rome.json to biome.json.
将 // rome-ignore 重命名为 // biome-ignore。

¥rename // rome-ignore to // biome-ignore.
将 ROME_BINARY 重命名为 BIOME_BINARY。

¥rename ROME_BINARY to BIOME_BINARY.
不再支持抑制注释格式 // biome-ignore lint(<GROUP_NAME>/<RULE_NAME>): <explanation>。改用 // biome-ignore lint/<GROUP_NAME>/<RULE_NAME>: <explanation>。

¥the suppression comment format // biome-ignore lint(<GROUP_NAME>/<RULE_NAME>): <explanation> is no longer supported. use // biome-ignore lint/<GROUP_NAME>/<RULE_NAME>: <explanation> instead.

选项 `--config-path` 是已移除

¥The option --config-path is removed

CLI 选项 --config-path 已从命令 biome lsp-proxy 和 biome start 中移除。

¥The CLI option --config-path is removed from the commands biome lsp-proxy and biome start.

该选项之前会覆盖 Biome 守护进程中打开的所有工作区的配置路径，导致在某些编辑器或 IDE 中打开多个项目时出现配置不匹配问题。

¥The option was overriding the configuration path for all workspaces opened in the Biome daemon, which led to a configuration mismatch problem when multiple projects are opened in some editors or IDEs.

如果你使用 LSP 兼容的编辑器，则可以使用其设置来定义项目的配置路径。

¥If you use an LSP-compatible editor, you can use its settings to define the configuration path of the project.

Zed
VS Code

1
{
2
  "lsp": {
3
    "biome": {
4
      "settings": {
5
         "configuration_path": "./frontend/biome.json"
6
      }
7
    }
8
  }
9
}

1
{
2
  "biome.lsp": {
3
    "configurationPath": "./frontend/biome.json"
4
  }
5
}

如果你是插件开发者，请更新你的插件，使其使用 workspace/configuration 响应而不是 --config-path 参数。Biome 的 LSP 会自动解析工作区中的配置，因此建议将其留空，除非你使用的是自定义配置路径。

¥If you are a developer of a plugin, please update your plugin to use the workspace/configuration response instead of using the --config-path argument. Biome’s LSP will resolve a configuration in the workspace automatically, so it is recommended to keep it empty unless you are using a custom configuration path.

选项 `ignore` 和 `include` 已移除，并替换为 `includes`

¥The options ignore and include are removed, and replaced by includes

如果你已经运行过 migrate 命令，则应该不会出现回归问题。将这两个字段合并为一个新字段的原因是，Biome 旧版 glob 引擎的实现存在缺陷，导致一些极端情况，除非我们更换引擎，否则无法修复。遗憾的是，我们无法在不进行重大更改的情况下实现这一点。

¥If you ran the command migrate already, you shouldn’t have regressions. The reason why these two fields were merged into a single new one was because the implementation of Biome’s old glob engine was flawed, causing some edge cases that we couldn’t fix unless we changed our engine. Unfortunately, we couldn’t do this without breaking changes.

之前的 glob 引擎会将匹配器 **/ 添加到用户提供的任何 glob 匹配项之前。这意味着 glob 模式 src/** 总是被转换为 **/src/**，这在某些情况下会导致一些意想不到的行为：

¥The previous glob engine would prepend the matcher **/to any user-provided glob. Which means that the glob src/** was always converted to **/src/**, causing some unexpected behavior in some cases:

	`/projectA/src/file.js`	`src/file.js`	`/projectB/frontend/src/file.js`
`src/**`	Glob 不匹配路径	Glob 匹配路径	Glob 不匹配路径
`/src/`	Glob 匹配路径	Glob 匹配路径	Glob 匹配

如你所见，glob **/src/** 过于激进，它会匹配不应该匹配的路径，例如 /Users/www/projectB/frontend/src/file.js。

¥As you can see, the glob **/src/** is too eager, and it matches paths that shouldn’t have, for example /Users/www/projectB/frontend/src/file.js.

从 v2 版本开始，Biome 将不再在 glob 模式前添加 **/。

¥From v2, Biome won’t prepend **/ to globs anymore.

在之前的 glob 引擎中，模式 * 可以匹配任何字符序列，包括路径分隔符 /。这意味着 glob 模式 **/src/*.js 总是会被转换为 **/src/**/*.js。从 v2 版本开始，Biome * 将不再匹配路径分隔符 /。

¥In the previous glob engine the pattern * matched against any sequence of characters, including the path separator /. Which means that the glob **/src/*.js was always converted to **/src/**/*.js. From v2, Biome * won’t match the path separator /.

路径和 glob 现在相对于配置文件

¥Paths and globs are now relative to the configuration file

在 v1 版本中，配置文件中声明的 glob 模式和文件路径均相对于工作目录。此行为可能会导致一些意外行为，尤其是在来自其他工具时。

¥In v1, globs and files declared in the configuration file were relative to the working directory. This behavior could cause some unexpected behaviour, especially if coming from other tools.

在以下示例中，配置文件位于项目根目录，check 命令从子目录运行，并配置为仅分析 src/ 文件夹内的文件。

¥In the following example, the configuration file is at root of the project, the check command is run from a subdirectory and configured to analyze only files inside the src/ folder.

biome.json
Directory
src/
- deploy.js
Directory
ui/
- package.json
- Directory
  src/
  - main.tsx
  - utils.ts

1
{
2
  "name": "@org/ui",
3
  "publish": false,
4
  "scripts": {
5
    "check": "biome check"
6
  }
7
}

1
{
2
  "files": {
3
    "includes": ["src/**"]
4
  }
5
}

在 v1 版本中，运行 npm run check 时，会发生以下情况：

¥In v1, when you run npm run check, the following happens:

Biome 会在 ui/ 中查找 biome.json。

¥Biome looks for biome.json inside ui/
未找到配置文件，Biome 开始检查父文件夹。

¥No configuration file found, Biome starts checking the parent folders
Biome 会在父文件夹中查找 biome.json。

¥Biome finds biome.json in the parent folder
工作目录为 ui/，因为 CLI 命令是在此目录中运行的。

¥The working directory is ui/, because that’s where the CLI commands was ran
Biome 会在 src/** 前添加 ui/。

¥Biome prepend ui/ to src/**
全局变量 ui/src/** 匹配 ui/src/main.tsx 和 ui/src/utils.ts，但不匹配 src/deploy.js。

¥The glob ui/src/** matches ui/src/main.tsx and ui/src/utils.ts, but it doesn’t match src/deploy.js
分析了两个文件

¥Two files are analyzed

在 v2 版本中，运行 npm run check 时，会发生以下情况：

¥In v2, when you run npm run check, the following happens:

Biome 会在 ui/ 中查找 biome.json。

¥Biome looks for biome.json inside ui/
未找到配置文件，Biome 开始检查父文件夹。

¥No configuration file found, Biome starts checking the parent folders
Biome 会在父文件夹中查找 biome.json。

¥Biome finds biome.json in the parent folder
全局变量 src/** 不匹配 ui/src/main.tsx 和 ui/src/utils.ts，但匹配 src/deploy.js。

¥The glob src/** doesn’t match ui/src/main.tsx and ui/src/utils.ts, but matches src/deploy.js
仅分析一个文件

¥One file is analyzed

要与之前的行为保持一致，必须将 glob 模式更新为 ui/src/**：

¥To match the previous behavior, the glob must be updated to ui/src/**:

1
{
2
  "files": {
3
    "includes": ["ui/src/**"]
4
  }
5
}

选项 `all` 已从代码检查器中移除

¥The option all is removed from the linter

在 Biome 的早期版本中，我们引入了 all，用于启用代码检查器的所有规则，或启用属于某个组的所有规则。当时，Biome 的规则很少，维护成本对于维护者和终端用户来说都非常低。我们毫不犹豫地添加了该选项。

¥In the very early versions of Biome, we introduced all as a mean to enable all rules of the linter, or enable all rules that belong to a group. At that time, Biome had few rules, and their maintenance cost was very low to the maintainers and the end-users. We didn’t think twice, and we just added it.

现在 Biome 拥有超过 300 条规则，其中一些规则相互冲突，导致项目无法修复规则违规，因为一个修复会触发另一个规则，反之亦然。

¥Now Biome has more than 300 rules, and some of those rules conflict with each other, causing situations where a project can’t fix the violations of the rules, because one fix triggers another rule, and vice versa.

我们决定暂时搁置该选项，并在未来以其他形式重新推出，或许会采用不同的语义和配置。我们意识到此次重大变更可能会带来一些不便。

¥We decided to take a step back, remove the option, and introduce it in the future in some other form, maybe with different semantics and configuration. We are aware that this breaking change can cause some inconvenience.

项目维护者已经在 Discord 和 GitHub 上讨论此主题。欢迎你参与讨论，帮助我们找到一个好的解决方案。

¥The maintainers of the project are already discussing the topic on Discord and GitHub. You are encouraged to take part in the conversation and help us find a good solution.

作为一种有限的替代方案，你可以启用推荐规则并启用所有代码检查域。但是，你无法禁用单个规则，而且域名 react 和 solid 启用的规则彼此冲突：

¥As limited workaround, you can enable the recommended rules, and enable all the linter domains. However, you can’t disable single rules, and the domains react and solid enable rules that conflict with each other:

1
{
2
  "linter": {
3
    "domains": {
4
      "next": "all",
5
      "react": "all",
6
      "test": "all",
7
      "solid": "all",
8
      "project": "all"
9
    },
10
    "rules": {
11
      "recommended": true
12
    }
13
  }
14
}

不再支持语法 `assert`

¥Syntax assert no longer supported

assert 语法已达到 Stage 3 阶段，不再受支持，并已被 with 语法取代。

¥The assert syntax, which reached Stage 3, is no longer supported, and it was replaced by the with syntax.

所有 Node.js 的 LTS 版本、所有浏览器引擎和无服务器运行时均支持新语法。

¥All LTS versions of Node.js support the new syntax, as well as all browser engines and serverless runtimes.

1
import {test} from "foo.json" assert { for: "for" }
2
export * from "mod" assert { type: "json" }
3
import {test} from "foo.json" with { for: "for" }
4
export * from "mod" with { type: "json" }

lint 的工作方式有所不同

¥The linter works differently

在 v1 版本中，代码检查器的工作方式如下：

¥In v1, the linter worked as follows:

默认情况下，推荐规则仅发出错误诊断信息。

¥The recommended rules, by default, emit only diagnostics with error.
不推荐的规则需要手动启用，并且用户必须决定其严重程度。

¥The non-recommended rules needed to be manually enabled, and the user had to decide the severity.

这种工作方式与其他代码检查工具（例如 ESLint、clippy、golint 等）略有不同，而且功能非常有限。

¥This way of working was a bit different from other linters (ESLint, clippy, golint, etc.), and it was very limited.

在 v2 版本中，代码检查器的工作方式与其他代码检查器类似，这意味着：

¥In v2, the linter works like other linters do, which means the following:

每条规则都关联一个默认的严重级别，由 Biome 建议。

¥Every rule is associated with a default severity level, suggested by Biome.
推荐规则可以发出不同严重程度的诊断信息。

¥The recommended rules can emit diagnostics of different severity.
用户现在可以使用规则的默认严重性，也可以自行选择严重性。

¥Users can now avail of the default severity of a rule, or choose the severity themselves.

如果你依赖于推荐规则来始终发出错误，则 biome migrate 命令会将这些规则的严重性设置为 "error"。

¥If you relied on recommended rules to always emit an error, the biome migrate command will set the severity of those rules to "error".

`style` 规则不再报错

¥style rules don’t emit errors anymore

过去几个月，我们收到了许多关于我们推荐规则的宝贵反馈。我们意识到，平衡 “recommended” 规则集对用户来说是一项挑战。虽然有些人很喜欢我们的默认设置，但也有人认为它们过于繁琐。

¥We received a lot of great feedback in the past months regarding our recommended rules. We realized that it’s challenging to balance a “recommended” set of rules for our users. While some really liked our defaults, others thought that they were too noisy.

从 v2 版本开始，除非另有配置，否则所有属于 XX1 组的规则都不会发出错误。如果你启用了某些功能，biome migrate 命令会更新配置，使其仍然能够发出错误。确保配置符合你的标准。

¥From v2, all rules that belong to the style group won’t emit an error unless configured otherwise. The biome migrate command will update the configuration so they still emit errors if you had them enabled. Make sure that the configuration conforms to your standards.

`package.json` 的不同默认格式

¥Different default formatting of package.json

Biome 现在使用不同的默认值格式化 package.json 文件。现在，无论对象和数组的宽度如何，它们始终以多行格式显示：

¥Biome now formats package.json with different defaults. Now objects and arrays are always formatted on multiple lines, regardless of their width:

1
{ "name": "project", "dependencies": { "foo": "^1.0.0" } }
2
{
3
 "name": "project",
4
 "dependencies": {
5
   "foo": "^1.0.0"
6
 }
7
}

如果你喜欢之前的格式化样式，则需要对配置进行覆盖，并将 "auto" 用作 expand 选项的值：

¥If you liked the previous formatting style, you’ll have to add an override to the configuration, and use the "auto" as value of the expand option:

1
{
2
  "overrides": [{
3
    "includes": ["package.json"],
4
    "json": {
5
      "formatter": {
6
        "expand": "auto"
7
      }
8
    }
9
  }]
10
}

导入组织器对导入的排序方式有所不同

¥The import organizer sorts the imports differently

Biome v2 配备了全新的导入管理器，包含许多新功能：

¥Biome v2 comes with a new import organizer with many new features:

它支持自定义排序。

¥It supports customizing the sorting.
组织 export 语句。

¥It organizes export statements.
它会忽略 import 语句之间的空行。

¥It ignores blank lines between import statements.
合并 import/export。

¥It merges import/export.
其默认排序比以前更加一致。

¥Its default sorting is more consistent than before.

所有这些更改都可能导致项目中导入和导出的排序发生变化。配置也已从专用字段 organizeImports 移至字段辅助操作。biome migrate 负责按如下方式移动配置：

¥All these changes can lead to different sorting of the imports and exports of your project. The configuration has also been moved from a dedicated organizeImports field to an assist action. biome migrate takes care of moving the configuration as follows:

1
{
2
   "organizeImports": { "enabled": true }
3
   "assist": { "actions": { "source": { "organizeImports": "on" } } }
4
}

新旧默认排序器之间的一个显著区别是，不带 node: 协议的 Node.js 模块不再被置于其他导入之前。例如，以下导入语句在 Biome 1.x 中被排序：

¥One significant difference between the old and new default sorters is that Node.js modules without the node: protocol are no longer placed before other imports. For example, the following imports were sorted in Biome 1.x:

1
import fs from "node:fs";
2
import path from "path";
3
import pkg from "@a/package";

在 Biome 2.0 中，它们的排序如下：

¥In Biome 2.0, they are sorted as follows:

1
import fs from "node:fs";
2
import pkg from "@a/package";
3
import path from "path";

要恢复旧的行为，请使用如下自定义顺序：

¥To restore the old behavior, use a custom order as follows:

1
{
2
    "assist": {
3
        "actions": {
4
            "source": {
5
                "organizeImports": {
6
                    "level": "on",
7
                    "options": {
8
                        "groups": [
9
                            // Bun modules
10
                            ":BUN:",
11
                            // Node.js modules
12
                            ":NODE:",
13
                            // Modules imported with the `npm:` protocol
14
                            ["npm:*", "npm:*/**"],
15
                            // Modules imported with another protocol. e.g. `jsr:`
16
                            ":PACKAGE_WITH_PROTOCOL:",
17
                            // URLs
18
                            ":URL:",
19
                            // Libraries
20
                            ":PACKAGE:",
21
                            // Absolute paths
22
                            ["/**"],
23
                            // Sharp aliases
24
                            ["#*", "#*/**"],
25
                            // All other paths
26
                            ":PATH:"
27
                        ]
28
                    }
29
                }
30
            }
31
        }
32
    }
33
}

请注意，无法实现与 Biome v1.x 完全相同的行为。我们建议使用新的默认设置，它更加一致且简单。

¥Please note that it is not possible to achieve exactly the same behavior as Biome v1.x. We recommend using the new default, which is much more consistent and simpler.

阅读导入管理器的文档了解更多详情。

¥Read the documentation of the import organizer for more details.

Zed 扩展 `v0.2.0` 与 v1 版本不兼容

¥Zed extension v0.2.0 isn’t compatible with v1

新版 Zed 扩展与 Biome v1 不兼容，因为 --config-path 已不再受支持。团队尝试保持向后兼容性，但遗憾的是，Zed 对扩展作者的调试功能非常有限。

¥The new version of the Zed extension isn’t compatible with Biome v1, because --config-path isn’t supported anymore. The team tried to maintain backwards compatibility, but unfortunately Zed has very limited debugging capabilities for extension authors.

VS Code 扩展 v3 需要完全重启

¥VS Code extension v3 needs complete restart

虽然这与 Biome v2 没有直接关系，但新版本的 VS Code 扩展使用不同的方法连接到 Biome Daemon。如果你升级了扩展程序，并且使用 "source.fixAll.biome": "explicit"，则在保存时可能会遇到代码错误。要解决此问题，你需要：

¥While this isn’t directly related to Biome v2, the new version of the VS Code extension uses a different method to connect to the Biome Daemon. If you upgrade the extension, it’s possible you might experience incorrect code upon save if you use "source.fixAll.biome": "explicit". To fix this, you need to:

升级扩展；

¥upgrade the extension;
关闭编辑器；

¥close the editor;
终止可能存在的悬空 biome 进程；

¥kill possible dangling biome processes;
重启编辑器；

¥restart the editor;

Biome v2.1 中文网 - 粤ICP备13048890号

Nodejs.cn 旗下网站

升级到 Biome v2

通过 CLI 升级

重大变更

不再支持 Rome 相关功能

选项 --config-path 是已移除

选项 ignore 和 include 已移除，并替换为 includes

路径和 glob 现在相对于配置文件

选项 all 已从代码检查器中移除

不再支持语法 assert