Node 16应用无法解析本地ESM模块依赖问题求助

我在将本地ESM包prismic-utils导入Node 16应用时，遭遇依赖解析失败，报错如下：

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@prismicio/client' imported from /Users/***/Workspace/wisdom-store/lib/prismic-utils/index.mjs
    at packageResolve (internal/modules/esm/resolve.js:664:9)
    at moduleResolve (internal/modules/esm/resolve.js:705:18)
    at Loader.defaultResolve [as _resolve] (internal/modules/esm/resolve.js:819:11)
    at Loader.resolve (internal/modules/esm/loader.js:89:40)
    at Loader.getModuleJob (internal/modules/esm/loader.js:242:28)
    at ModuleWrap.<anonymous> (internal/modules/esm/module_job.js:73:40)
    at link (internal/modules/esm/module_job.js:72:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}

消费应用通过file:路径在devDependencies中声明该本地包：

{
  "name": "node-application",
  "devDependencies" : {
      "prismic-utils": "file:../lib/prismic-utils"
  }
}

本地包prismic-utils的package.json已正确声明依赖：

{   
  "name": "prismic-utils",   
  "version": "0.0.0",  
  "private": true,  
  "main": "index.mjs",   
  "dependencies": {
    "@prismicio/helpers": "^2.3.9",
    "@prismicio/client": "^6.7.3"
  },   
  "devDependencies": {
    "eslint": "^8.35.0",
     "eslint-plugin-node": "^11.1.0",
     "msw": "^1.1.0",
     "node-fetch": "^3.3.0",
     "vitest": "^0.28.5"
  } 
}

目前的问题是：消费应用的node_modules中已安装了@prismicio/client和@prismicio/helpers，但只有当本地包自身存在node_modules目录时，应用才能正常解析这些传递依赖，否则就会报错。

问题原因与解决方法 #

原因分析 #

Node.js ESM模块解析机制对本地file:依赖的处理逻辑，与npm发布的包存在差异：

• 对于npm发布的包，Node会自动向上遍历目录，从消费应用的node_modules中查找传递依赖；
• 对于本地file:引用的包，Node默认优先从本地包自身的node_modules查找依赖，不会自动向上遍历消费应用的node_modules目录。

解决办法 #

方法1：启用--preserve-symlinks启动标志

启动消费应用时添加该标志，让Node在解析模块时保留符号链接，允许向上遍历查找消费应用的node_modules：

node --preserve-symlinks index.mjs

如果通过npm脚本启动，修改package.json的scripts字段：

{
  "scripts": {
    "dev": "node --preserve-symlinks src/index.mjs"
  }
}

方法2：使用npm link替代file:引用

通过符号链接将本地包关联到消费应用的node_modules，让依赖解析逻辑与普通npm包一致：

1. 在本地包prismic-utils目录执行：

npm link

2. 在消费应用目录执行：

npm link prismic-utils

方法3：添加exports字段明确模块导出（可选）

在本地包的package.json中添加exports字段，帮助Node更精准地解析模块路径：

{
  "name": "prismic-utils",
  "main": "index.mjs",
  "exports": "./index.mjs",
  // 其他已有字段...
}

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