eslint-plugin-import 的 enforce-node-protocol-usage 规则:统一 Node.js 内置模块的 `node:` 协议写法

原创2026-10-09 13:18:422,253 阅读
文章标签:开发工具代码质量静态分析

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):

  1. moduleName 本身是核心模块(isCoreModule(moduleName));
  2. 加上 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 配置即可,保持现状由团队约定自行管理。

延伸阅读

登录后查看全文
eslint-plugin-import