no-restricted-imports

当通过 import 加载时，禁用指定的模块

Imports 是 ES6/ES2015 标准，用于使其他模块的功能在当前模块中可用。在 CommonJS 中，这是通过 require() 调用实现的，这使得此 ESLint 规则大致等同于其 CommonJS 对应规则 no-restricted-modules。

为什么您要限制导入？

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

• 某些模块提供相似或相同的功能，例如 lodash 和 underscore。您的项目可能已标准化一个模块。您想确保不使用其他替代方案，因为这将不必要地膨胀项目，并在一个依赖项就足够的情况下提供两个依赖项的更高维护成本。

规则详情

此规则允许您指定您不想在应用程序中使用的导入。

它仅适用于静态导入，不适用于动态导入。

选项

此规则同时具有字符串和对象选项，用于指定要限制的导入模块。

使用字符串选项，您可以指定要限制导入的模块名称作为规则选项数组中的值

"no-restricted-imports": ["error", "import1", "import2"]
1

字符串选项的错误代码示例

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

import fs from 'fs';
1
2
3

字符串选项也限制模块被导出，如本例所示

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

export { fs } from 'fs';
1
2
3

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

export * from 'fs';
1
2
3

字符串选项的正确代码示例

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

import crypto from 'crypto';
export { foo } from "bar";
1
2
3
4

您还可以使用对象中的 name 和 message 属性为特定模块指定自定义消息，其中 name 的值是模块的名称，message 属性包含自定义消息。（自定义消息将附加到规则的默认错误消息之后。）

"no-restricted-imports": ["error", {
    "name": "import-foo",
    "message": "Please use import-bar instead."
}, {
    "name": "import-baz",
    "message": "Please use import-quux instead."
}]
1
2
3
4
5
6
7

字符串选项的错误代码示例

/*eslint no-restricted-imports: ["error", {
    "name": "disallowed-import",
    "message": "Please use 'allowed-import' instead"
}]*/

import foo from 'disallowed-import';
1
2
3
4
5
6

paths

这是一个对象选项，其值是一个数组，其中包含您要限制的模块的名称。

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

paths 的错误代码示例

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

import cluster from 'cluster';
1
2
3

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

"no-restricted-imports": ["error", {
    "paths": [{
        "name": "import-foo",
        "message": "Please use import-bar instead."
    }, {
        "name": "import-baz",
        "message": "Please use import-quux instead."
    }]
}]
1
2
3
4
5
6
7
8
9

importNames

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

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

"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
    "importNames": ["Bar"],
    "message": "Please use Bar from /import-bar/baz/ instead."
  }]
}]
1
2
3
4
5
6
7

当 paths 中的 importNames 具有 "default" 时的错误代码示例

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["default"],
    message: "Please use the default import from '/bar/baz/' instead."
}]}]*/

import DisallowedObject from "foo";
1
2
3
4
5
6
7

paths 中 importNames 的错误代码示例

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["DisallowedObject"],
    message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
}]}]*/

import { DisallowedObject } from "foo";

import { DisallowedObject as AllowedObject } from "foo";

import { "DisallowedObject" as SomeObject } from "foo";
1
2
3
4
5
6
7
8
9
10
11

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["DisallowedObject"],
    message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
}]}]*/

import * as Foo from "foo";
1
2
3
4
5
6
7

paths 中 importNames 的正确代码示例

如果分配给默认导出的本地名称与 importNames 中的字符串相同，则不会导致错误。

/*eslint no-restricted-imports: ["error", { paths: [{ name: "foo", importNames: ["DisallowedObject"] }] }]*/

import DisallowedObject from "foo"
1
2
3

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    importNames: ["DisallowedObject"],
    message: "Please import 'DisallowedObject' from '/bar/baz/' instead."
}]}]*/

import { AllowedObject as DisallowedObject } from "foo";
1
2
3
4
5
6
7

allowImportNames

此选项是一个数组。allowImportNames 是 importNames 的反向，它允许在此数组中指定的导入。因此，它限制从模块导入所有内容，但指定的允许项除外。

注意：allowImportNames 不能与 importNames 组合使用。

"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
    "allowImportNames": ["Bar"],
    "message": "Please use only Bar from import-foo."
  }]
}]
1
2
3
4
5
6
7

paths 中 allowImportNames 的错误代码示例

不允许除 ‘AllowedObject’ 之外的所有导入名称。

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    allowImportNames: ["AllowedObject"],
    message: "Please use only 'AllowedObject' from 'foo'."
}]}]*/

import { DisallowedObject } from "foo";
1
2
3
4
5
6
7

paths 中 allowImportNames 的正确代码示例

不允许除 ‘AllowedObject’ 之外的所有导入名称。

/*eslint no-restricted-imports: ["error", { paths: [{
    name: "foo",
    allowImportNames: ["AllowedObject"],
    message: "Only use 'AllowedObject' from 'foo'."
}]}]*/

import { AllowedObject } from "foo";
1
2
3
4
5
6
7

patterns

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

paths 选项采用确切的导入路径，而 patterns 选项可用于更灵活地指定导入路径，从而允许限制同一目录中的多个模块。例如

"no-restricted-imports": ["error", {
  "paths": [{
    "name": "import-foo",
  }]
}]
1
2
3
4
5

此配置限制导入 import-foo 模块，但不限制导入 import-foo/bar 或 import-foo/baz。您可以使用 patterns 来限制两者

"no-restricted-imports": ["error", {
    "paths": [{
      "name": "import-foo",
    }],
    "patterns": [{
      "group": ["import-foo/ba*"],
    }]
}]
1
2
3
4
5
6
7
8

此配置不仅使用 path 限制从 import-foo 导入，还使用 patterns 限制从 import-foo/bar 和 import-foo/baz 导入。

要在使用 gitignore- 样式模式时重新包含模块，请在模式前添加否定 (!) 标记。（确保这些否定模式放在数组的最后，因为顺序很重要）

"no-restricted-imports": ["error", {
    "patterns": ["import1/private/*", "import2/*", "!import2/good"]
}]
1
2
3

您还可以使用正则表达式来限制模块（请参阅 regex 选项）。

patterns 选项的错误代码示例

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

import pick from 'lodash/pick';
1
2
3

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

import pick from 'lodash/map';
1
2
3

/*eslint no-restricted-imports: ["error", { "patterns": ["import1/*", "!import1/private/*"] }]*/

import pick from 'import1/private/someModule';
1
2
3

在此示例中，"!import1/private/*" 不会重新包含 private 内的模块，因为如果否定标记 (!) 的父目录被模式排除，则它不会重新包含文件。在本例中，import1/private 目录已被 import1/* 模式排除。（可以使用 "!import1/private" 重新包含排除的目录。）

patterns 选项的正确代码示例

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

import crypto from 'crypto';
1
2
3

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

import pick from 'lodash/pick';
1
2
3

/*eslint no-restricted-imports: ["error", { "patterns": ["import1/*", "!import1/private"] }]*/

import pick from 'import1/private/someModule';
1
2
3

group

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

当使用 patterns 选项时，group 或 regex 属性之一是必需的。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import1/private/*"],
      "message": "usage of import1 private modules not allowed."
    }, {
      "group": ["import2/*", "!import2/good"],
      "message": "import2 is deprecated, except the modules in import2/good."
    }]
}]
1
2
3
4
5
6
7
8
9

group 选项的错误代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["lodash/*"],
    message: "Please use the default import from 'lodash' instead."
}]}]*/

import pick from 'lodash/pick';
1
2
3
4
5
6

此 group 选项的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["lodash/*"],
    message: "Please use the default import from 'lodash' instead."
}]}]*/

import lodash from 'lodash';
1
2
3
4
5
6

regex

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

注意：regex 不能与 group 组合使用。

"no-restricted-imports": ["error", {
    "patterns": [{
      "regex": "import1/private/",
      "message": "usage of import1 private modules not allowed."
    }, {
      "regex": "import2/(?!good)",
      "message": "import2 is deprecated, except the modules in import2/good."
    }]
}]
1
2
3
4
5
6
7
8
9

regex 选项的错误代码示例

/*eslint 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';
1
2
3
4
5
6
7
8

regex 选项的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    regex: "@app/(?!(api/enums$)).*",
}]}]*/

import Foo from '@app/api/enums';
1
2
3
4
5

caseSensitive

这是一个布尔选项，当为 true 时，将 group 或 regex 属性中指定的模式设置为区分大小写。默认为 false。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import1/private/prefix[A-Z]*"],
      "caseSensitive": true
    }]
}]
1
2
3
4
5
6

caseSensitive: true 选项的错误代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo[A-Z]*"],
    caseSensitive: true
}]}]*/

import pick from 'fooBar';
1
2
3
4
5
6

caseSensitive: true 选项的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo[A-Z]*"],
    caseSensitive: true
}]}]*/

import pick from 'food';
1
2
3
4
5
6

importNames

您还可以在 patterns 数组内的对象中指定 importNames。在这种情况下，指定的名称仅适用于关联的 group 或 regex 属性。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["utils/*"],
      "importNames": ["isEmpty"],
      "message": "Use 'isEmpty' from lodash instead."
    }]
}]
1
2
3
4
5
6
7

patterns 中 importNames 的错误代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNames: ['isEmpty'],
    message: "Use 'isEmpty' from lodash instead."
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6
7

patterns 中 importNames 的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNames: ['isEmpty'],
    message: "Use 'isEmpty' from lodash instead."
}]}]*/

import { hasValues } from 'utils/collection-utils';
1
2
3
4
5
6
7

allowImportNames

您还可以在 patterns 数组内的对象中指定 allowImportNames。在这种情况下，指定的名称仅适用于关联的 group 或 regex 属性。

注意：allowImportNames 不能与 importNames、importNamePattern 或 allowImportNamePattern 组合使用。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["utils/*"],
      "allowImportNames": ["isEmpty"],
      "message": "Please use only 'isEmpty' from utils."
    }]
}]
1
2
3
4
5
6
7

patterns 中 allowImportNames 的错误代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    allowImportNames: ['isEmpty'],
    message: "Please use only 'isEmpty' from utils."
}]}]*/

import { hasValues } from 'utils/collection-utils';
1
2
3
4
5
6
7

patterns 中 allowImportNames 的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    allowImportNames: ['isEmpty'],
    message: "Please use only 'isEmpty' from utils."
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6
7

importNamePattern

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

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import-foo/*"],
      "importNamePattern": "^foo",
    }]
}]
1
2
3
4
5
6

importNamePattern 选项的错误代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: '^is',
    message: "Use 'is*' functions from lodash instead."
}]}]*/

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6
7

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo/*"],
    importNamePattern: '^(is|has)',
    message: "Use 'is*' and 'has*' functions from baz/bar instead"
}]}]*/

import { isSomething, hasSomething } from 'foo/bar';
1
2
3
4
5
6
7

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["foo/*"],
    importNames: ["bar"],
    importNamePattern: '^baz',
}]}]*/

import { bar, bazQux } from 'foo/quux';
1
2
3
4
5
6
7

importNamePattern 选项的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: '^is',
    message: "Use 'is*' functions from lodash instead."
}]}]*/

import isEmpty, { hasValue } from 'utils/collection-utils';
1
2
3
4
5
6
7

您还可以通过将其设置为与任何名称匹配的模式（例如 ^）来使用此选项仅允许副作用导入。

importNamePattern 选项的错误代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: "^"
}]}]*/

import isEmpty, { hasValue } from 'utils/collection-utils';

import * as file from 'utils/file-utils';
1
2
3
4
5
6
7
8

importNamePattern 选项的正确代码示例

/*eslint no-restricted-imports: ["error", { patterns: [{
    group: ["utils/*"],
    importNamePattern: "^"
}]}]*/

import 'utils/init-utils';
1
2
3
4
5
6

allowImportNamePattern

这是一个字符串选项。allowImportNamePattern 是 importNamePattern 的反向，此选项允许与指定的正则表达式模式匹配的导入。因此，它限制从模块导入所有内容，但指定的允许模式除外。

注意：allowImportNamePattern 不能与 importNames、importNamePattern 或 allowImportNames 组合使用。

"no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["import-foo/*"],
      "allowImportNamePattern": "^foo",
    }]
}]
1
2
3
4
5
6

allowImportNamePattern 选项的错误代码示例

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

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6

allowImportNamePattern 选项的正确代码示例

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

import { isEmpty } from 'utils/collection-utils';
1
2
3
4
5
6

何时不使用它

如果您希望能够在项目中导入模块而没有 ESLint 错误或警告，请不要使用此规则，或者不要在此规则的列表中包含模块。

版本

此规则在 ESLint v2.0.0-alpha-1 中引入。

资源

• 规则来源
• 测试来源