Mocha测试中使用Subpath imports时出现模块找不到错误

背景 #

• 项目中安装了swagger-client，其依赖@swagger-api/apidom-reference使用了Node.js的Subpath imports特性，相关配置如下：

{
  ...,
  "imports": {
    "#buffer": {
      "node": {
        "import": "./es/util/polyfills/buffer/protocol-import.js",
        "require": "./cjs/util/polyfills/buffer/standard-import.cjs"
      },
      "default": "./cjs/util/polyfills/buffer/standard-import.cjs"
    },
  },
 ...
}

• Node.js版本为16.0.0（原生支持Subpath imports）
• 项目正常运行时swagger-client可正常使用，但在Mocha测试套件中导入该依赖时出现模块找不到的错误

错误信息 #

Error: Cannot find module '/Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/node_modules/@swagger-api/apidom-reference/cjs/parse/parsers/binary/#buffer'
Require stack:
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/node_modules/@swagger-api/apidom-reference/cjs/parse/parsers/binary/index-node.cjs
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/node_modules/swagger-client/lib/resolver/strategies/openapi-3-1-apidom/resolve.js
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/node_modules/swagger-client/lib/resolver/strategies/openapi-3-1-apidom/index.js
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/node_modules/swagger-client/lib/index.js
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/node_modules/swagger-client/lib/commonjs.js
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/srcfiles/swaggers/OpenAPI.js
- /Users/dchicchon/Projects/myproject/master/mainProject/node_modules/@projectApp/submodule/test/unit/srcfiles/swaggers/OpenAPITest.js

临时修复方式 #

手动修改@swagger-api/apidom-reference中的目标文件，将require("#buffer")替换为require("buffer")或直接注释该行代码。

原因 #

Node.js的Subpath imports依赖模块自身package.json中的imports字段进行路径映射，但Mocha在处理嵌套依赖（尤其是子模块内的依赖）时，未能正确识别@swagger-api/apidom-reference的imports配置，错误地将#buffer当作相对路径去查找，而非解析为预设的映射路径。

方法1：自定义模块解析钩子 #

创建一个mocha-resolver.js脚本，覆盖Node.js的模块解析逻辑：

const Module = require('module');
const originalResolve = Module._resolveFilename;
const path = require('path');

Module._resolveFilename = function (request, parent) {
  // 仅处理@swagger-api/apidom-reference中的#buffer导入
  if (request === '#buffer' && parent.filename.includes('@swagger-api/apidom-reference')) {
    // 找到该依赖的package.json路径
    const pkgDir = path.dirname(require.resolve('@swagger-api/apidom-reference/package.json'));
    const pkg = require(path.join(pkgDir, 'package.json'));
    // 获取对应环境的映射路径
    const target = pkg.imports['#buffer'].node.require || pkg.imports['#buffer'].default;
    // 解析为绝对路径后交给原解析函数
    return originalResolve(path.join(pkgDir, target), parent);
  }
  return originalResolve(request, parent);
};

运行Mocha时加载该脚本：

mocha --require ./mocha-resolver.js test/**/*.js

方法2：用patch-package永久修复依赖 #

1. 安装依赖：

npm install patch-package --save-dev

2. 手动修改@swagger-api/apidom-reference中出错的文件（替换require("#buffer")为require("buffer")）
3. 生成补丁文件：

npx patch-package @swagger-api/apidom-reference

4. 在package.json的scripts中添加自动应用补丁的命令：

"scripts": {
  "postinstall": "patch-package"
}

后续每次执行npm install时，补丁会自动应用，无需重复手动修改。

方法3：升级Mocha版本 #

部分旧版Mocha对ES模块和Subpath imports的支持存在缺陷，尝试升级到最新稳定版：

npm install mocha@latest --save-dev

内容的提问来源于stack exchange，提问作者pythonNovice