使用npx运行本地NPM包时出现ERR_MODULE_NOT_FOUND错误的解决方法

问题重现 #

运行本地打包后的tgz包时出现模块找不到错误：

> npx -y [organization]-[package]-0.0.1.tgz
node:internal/errors:496
    ErrorCaptureStackTrace(err);
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'C:\Users\wathhr\AppData\Local\npm-cache\_npx\9765d4346a8e56c1\node_modules\[organization]\[package]\node_modules\fs-extra\lib\index.js' imported from C:\Users\wathhr\AppData\Local\npm-cache\_npx\9765d4346a8e56c1\node_modules\[organization]\[package]\dist\bin.js
    at new NodeError (node:internal/errors:405:5)
    at finalizeResolution (node:internal/modules/esm/resolve:324:11)
    at moduleResolve (node:internal/modules/esm/resolve:943:10)
    at defaultResolve (node:internal/modules/esm/resolve:1129:11)
    at nextResolve (node:internal/modules/esm/loader:163:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:835:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
    at link (node:internal/modules/esm/module_job:76:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}

问题原因 #

你的esbuild配置中external: ['./node_modules/*']会让打包后的代码尝试从当前包目录下的node_modules加载依赖，但npm安装本地tgz包时，依赖会被安装在全局npx缓存的根node_modules目录，而非包自身的node_modules，导致路径解析错误。

解决方案 #

修改esbuild的external配置，直接指定依赖包名而非相对路径：

方案1：自动提取所有生产依赖（推荐） #

{
  entryPoints: ['./src/index.ts'],
  outfile: './dist/bin.js',
  banner: {
    'js': '#!/usr/bin/env node',
  },
  minify: false,
  bundle: true,
  external: Object.keys(require('./package.json').dependencies), // 自动读取dependencies中的包名
  platform: 'node',
  format: 'esm',
  logLevel: 'info',
}

方案2：手动列出所有依赖 #

如果不想动态读取package.json，也可以手动列出所有需要外部化的依赖：

{
  // ...其他配置
  external: ['@clack/prompts', 'command-exists', 'fs-extra', 'ts-deepmerge'],
  // ...其他配置
}

验证步骤 #

1. 重新执行打包：npm run build
2. 重新生成tgz包：npm pack
3. 运行新生成的tgz包：npx -y ./[organization]-[package]-0.0.1.tgz

注意事项 #

• 确保package.json的dependencies中包含所有代码中用到的第三方包，避免遗漏
• 方案1的动态读取方式更易于维护，新增依赖时无需手动修改esbuild配置

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