Oxc
← Back to rules

eslint/no-restricted-imports 限制

它的作用 ​

此规则允许你指定在应用程序中不希望使用的导入。
仅适用于静态导入，不适用于动态导入。

为什么这是个问题？ ​

某些导入在特定环境中可能没有意义。
例如，Node.js 的 fs 模块在没有文件系统环境的场景中是毫无意义的。

某些模块提供相似甚至相同的功能（如 lodash 与 underscore）。你的项目可能已经标准化使用某个模块。
你希望确保其他替代方案不会被使用，因为这会不必要地增加项目体积，并导致维护两个依赖项的成本，而实际上一个就足够了。

示例 ​

以下为 错误 代码示例：

js
/* no-restricted-imports: ["error", "disallowed-import"] */

import foo from "disallowed-import";
export * from "disallowed-import";

以下为 正确 代码示例：

js
/* no-restricted-imports: ["error", "fs"] */

import crypto from "crypto";
export * from "bar";

选项 ​

你也可以通过在对象中使用 name 和 message 属性，为特定模块指定自定义消息，其中 name 是模块名称，message 属性包含自定义提示信息。
该自定义消息将以帮助文本的形式呈现给用户。

以下为 错误 代码示例：

js
/* no-restricted-imports: ["error", {
  "name": "disallowed-import",
  "message": "请改用 'allowed-import'"
}] */

import foo from "disallowed-import";

paths ​

这是一个对象选项，其值为一个数组，包含你希望限制的模块名称。

json
{"rules: {"no-restricted-imports": ["error", { "paths": ["import1", "import2"] }]}}

paths 的 错误 代码示例：

js
/* no-restricted-imports: ["error", { "paths": ["cluster"] }] */

import cluster from "cluster";

你也可以在 paths 数组中使用带有 name 和 message 属性的对象来为特定模块指定自定义消息。

json
"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
    "message": "请改用 import-bar"
  }, {
    "name": "import-baz",
    "message": "请改用 import-quux"
  }]
}]
importNames ​

paths 中的此选项是一个数组，可用于指定从某个模块导出的特定绑定名称。
在 paths 数组中指定的 importNames 会影响对应对象中的 name 属性所指定的模块，因此在使用 importNames 或 message 选项时，必须先指定 name 属性。

在 importNames 数组中指定 "default" 字符串，将限制默认导出的导入。

以下为 错误 代码示例：

js
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "importNames": ["default"]
}, {
  "name": "bar",
  "importNames": ["Baz"]
}]}] */

import DisallowedObject from "foo";
import { Baz } from "far";
allowImportNames ​

此选项是一个数组。它是 importNames 的反向操作，allowImportNames 允许在该数组中指定的导入。
因此，它会限制模块的所有导入，除了明确允许的那些。

注意：allowImportNames 不能与 importNames 同时使用。

以下为 错误 代码示例：

js
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "allowImportNames": ["AllowedObject"],
  "message": "请仅从 'foo' 导入 'AllowedObject'"
}]}] */

import { DisallowedObject } from "foo";

allowTypeImports ​

是否允许对路径进行仅类型导入。默认值：false。

以下为 错误 代码示例：

typescript
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "allowTypeImports": true
}]}] */

import foo from "import-foo";
export { Foo } from "import-foo";

以下为 正确 代码示例：

typescript
/* no-restricted-imports: ["error", { paths: [{
  "name": "foo",
  "allowTypeImports": true
}]}] */

import type foo from "import-foo";
export type { Foo } from "import-foo";

patterns ​

这也是一个对象选项，其值为一个数组。
此选项允许你使用 gitignore 风格的模式或正则表达式来指定多个要限制的模块。

当 paths 选项仅接受精确的导入路径时，patterns 选项提供了更灵活的方式来指定导入路径，允许对同一目录下的多个模块进行限制。例如：

json
"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
  }]
}]

此配置仅限制 import-foo 模块的导入，但不会限制 import-foo/bar 或 import-foo/baz 的导入。你可以使用 patterns 来同时限制这些导入：

json
"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
  }],
  "patterns": [{
    "group": ["import-foo/ba*"],
  }]
}]

此配置不仅通过路径限制了 import-foo 的导入，还通过 patterns 限制了 import-foo/bar 和 import-foo/baz 的导入。

你也可以使用正则表达式来限制模块（参见 regex 选项）。

以下为 patterns 选项的 错误 代码示例：

js
/* no-restricted-imports: ["error", { "patterns": ["lodash/*"] }] */

import pick from "lodash/pick";

以下为 patterns 选项的 正确 代码示例：

js
/* no-restricted-imports: ["error", { "patterns": ["crypto/*"] }] */

import crypto from "crypto";
group ​

patterns 数组还可以包含对象。group 属性用于指定用于限制模块的 gitignore 风格模式，message 属性用于指定自定义消息。

使用 patterns 选项时，group 或 regex 属性至少需要指定一个。

以下为 group 选项的 错误 代码示例：

js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["lodash/*"],
  message: "请改用从 'lodash' 的默认导入"
}]}] */

import pick from "lodash/pick";
regex ​

regex 属性用于指定用于限制模块的正则表达式模式。

注意：regex 不能与 group 一起使用。

警告：此规则使用 Rust-Regex，其不支持所有 JS-Regex 特性，例如前瞻和后瞻断言。

以下为 regex 选项的 错误 代码示例：

js
/* no-restricted-imports: ["error", { patterns: [{
  regex: "@app/(api|enums).*",
}]}] */

import Foo from "@app/api";
import Bar from "@app/api/bar";
import Baz from "@app/api/baz";
import Bux from "@app/api/enums/foo";
caseSensitive ​

这是一个布尔选项，当设置为 true 时，会使 group 属性中指定的模式变为大小写敏感。默认值为 false。

警告：此选项不会对 regex 生效。regex 使用 Rust-RegEx，其自身有独立的大小写敏感实现。

importNames ​

你也可以在 patterns 数组中的对象内指定 importNames。
在此情况下，指定的名称仅适用于相关的 group 或 regex 属性。

以下为 patterns 中 importNames 的 错误 代码示例：

js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["utils/*"],
  importNames: ['isEmpty'],
  message: "请改用 lodash 中的 'isEmpty'"
}]}] */

import { isEmpty } from "utils/collection-utils";
allowImportNames ​

你也可以在 patterns 数组中的对象内指定 allowImportNames。
在此情况下，指定的名称仅适用于相关的 group 或 regex 属性。

注意：allowImportNames 不能与 importNames、importNamePattern 或 allowImportNamePattern 一起使用。

importNamePattern ​

此选项允许你使用正则表达式模式来限制导入名称。

以下为 importNamePattern 选项的 错误 代码示例：

js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["foo/*"],
  importNamePattern: '^(is|has)',
  message: "请改用 'is*' 与 'has*' 函数，来自 baz/bar"
}]}] */

import { isSomething, hasSomething } from "foo/bar";
allowImportNamePattern ​

此为字符串选项。它是 importNamePattern 的反向操作，此选项允许匹配指定正则表达式的导入。
因此，它会限制模块的所有导入，除了明确允许的模式。

注意：allowImportNamePattern 不能与 importNames、importNamePattern 或 allowImportNames 一起使用。

json
"no-restricted-imports": ["error", {
  "patterns": [{
    "group": ["import-foo/*"],
    "allowImportNamePattern": "^foo",
  }]
}]

以下为 allowImportNamePattern 选项的 错误 代码示例：

js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["utils/*"],
  allowImportNamePattern: '^has'
}]}] */

import { isEmpty } from "utils/collection-utils";

以下为 allowImportNamePattern 选项的 正确 代码示例：

js
/* no-restricted-imports: ["error", { patterns: [{
  group: ["utils/*"],
  allowImportNamePattern: '^is'
}]}] */

import { isEmpty } from "utils/collection-utils";

如何使用 ​

要通过配置文件或 CLI 启用 此规则，可以使用：

json
{
  "rules": {
    "no-restricted-imports": "error"
  }
}
bash
oxlint --deny no-restricted-imports

参考资料 ​

© 2026 VoidZero Inc. 及 Oxc 贡献者。