导入排序

Biome 允许使用自然排序对导入语句进行排序。

¥Biome allows sorting import statements using natural ordering.

此功能默认启用，但可以通过配置选择退出：

¥This feature is enabled by default but can be opted-out via configuration:

{
  "organizeImports": {
    "enabled": false
  }
}

导入如何排序

¥How imports are sorted

导入语句按 “distance” 排序。来自用户的 “farther” 模块放在顶部，给用户的模块 “closer” 放在底部：

¥Import statements are sorted by “distance”. Modules that are “farther” from the user are put on the top, modules “closer” to the user are put on the bottom:

通过 bun: 协议导入的模块。这适用于编写由 Bun 运行的代码时；

¥modules imported via bun: protocol. This is applicable when writing code run by Bun;
使用 node: 协议和常见 Node 内置函数（如 assert）明确导入的内置 Node.js 模块；

¥built-in Node.js modules that are explicitly imported using the node: protocol and common Node built-ins such as assert;
通过 npm: 协议导入的模块。这适用于编写由 Deno 运行的代码时；

¥modules imported via npm: protocol. This is applicable when writing code run by Deno;
包含协议 : 的模块。这些通常被视为 “虚拟模块”，由你的工作环境注入的模块，例如 vite；

¥modules that contain the protocol :. These are usually considered “virtual modules”, modules that are injected by your working environment, e.g. vite;
通过 URL 导入的模块；

¥modules imported via URL;
从库导入的模块；

¥modules imported from libraries;
通过绝对导入导入的模块；

¥modules imported via absolute imports;
从以 # 为前缀的名称导入的模块。这适用于使用 Node 的子路径导入时；

¥modules imported from a name prefixed by #. This is applicable when using Node’s subpath imports;
通过相对导入导入的模块；

¥modules imported via relative imports;
无法通过先前标准识别的模块；

¥modules that couldn’t be identified by the previous criteria;

例如，给定以下代码：

¥For example, given the following code:

import uncle from "../uncle";
import sibling from "./sibling";
import express from "npm:express";
import imageUrl from "url:./image.png";
import { sortBy } from "virtual:utils";
import assert from "node:assert";
import aunt from "../aunt";
import { VERSION } from "https://deno.land/std/version.ts";
import { mock, test } from "node:test";
import { expect } from "bun:test";
import { internal } from "#internal";
import { secret } from "/absolute/path";
import React from "react";

它们将按以下方式排序：

¥They will be sorted like this:

 import { expect } from "bun:test";
 import assert from "node:assert";
 import { mock, test } from "node:test";
 import express from "npm:express";
 import { sortBy } from "virtual:utils";
 import { VERSION } from "https://deno.land/std/version.ts";
 import React from "react";
 import { secret } from "/absolute/path";
 import { internal } from "#internal";
 import aunt from "../aunt";
 import uncle from "../uncle";
 import sibling from "./sibling";
 import imageUrl from "url:./image.png";

你可以通过两种方式应用排序：通过 CLI 或 VSCode 扩展。

¥You can apply the sorting in two ways: via CLI or VSCode extension.

分组导入

¥Grouped imports

以特定顺序使用导入语句是很普遍的，主要是当你在前端项目上工作并导入 CSS 文件时：

¥It’s widespread to have import statements in a certain order, primarily when you work on a frontend project, and you import CSS files:

import "../styles/reset.css";
import "../styles/layout.css";
import { Grid } from "../components/Grid.jsx";

另一种常见情况是导入 polyfill 或 shim 文件，需要保留在顶部文件：

¥Another common case is import polyfills or shim files, that needs to stay at the top file:

import "../polyfills/array/flatMap";
import { functionThatUsesFlatMap } from "./utils.js";

在这些情况下，Biome 将对所有这三个导入进行排序，并且该顺序可能会破坏你的应用。

¥In these cases, Biome will sort all these three imports, and it might happen that the order will break your application.

为了避免这种情况，请创建导入的 “group”。你可以通过添加新行来分隔组来创建 “group”。

¥To avoid this, create a “group” of imports. You create a “group” by adding a new line to separate the groups.

默认情况下，此规则检查以下元素的替代文本：

¥By doing so, Biome will limit the sorting only to the import statements that belong to the same group:

// group 1, only these two files will be sorted
import "../styles/reset.css";
import "../styles/layout.css";

// group 2, only this one is sorted
import { Grid } from "../components/Grid.jsx";

// group 1, the polyfill/shim
import "../polyfills/array/flatMap";

// group 2, the files that require the polyfill/shim
import { functionThatUsesFlatMap } from "./utils.js";

副作用导入

¥Side effect imports

副作用导入是通常不导入任何名称的导入语句：

¥Side effect imports are import statements that usually don’t import any name:

import "./global.js"

由于很难确定模块会触发哪些副作用，导入排序器假定每个副作用导入都形成自己的导入组。

¥Since it is difficult to determine which side effects a module triggers, the import sorter assumes that each side effect import forms its own import group.

例如，以下导入形成 4 个导入组。

¥For example, the following imports form 4 import groups.

import sibling from "./sibling";       // Import group 1
import { internal } from "#internal";  // Import group 1
import "z";  // Import group 2
import "a";  // Import group 3
import React from "react";         // Import group 4
import assert from "node:assert";  // Import group 4

每个组都按以下方式独立排序：

¥Each group is independently sorted as follows:

import { internal } from "#internal";  // Import group 1
import sibling from "./sibling";      // Import group 1
import "z";  // Import group 2
import "a";  // Import group 3
import assert from "node:assert";  // Import group 4
import React from "react";         // Import group 4

通过 CLI 导入排序

¥Import sorting via CLI

使用命令 check，带选项 --write。

¥Using the command check, with the option --write.

biome check --write ./path/to/src

通过 VSCode 扩展导入排序

¥Import sorting via VSCode extension

Biome VS Code 扩展支持通过 “组织导入” 代码操作进行导入排序。默认情况下，规则要求文件名为 ⇧、Alt、O 或与文件中 Ctrl 的名称匹配。

¥The Biome VS Code extension supports imports sorting through the “Organize Imports” code action. By default, this action can be run using the ⇧+Alt+O keyboard shortcut, or is accessible through the Command Palette (Ctrl/⌘+⇧+P) by selecting Organize Imports.

如果你希望操作在保存时自动运行而不是手动调用，则可以将以下内容添加到编辑器配置中：

¥You can add the following to your editor configuration if you want the action to run automatically on save instead of calling it manually:

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