eslint-plugin-import 的 enforce-node-protocol-usage 规则:统一 Node.js 内置模块的 `node:` 协议写法
eslint-plugin-import 的 enforce-node-protocol-usage 规则:统一 Node.js 内置模块的 node: 协议写法
本篇技术指南聚焦于 eslint-plugin-import 中的 import/enforce-node-protocol-usage 规则,它用于强制统一 Node.js 内置模块(builtin modules)导入时的 node: 协议写法——要么一律使用、要么一律省略。读者阅读后将掌握该规则的配置选项、自动修复行为、与 import/node-version 设置的联动机制,以及它在源码层面如何判定核心模块并生成 fix 修复。
规则概述
import/enforce-node-protocol-usage 是 eslint-plugin-import 提供的一条静态分析规则(type: 'suggestion'),它保证项目中对 Node.js 内置模块(如 fs、path、child_process 等)的导入风格保持一致:在 always 模式下要求统一使用 node: 前缀,在 never 模式下要求统一省略 node: 前缀。
该规则支持 ESLint 的 --fix 命令行选项自动修复(规则元数据中声明了 fixable: 'code'),即运行 eslint --fix 或编辑器内的"修复所有可自动修复问题"操作时,不符合规范的导入语句会被自动改写。在 规则注册表 中,该规则以 'enforce-node-protocol-usage': require('./rules/enforce-node-protocol-usage') 的方式注册,可通过 import/enforce-node-protocol-usage 启用。
为何要统一 node: 协议写法
文档中给出了两种取向的权衡:
倾向使用 node: 协议的理由:
- 代码意图更明确,显式标注了"这是 Node.js 内置模块",与第三方包、相对路径导入形成清晰区分。
倾向省略 node: 协议的理由:
- 部分工具链尚不支持
node:协议; - 省略前缀的写法可移植性更好,因为 import maps 和自动 polyfill(automatic polyfilling)可以直接作用于不带协议的模块名。
选择哪一种并无绝对优劣,关键在于团队内保持一致,这正是本规则存在的意义。
如何判定"核心模块"
规则并非硬编码一份模块名单,而是借助 is-core-module 包来判定某个 specifier 是否属于 Node.js 核心模块(见 src/rules/enforce-node-protocol-usage.js)。这意味着内置模块的清单会跟随 is-core-module 所依据的 Node.js 版本知识库变化,新版本新增的核心模块也能被正确识别。
一个关键前提是:判定是否为核心模块,取决于运行 ESLint 的 Node.js 版本。如果需要针对特定目标版本进行判定,可以通过 ESLint 的 settings 配置项 import/node-version 显式指定,该设置在整个插件中是共享的(详见 README.md 中的说明):
// .eslintrc
{
"settings": {
"import/node-version": "22.3.4",
},
}
该设置的值是一个表示 Node.js 版本的字符串;如果该值为空或未设置,则回退到"运行 ESLint 的 Node.js 版本"。在源码实现中(src/rules/enforce-node-protocol-usage.js),规则会对该设置做严格校验:
- 若
import/node-version已定义但不是字符串,或不符合数字.数字.数字的 semver 格式(例如"10.23.45",不允许前导零),规则会直接抛出TypeError。
throw new TypeError(
'`import/node-version` setting must be a string in the format "10.23.45" (a semver version, with no leading zero)'
);
这一点在测试中也有体现:tests/src/rules/enforce-node-protocol-usage.js 使用 'import/node-version': '16.0.0' 作为 settings,并注释说明 node: 前缀自 Node ^14.18 || >= 16 起才可用。
一个值得注意的版本语义
在 always 模式下,规则会同时检查两件事(src/rules/enforce-node-protocol-usage.js):
moduleName本身是核心模块(isCoreModule(moduleName));- 加上
node:前缀后依然是核心模块(isCoreModule('node:' + moduleName))。
只有两者都成立才会报告。这意味着:如果某个模块仅在 node: 协议下存在(例如 node:test),而当前目标版本下 test 不带协议无法解析为核心模块,规则就不会强制添加前缀,避免生成"修完反而坏掉"的代码。相应地,在 never 模式下,规则同样只对"去掉 node: 后依然属于核心模块"的导入进行报告(src/rules/enforce-node-protocol-usage.js),因此 node:test 这类仅能通过协议访问的模块不会被强制去前缀——这一点在原文档的 never 示例中也有明确注释说明。
配置选项
规则要求必须传入一个且仅一个字符串选项(schema 规定 minItems: 1, maxItems: 1,且取值被 enum 限定,见 src/rules/enforce-node-protocol-usage.js):
| 选项 | 行为 |
|---|---|
'always' |
强制 Node.js 内置模块的导入必须使用 node: 协议 |
'never' |
强制 Node.js 内置模块的导入不得使用 node: 协议 |
在 src/index.js 注册后,典型配置方式如下:
// .eslintrc
{
"rules": {
"import/enforce-node-protocol-usage": ["error", "always"]
}
}
选项缺失或取值非法时,规则会抛出显式错误:未传选项抛 Missing option,传入其他字符串抛 Unexpected option: xxx(src/rules/enforce-node-protocol-usage.js)。如果不需要强制某一种写法,应直接关闭该规则(见文末"何时不使用")。
示例:'always'
在 always 模式下,不带 node: 协议的内置模块导入会被报告,并自动修复为带协议写法。
❌ Invalid
import fs from 'fs';
export { promises } from 'fs';
// require
const fs = require('fs/promises');
✅ Valid
import fs from 'node:fs';
export { promises } from 'node:fs';
import * as test from 'node:test';
// require
const fs = require('node:fs/promises');
报告的消息文案在源码中定义为 requireNodeProtocol(src/rules/enforce-node-protocol-usage.js):
Prefer `node:{{moduleName}}` over `{{moduleName}}`.
从测试用例(tests/src/rules/enforce-node-protocol-usage.js)可以看到,always 模式覆盖了 fs、fs/promises、buffer、child_process、timers/promises 等常见核心模块,并且覆盖多种导入语法:
// 测试中可自动修复的示例(修复结果对比)
import x from "fs"; // → import x from "node:fs";
export {promises} from "fs"; // → export {promises} from "node:fs";
const {promises} = require("fs"); // → const {promises} = require("node:fs");
await import('fs/promises'); // → await import('node:fs/promises');
示例:'never'
在 never 模式下,带 node: 协议的内置模块导入会被报告,并自动修复为不带协议写法。
❌ Invalid
import fs from 'node:fs';
export { promises } from 'node:fs';
// require
const fs = require('node:fs/promises');
✅ Valid
import fs from 'fs';
export { promises } from 'fs';
// require
const fs = require('fs/promises');
// 仅可通过 node: 协议访问的模块不会被强制去前缀
import * as test from 'node:test';
报告的消息文案为 forbidNodeProtocol:
Prefer `{{moduleName}}` over `node:{{moduleName}}`.
测试中 never 模式的用例直接复用了 always 的用例集并交换 code 与 output(tests/src/rules/enforce-node-protocol-usage.js),保证两种模式互为镜像、行为对称。
自动修复的底层实现
该规则不仅是"报告错误",还能通过 --fix 完成实际改写。修复的核心是一个名为 replaceStringLiteral 的辅助函数(src/rules/enforce-node-protocol-usage.js):
- 它基于 AST 节点的
range定位字符串字面量内容的首尾(跳过开闭引号),再调用 ESLint fixer 的replaceTextRange只替换引号内的模块名字符串; always模式调用replaceStringLiteral(fixer, src, 'node:', 0, 0),即在模块名前插入node:;never模式调用replaceStringLiteral(fixer, src, '', 0, 5),即删除开头的node:这 5 个字符。
因为替换范围严格限制在字符串引号内部,所以修复不会破坏注释、引号样式或其他代码结构。对应地,规则在 meta 中声明了 fixable: 'code'(src/rules/enforce-node-protocol-usage.js)。
规则监听哪些语法形态
从源码的 create 入口(src/rules/enforce-node-protocol-usage.js)可以看出,规则覆盖了四种 AST 节点:
| AST 节点 | 对应的导入形态 |
|---|---|
ImportDeclaration |
import fs from 'fs' 等 ESM 静态导入 |
ExportNamedDeclaration |
export { promises } from 'fs' 等 re-export |
CallExpression |
静态 require('fs') 调用(经 isStaticRequireWith1Param 过滤) |
ImportExpression |
动态 import('fs') 表达式(仅当参数是字符串字面量时) |
其中 isStaticRequireWith1Param(src/rules/enforce-node-protocol-usage.js)做了严格甄别:要求 callee 恰好是名为 require 的标识符、非可选调用(require?.() 不命中)、恰好 1 个参数且参数是字符串字面量。因此 require.resolve('fs')、require(fs)、require('fs', extra)、foo.require('fs')、模板字符串形式的 require(\fs`)` 等都不会被误报——这些边界情况全部有对应的 valid 测试用例(tests/src/rules/enforce-node-protocol-usage.js)。
另外,规则跳过 TemplateLiteral 形态(src/rules/enforce-node-protocol-usage.js),因此 import(\fs`)这类动态模板字符串导入不会触发检查;非核心模块、相对路径(如./fs)、第三方包(如 unicorn)以及 punycode/`(带尾斜杠的非精确内置模块路径)也不会被误报。
何时不使用该规则
如果你不希望强制统一 Node.js 内置模块的 node: 协议写法——例如项目中既有支持协议的工具链又有不支持协议的工具链、暂时无法全局统一——那么不应启用该规则。此时直接移除/关闭 import/enforce-node-protocol-usage 配置即可,保持现状由团队约定自行管理。
延伸阅读
- 规则完整源码:src/rules/enforce-node-protocol-usage.js
- 规则测试用例(含大量可自动修复的输入/输出对与边界情况):tests/src/rules/enforce-node-protocol-usage.js
- 规则注册位置:src/index.js
import/node-version全局设置说明:README.md- 使用 ESLint
--fix时,可在命令行执行eslint --fix <目标文件>自动应用本规则的所有修复。