导入未加.js后缀导致外部模块加载失败的原因排查

问题背景 #

• 在Docker容器中使用pnpm+pm2运行Node.js项目（app-b）时，导入外部库library-a出现大量模块找不到错误
• library-a与app-b的package.json均配置了"type": "module"
• library-a经tsc编译后自身运行正常，但被app-b导入执行import liba from 'library-a'时触发报错

错误日志 #

Error: Cannot find module '/home/app/node_modules/.pnpm/@termsurf+task@0.0.58_@termsurf+task-host@0.0.3_eslint-plugin-import@2.29.1/node_modules/@termsurf/task/host/code/action/convert/document/handler' imported from /home/app/node_modules/.pnpm/@termsurf+task@0.0.58_@termsurf+task-host@0.0.3_eslint-plugin-import@2.29.1/node_modules/@termsurf/task/host/code/tool/node/command.js
    at finalizeResolution (node:internal/modules/esm/resolve:264:11)
    at moduleResolve (node:internal/modules/esm/resolve:917:10)
    at defaultResolve (node:internal/modules/esm/resolve:1130:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:396:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:365:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:240:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:85:39)
    at link (node:internal/modules/esm/module_job:84:36)

library-a的导入示例 #

// index.js
import foo from './foo'
import bar from './bar.js'
import baz from './baz/index.js'

app-b的tsconfig.json配置 #

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2020",
    "lib": ["es2020", "dom"],
    "outDir": "host",
    "rootDir": ".",
    "sourceMap": true,
    "declaration": true,
    "moduleResolution": "node",
    "strictNullChecks": true,
    "strict": true,
    "esModuleInterop": true,
    "noUncheckedIndexedAccess": true,
    "baseUrl": ".",
    "allowJs": false,
    "noErrorTruncation": false,
    "resolveJsonModule": true,
    "types": ["node"],
    "typeRoots": ["node_modules/@types"],
    "noImplicitAny": false,
    "paths": {
      "~/*": ["./*"]
    }
  },
  "include": ["*.ts", "./**/*.ts", "*.d.ts", "declare.d.ts"],
  "exclude": ["node_modules", "host", "tmp", "test"]
}

问题成因 #

1. ESM模块的严格路径解析规则 #

Node.js的ES模块（ESM）完全遵循ECMAScript规范，要求相对路径导入必须包含完整的文件扩展名（如.js）。CommonJS模块支持省略扩展名自动补全，但ESM不兼容这一特性。library-a编译后的代码中存在import foo from './foo'这类省略扩展名的语句，Node.js运行时无法自动补全扩展名，导致找不到对应模块。

2. library-a本地运行正常的隐藏原因 #

library-a自身运行正常，大概率是因为开发/测试环境依赖了ts-node、webpack等工具，这些工具会在编译或运行阶段自动补全文件扩展名；或者其测试环境的模块解析规则较为宽松，掩盖了扩展名缺失的问题。而tsc编译仅负责将TypeScript转译为JavaScript，默认不会为相对导入添加.js扩展名，保留了原有的不规范导入路径。

3. TypeScript编译与Node.js运行时的解析规则差异 #

app-b的tsconfig中moduleResolution设置为node，这在TypeScript编译阶段可以正常解析省略扩展名的导入，但编译后的ESM代码在Node.js运行时，依然会因为缺少扩展名触发报错。TypeScript的模块解析是编译时逻辑，而Node.js的ESM解析是运行时逻辑，两者规则不匹配导致问题暴露。

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