企业官网建设流程全解析

• 开发工具
• 代码质量
• 静态分析

本文围绕 eslint-plugin-import 提供的import/no-absolute-path规则展开，介绍它为什么存在、会拦截哪些写法、如何通过esmodule/commonjs/amd三个选项精确控制检查范围，并深入源码（src/rules/no-absolute-path.js、src/core/importType.js、utils/moduleVisitor.js）说明判定与自动修复的底层原理。读完本文，你可以独立完成该规则的配置、理解其 fix 行为，并借助仓库测试用例验证自己的理解。

一、规则背景：绝对路径导入为什么是坏味道

Node.js 本身允许用绝对路径导入模块，例如：

require('/home/xyz/file.js');

这种写法把代码与某台具体的电脑绑定在一起：只要换一台机器、换一个部署目录，这段代码就会立刻失效。对于要发布到npm的包而言，消费者在完全不同的目录结构下安装使用，绝对路径导入几乎必然导致运行时崩溃。

import/no-absolute-path规则的职责就是禁止使用绝对路径导入模块。它在仓库中的注册位置是 src/index.js，元信息中标记为type: 'suggestion'、fixable: 'code'，因此它既是一类"静态分析建议"，又是一条可以自动修复的规则——配合 ESLint 的--fix命令行选项即可一键改写。

二、规则行为：Fail 与 Pass 对照

该规则的核心判定很简单：只要模块说明符（module specifier）是一个以/开头的绝对路径，就会报告错误。原文档给出了完整的正反例：

Fail（会被报告）

import f from '/foo'; import f from '/some/path'; var f = require('/foo'); var f = require('/some/path');

以上 4 种写法分别覆盖了 ES6import和 CommonJSrequire两种模块系统，都属于绝对路径导入。

Pass（不会被报告）

import _ from 'lodash'; import foo from 'foo'; import foo from './foo'; var _ = require('lodash'); var foo = require('foo'); var foo = require('./foo');

注意这里的语义边界：

• 裸模块名（lodash、foo）走的是node_modules解析，合法；
• 相对路径（./foo）依赖当前文件位置，合法；
• Node 内置模块（events、path等）同样不受影响。

仓库测试 tests/src/rules/no-absolute-path.js 的 valid 用例中还额外验证了../foo、./、@scope/foo（scoped 包）、内置模块events/path等写法均不会被报告。

三、Options 配置详解：esmodule / commonjs / amd

该规则的检查范围由三个布尔选项控制，默认值如下：

也就是说，默认情况下规则只对 ES6 import 和 CommonJS require 生效，AMD 依赖路径默认不检查。

启用 AMD 检查后，define与require的依赖数组中的绝对路径同样会被报告：

/*eslint import/no-absolute-path: [2, { commonjs: false, amd: true }]*/ define(['/foo'], function (foo) { /*...*/ }) // reported require(['/foo'], function (foo) { /*...*/ }) // reported const foo = require('/foo') // ignored because of explicit `commonjs: false`

这里三种模块系统可以任意组合，例如{ commonjs: false, amd: true }意味着只检查 AMD，CommonJS 写法被显式豁免。

配置写法示例

传统.eslintrc风格（2表示error级别，也可写作字符串'error'）：

{ "rules": { "import/no-absolute-path": ["error", { "commonjs": false, "amd": true }] } }

Flat config（eslint.config.js/.mjs）风格，可参考仓库中的 examples/flat/eslint.config.mjs：

import importPlugin from 'eslint-plugin-import'; export default [ { plugins: { import: importPlugin }, rules: { 'import/no-absolute-path': ['error', { amd: true }], }, }, ];

需要特别说明的是：该规则默认不在推荐配置中。查看 config/recommended.js 可以发现，import/no-absolute-path并未被列入import:recommended预设，因此如果你想启用它，必须在自己的配置里显式声明，而不是依赖extends: ['plugin:import/recommended']。

另外，从 utils/moduleVisitor.js 中的makeOptionsSchema可以看出，选项对象还额外支持一个ignore数组（字符串正则列表），命中正则的模块路径会被跳过不检查，可用于对个别路径做豁免。

四、自动修复：--fix 的行为与边界

规则声明了fixable: 'code'，因此可以直接运行：

eslint --fix src/**/*.js

修复逻辑位于 src/rules/no-absolute-path.js：

fix(fixer) { // node.js and web imports work with posix style paths ("/") let relativePath = path.posix.relative(path.dirname(getPhysicalFilename(context)), source.value); if (!relativePath.startsWith('.')) { relativePath = `./${relativePath}`; } return fixer.replaceText(source, JSON.stringify(relativePath)); }

其原理是：

1. 通过getPhysicalFilename(context)（实现在 utils/contextCompat.js，兼容新旧 ESLint 上下文 API）拿到当前被检查文件的真实磁盘路径；
2. 取该文件所在目录（path.dirname），再调用 Node 的path.posix.relative计算出从该目录到目标绝对路径的相对路径；
3. 如果结果不以.开头（例如计算出的是..之外的裸名称），自动补上./前缀；
4. 用JSON.stringify序列化后替换原模块说明符。

测试用例 tests/src/rules/no-absolute-path.js 的 invalid 部分给出了非常直观的修复结果，假设被检查文件位于/foo/bar/index.js：

可见修复逻辑遵循 POSIX 路径语义（统一使用/分隔），在跨平台场景下也能产出稳定的相对路径，这正是注释中"node.js and web imports work with posix style paths"的含义。

五、源码级原理：判定入口与访问者机制

判定入口：isAbsolute

规则对每个模块说明符的判定委托给了 src/core/importType.js 导出的isAbsolute：

export function isAbsolute(name) { return typeof name === 'string' && nodeIsAbsolute(name); }

这里直接复用了 Node 内置path.isAbsolute：先确保是字符串，再判断是否为绝对路径。importType.js是 eslint-plugin-import 的"导入类型分类器"，isAbsolute也是其中absolute类型的判定依据（见typeTest函数），其他规则如import/no-internal-modules等也共享同一套分类逻辑。

访问者机制：moduleVisitor

规则的create函数在 src/rules/no-absolute-path.js 中做了选项合并后，把reportIfAbsolute交给通用的moduleVisitor：

const options = { esmodule: true, commonjs: true, ...context.options[0] }; return moduleVisitor(reportIfAbsolute, options);

moduleVisitor（utils/moduleVisitor.js）是 eslint-plugin-import 的公共模块遍历器，它根据选项注册不同的 AST 访问器：

• esmodule为真时：访问ImportDeclaration、ExportNamedDeclaration、ExportAllDeclaration，以及动态import()表达式（ImportExpression或CallExpression中 callee 为Import的节点）；
• commonjs为真时：访问单参数require(...)调用，且同时支持字符串字面量与不含插值的单段模板字符串；
• amd为真时：访问require([...], cb)与define([...], ...)，逐个检查依赖数组中的字符串元素，并跳过require、exports这两个 AMD 魔法模块。

因此，虽然原文档的 Fail 示例只列了静态import和require两种形式，但从源码看，启用esmodule后动态import('/foo')同样会进入判定流程。每个被发现的模块路径最终都会回调reportIfAbsolute，命中绝对路径即以固定消息'Do not import modules using an absolute path'上报。

六、测试印证与最佳实践小结

仓库测试 tests/src/rules/no-absolute-path.js 用RuleTester完整覆盖了三类模块系统：

• valid 用例：裸包名、相对路径、scoped 包、内置模块、amd: true下相对路径依赖数组等均不报错；未开启amd时require([...])/define([...])默认不检查；
• invalid 用例：ES6 import、CommonJS require、AMD 依赖数组中的绝对路径均报错，并逐一断言了--fix的修复输出。

最后给出三条实用建议：

1. 默认开启即可：{ "import/no-absolute-path": "error" }覆盖绝大多数场景，防止代码库混入机器相关的硬编码路径；
2. 按模块系统裁剪范围：老项目若保留 AMD 加载器但希望清理 ES6/CommonJS 路径，可用{ commonjs: false, amd: true }这类组合逐步治理；
3. 善用 --fix：规则自带确定性修复，先跑一遍eslint --fix批量改写，再人工审查修复后的相对路径是否符合项目目录规划。

• 开发工具
• 代码质量
• 静态分析