VS Code 扩展

Biome 附带官方的 VS Code 扩展，它与你的代码编辑器紧密集成，为你的开发工作流程提供格式化、代码检查和重构功能。

¥Biome comes with an official VS Code extension that tightly integrates with your code editor, providing formatting, linting, and code refactoring features to your development workflow.

此参考文档概述了扩展的功能、安装方法以及如何为你的项目配置它。

¥This reference document provides an overview of the extension’s features, how to install it, and how to configure it for your projects.

Tip

如果你是从 2.x 版本升级，请查看本文档末尾的 迁移说明 版本。

¥If you’re upgrading from the 2.x version of the extension, check out the migration instructions at the end of this document.

安装扩展程序

¥Installing the extension

推荐的扩展安装方式是：VS Code 用户使用 Visual Studio Code Marketplace，VSCodium 和其他衍生工具（例如 Cursor）用户使用 Open VSX 注册表。

¥The recommended way to install the extension is through the Visual Studio Code Marketplace for VS Code users, or the Open VSX registry for VSCodium and other derivatives such as Cursor.

• 

• 

常见用例

¥Common use cases

单根工作区

¥Single-root workspaces

单根工作区是典型的 VS Code 工作区，其中只有一个工作区文件夹。

¥A single-root workspace is your typical VS Code workspace, where there is only one workspace folder.

• Directory

  src/

  • main.ts

• biome.json

• package.json

多根工作区

¥Multi-root workspaces

多根工作区是指包含多个工作区文件夹的工作区。在这种情况下，扩展程序将自动为每个工作区文件夹创建一个 Biome 实例。

¥A multi-root workspace is a workspace where there are multiple workspace folders. In this case, the extension will automatically create a Biome instance per workspace folder.

• Directory

  api/（工作区文件夹）

  ¥api/ (workspace folder)

  • biome.json

  • Directory

    src/

    • main.ts
• Directory

  app/（工作区文件夹）

  ¥app/ (workspace folder)

  • biome.json

  • Directory

    src/

    • main.ts

• my.code-workspace

功能

¥Features

格式化

¥Formatting

Biome 扩展将自身注册为 支持的文件类型 的格式化程序，并支持格式化整个文件或选定的代码。

¥The Biome extension registers itself as a formatter for supported file types, and supports formatting a whole file, or a selection of code.

从 命令面板 运行以下命令之一：

¥Run either one of the following commands from the command palette:

• 要格式化整个文件，请运行 Format Document 命令。

  ¥To format a whole file, run the Format Document command.

• 要格式化选定的代码，请选择代码并运行 Format Selection 命令。

  ¥To format a selection of code, select the code and run the Format Selection command.

保存时格式化

¥Formatting on save

要启用“保存时格式化”，请将 VS Code 的 editor.formatOnSave 设置设置为 true。

¥To enable formatting on save, set VS Code’s editor.formatOnSave setting to true.

代码修复

¥Code fixing

Biome 扩展将自身注册为 支持的文件类型 的代码操作提供程序，并为具有安全修复的诊断提供代码修复。

¥The Biome extension registers itself as a code action provider for supported file types, and provides code fixes for diagnostics that have safe fixes.

保存时修复

¥Fix on save

要启用“保存时修复”，请更新 VS Code 的 editor.codeActionsOnSave 设置以包含以下内容。这仅适用于 安全修复：

¥To enable Fix on Save, update VS Code’s editor.codeActionsOnSave setting to include the following. This will apply only the safe fixes:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit"
  }
}

如果你想在保存时应用 不安全修复，则必须执行 规则 safe 的代码修复。

¥If you want to apply unsafe fixes on save, you must make the code fix of the rule safe.

手动快速修复

¥Manual quick fixes

要手动应用快速修复，请选择诊断并单击 Quick Fix 按钮。

¥To manually apply a quick fix, select the diagnostic and click the Quick Fix button.

导入排序

¥Import sorting

该扩展程序能够在保存时对 支持的文件类型 的导入进行排序。要启用此功能，请将 VS Code 的 editor.codeActionsOnSave 设置更改为包含以下内容：

¥The extension is able to sort imports on save for supported file types. To enable this feature, set VS Code’s editor.codeActionsOnSave setting to include the following:

settings.json

{
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit"
  }
}

设置参考

¥Settings reference

以下设置可用于此扩展程序。

¥The following settings are available for the extension.

Settings precedence

所有设置均使用 VS Code 的 设置优先级 规则解析。这意味着将使用最具体级别的设置值。这允许你设置全局设置，并为特定的工作区文件夹覆盖它。

¥All settings are resolved using VS Code’s settings precedence rules. This means that the value of the setting at the most specific level will be used. This allows you to set a global setting, and override it for specific workspace folders.

biome.enabled

默认：true | 作用域：global, workspace, workspace folder

¥Default: true | Scopes: global, workspace, workspace folder

此设置控制扩展程序是否为工作区文件夹创建 LSP 会话。全局设置后，除非工作区文件夹本身覆盖了此设置，否则它将应用于所有工作区文件夹。

¥This setting controls whether the extension will create LSP session for a workspace folder. When set globally, it applies to all workspace folders, unless they themselves override the setting.

biome.configurationPath

Biome v2 only

此设置仅在使用 Biome v2 时生效。如果你使用的是 Biome v1，则此设置将被忽略。

¥This setting will only take effect when using Biome v2. If you are using Biome v1, this setting will be ignored.

默认：null | 作用域：global, workspace, workspace folder

¥Default: null | Scopes: global, workspace, workspace folder

此设置允许你指定自定义配置文件的路径。如果未指定，则使用默认配置文件。

¥This setting allows you to specify the path to a custom configuration file. If left unspecified, the default configuration file will be used.

biome.requireConfiguration

默认：false | 作用域：global, workspace, workspace folder

¥Default: false | Scopes: global, workspace, workspace folder

此设置控制 Biome 是否将自身注册为格式化程序和诊断提供程序。

¥This setting controls whether Biome will register itself as a formatter and diagnostics provider.

设置为 true 时，仅当工作区文件夹中存在 biome.json 文件时，扩展程序才会注册自身为格式化程序和诊断提供程序。

¥When set to true, the extension will only register itself as a formatter and diagnostics provider if a biome.json file is present in the workspace folder.

Caution

要使此设置生效，必须在同一作用域中将 biome.enabled 设置设为 true（默认值）。

¥The biome.enabled setting must be set to true (default) in the same scope for this setting to take effect.

biome.lsp.bin

默认：undefined | 作用域：global, workspace, workspace folder

¥Default: undefined | Scopes: global, workspace, workspace folder

此设置允许你覆盖 biome 二进制文件的路径。如果你想使用不同版本的 Biome，或者如果你想使用不在 PATH 上的二进制文件，这将非常有用。可以是二进制文件的路径，也可以是将平台映射到路径的对象。

¥This setting allows you to override the path to the biome binary. This is useful if you want to use a different version of Biome, or if you want to use a binary that’s not on your PATH. In can be either a path to a binary, or an object that maps a platform to a path.

string

{
  "biome.lsp.bin": "/path/to/biome"
}

object

使用对象时，键是平台标识符（由 <process.os>-<process.arch> 值构造），值是二进制文件的路径。

¥When using an object, the key is the platform identifier, constructed from the <process.os>-<process.arch> value, and the value is the path to the binary.

{
  "biome.lsp.bin": {
    "darwin-arm64": "/path/to/biome",
    "win32-x64": "/path/to/biome.exe"
  }
}

请注意，@biomejs/biome 不提供任何二进制文件。文件 @biomejs/biome/bin 只是一个很小的封装器，它将操作委托给真正的二进制文件。你机器上安装的二进制文件取决于你的操作系统和架构。

¥You should be aware of that @biomejs/biome doesn’t ship any binaries. The file @biomejs/biome/bin is just a tiny wrapper that delegates the operation to the real binary. The binary installed on your machine depends on the architecture of your OS and architecture.

二进制文件是以 @biomejs/cli-* 开头的软件包，位于 此列表 目录下。如果你指向的是通过 npm 安装的二进制文件，则配置如下所示：

¥The binaries are packages that start with @biomejs/cli-*, and can be found in this list. So, if you’re pointing to the binary installed via npm, the configuration will look like this:

string

{
  "biome.lsp.bin": "./node_modules/@biomejs/cli-linux-x64/bin"
}

object

使用对象时，键是平台标识符（由 <process.os>-<process.arch> 值构造），值是二进制文件的路径。

¥When using an object, the key is the platform identifier, constructed from the <process.os>-<process.arch> value, and the value is the path to the binary.

{
  "biome.lsp.bin": {
    "darwin-arm64": "./node_modules/@biomejs/cli-darwin-arm64/bin",
    "win32-x64": "./node_modules/@biomejs/cli-win32-x64/bin"
  }
}

biome.runFromTemporaryLocation

默认：true (windows), false (others) | 作用域：global, workspace, workspace folder

¥Default: true (windows), false (others) | Scopes: global, workspace, workspace folder

是否复制 Biome 二进制文件并从临时位置运行。

¥Whether to copy the Biome binary and run it from a temporary location.

在 Windows 系统中，禁用此设置将阻止你在 LSP 会话运行时更新 Node 模块中的 Biome，因为操作系统会在 LSP 运行时锁定该二进制文件。更新 Biome 之前，你需要关闭 VS Code。

¥On Windows, disabling this setting will prevent you from updating Biome in your node modules while an active LSP session is running, because the OS locks the binary while it’s running. You’ll need to close VS Code before updating Biome.

biome.suggestInstallingGlobally

默认：true | 作用域：global, workspace, workspace folder

¥Default: true | Scopes: global, workspace, workspace folder

当需要全局安装 Biome 但未在 PATH 类型中找到时，扩展程序会建议安装。

¥When a global installation of Biome is required but not found in the PATH, the extension will suggest installing it.

此设置控制是否显示建议弹出窗口。

¥This setting controls whether that suggestion popup is shown.

biome.lsp.trace.server

默认：off | 作用域：global

¥Default: off | Scopes: global

此设置允许你设置 Biome LSP 跟踪的日志级别。可能的值为 off、messages 和 verbose。当你遇到扩展程序的问题并希望与我们分享日志时，你可能需要将此设置设为 verbose。

¥This setting allows to set the logging level of the Biome LSP trace. The possible values are off, messages, verbose. You may want to set this setting to verbose when you encounter issues with the extension, and you’d like to share the logs with us.

故障排除

¥Troubleshooting

有时你可能会遇到扩展程序的意外问题。以下是一些帮助你排查常见问题并重置扩展程序状态的提示。

¥There may be times when you encounter unexpected issues with the extension. Here a a couple tip to help you troubleshoot the most common issues, and reset the extension’s state.

访问 LSP 跟踪

¥Accessing the LSP trace

如果你在使用扩展程序时遇到问题，我们可能会要求你提供 LSP 跟踪信息。你可以通过将 biome.lsp.trace.server 设置更改为 verbose，然后重新运行导致问题的操作来实现这一点。跟踪信息将在 output 面板的 Biome LSP trace (xxx) 选择选项下提供。

¥If you encounter issues with the extension, we may ask you to share the LSP trace with us. You can do so by setting the biome.lsp.trace.server setting to verbose, and re-running the action that caused the issue. The trace will be made available the output panel, under the Biome LSP trace (xxx) select option.

从 2.x 扩展迁移

¥Migrating from the 2.x extension

如果你是从 2.x 扩展迁移，我们建议你严格按照以下步骤操作：

¥If you are migrating from the 2.x extension, we recommend the following steps, in this exact order:

1. 更新扩展程序

   ¥Update the extension

2. 完全关闭编辑器。

   ¥Close the editor completely.

3. 打开任务管理器，并确保终止所有名为 biome 的进程。

   ¥Open your task manager, and make sure to kill all processes named biome.

4. 打开编辑器。

   ¥Open your editor.

这将破坏可能仍然连接到编辑器但扩展程序无法正常关闭的旧守护进程连接，从而导致文件保存时出现一些格式错误。

¥This will destroy possible old Daemon connections that are still connected to the editor, but can’t be shutdown gracefully by the extension, which caused some incorrect formatting when a file was saved.

更改

¥Changes

• biome.lspBin 设置已被弃用，请使用 biome.lsp.bin。它目前仍然可以工作，但我们建议你更新设置以使用新名称。

  ¥The biome.lspBin setting has been deprecated in favor of biome.lsp.bin. It will still work for now, but we recommend updating your settings to use the new name.

• biome.requireConfigFile 已重命名为 biome.requireConfiguration。由于旧设置已不再受支持，你现在应该迁移此设置。

  ¥The biome.requireConfigFile has been renamed to biome.requireConfiguration. You should migrate the setting now as the old is no longer supported.