---
url: /docs/guide/usage/linter/rules/import/extensions.md
---

### 作用

某些文件解析算法允许你在 import 源路径中省略文件扩展名。
例如，node 解析器（目前尚不支持 ESM/import）可以将 ./foo/bar 解析为绝对路径 /User/someone/foo/bar.js，因为在 CJS 中默认会自动解析 .js 扩展名。
根据解析器的不同，你还可以配置更多扩展名以自动解析。
为了在你的代码库中统一文件扩展名的使用，这条规则可以强制要求或禁止使用某些文件扩展名。

### 这有什么问题？

基于 ESM 的文件解析算法（例如 Vite 提供的那种）建议
明确指定文件扩展名以提升性能。没有扩展名时，
打包器必须检查多种可能的文件扩展名，这会拖慢
大型项目的构建过程。此外，常见的 ESM 环境
（例如浏览器和 Node.js）通常要求完整指定的相对导入，
这意味着那里不支持无扩展名导入。

出于个人偏好和兼容性原因，这条规则也允许配置为在 import 中
*禁止* 使用扩展名。这通常不推荐，但如果偏好如此，也可以这样做。

### 示例

以下是此规则的**错误**代码示例：

当配置设为 "always" 时，以下模式被视为问题：

```js
import foo from "./foo";
import bar from "./bar";
import Component from "./Component";
import foo from "@/foo";
```

当配置设为 "never" 时，以下模式被视为问题：

```js
import foo from "./foo.js";
import bar from "./bar.json";
import Component from "./Component.jsx";
import express from "express/index.js";
```

以下是此规则的**正确**代码示例：

当配置设为 "always" 时，以下模式不被视为问题：

```js
import foo from "./foo.js";
import bar from "./bar.json";
import Component from "./Component.jsx";
import * as path from "path";
import foo from "@/foo.js";
```

当配置设为 "never" 时，以下模式不被视为问题：

```js
import foo from "./foo";
import bar from "./bar";
import Component from "./Component";
import express from "express/index";
import * as path from "path";
```

**按扩展名配置示例**：

```js
// 配置：{ "vue": "always", "ts": "never" }
import Component from "./Component.vue"; // ✓ OK - .vue 配置为 "always"
import utils from "./utils"; // ✓ OK - .ts 配置为 "never"
import styles from "./styles.css"; // ✓ OK - .css 未配置，已忽略

// 配置：["ignorePackages", { "js": "never", "ts": "never" }]
import foo from "./foo"; // ✓ OK - 无扩展名
import bar from "lodash/fp"; // ✓ OK - 包导入，已忽略（ignorePackages 将其设为 true）
```

### 与 `eslint-plugin-import` 的差异

如果你发现此规则实现与原始 `eslint-plugin-import`
规则之间存在差异，请注意，这两者在行为上有一些刻意且固有的差异。

Oxlint 能开箱即用地理解并解析 TypeScript 路径。如果你的 ESLint
配置未包含 `eslint-import-resolver-typescript` 或类似工具，那么原始
规则将无法正确解析 TypeScript 路径，因此 ESLint 与 Oxlint 之间的行为可能不同。一般来说，这意味着 Oxlint 会捕获比原始规则
更多的有效违规，尽管这取决于具体配置。

Oxlint 还能够在单个仓库中解析多个 `tsconfig.json` 文件，因此在
monorepo 场景下，它在解析文件路径方面会更强大。

## 配置

### \[0]

type: `"always" | "never" | "ignorePackages"`

扩展名规则配置；复制以避免额外的间接引用。

### \[1]

type: `object`

#### \[1].checkTypeImports

type: `boolean`

default: `false`

在强制执行扩展名规则时是否检查类型导入。

#### \[1].ignorePackages

type: `boolean`

default: `false`

在强制执行扩展名规则时是否忽略包导入。

#### \[1].pathGroupOverrides

type: `array`

针对自定义 import 指定符的路径组覆盖。

##### \[1].pathGroupOverrides\[n]

type: `object`

###### \[1].pathGroupOverrides\[n].action

type: `"enforce" | "ignore"`

匹配模式时采取的操作。

针对路径组覆盖要采取的操作。

决定如何对匹配的自定义 import 标识符验证 import 扩展名。

###### `"enforce"`

对匹配的导入强制执行扩展名校验（根据配置要求扩展名）。

###### `"ignore"`

完全忽略匹配的导入（跳过所有扩展名校验）。

###### \[1].pathGroupOverrides\[n].pattern

type: `string`

用于匹配 import 标识符的 Glob 模式。

#### \[1].pattern

type: `Record<string, string>`

每个扩展名的规则。

## 如何使用

## 版本

此规则于 v1.2.0 中新增。

## 参考