TypeScript与Node.js相对导入报错求助：独立部署build文件夹遇问题

问题根源 #

你的项目采用ESM格式（package.json中"type":"module"），而Node.js的ESM规范要求相对导入必须带完整文件后缀（如.js）。原配置下TypeScript编译后的代码保留了无后缀的导入路径，导致Node无法找到对应模块；切换到node16解析模式时，TS会强制要求源码符合ESM导入规则，因此报错。

解决方案 #

1. 修正tsconfig.json配置 #

调整编译选项以匹配Node.js ESM的解析规则，确保TS编译后自动生成带正确后缀的导入语句：

{
  "compilerOptions": {
    "outDir": "./build",
    "strict": true,
    "baseUrl": "./src",
    "rootDir": "./src",
    "esModuleInterop": true,
    // 核心配置：对齐Node的ESM解析逻辑
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2020", // 适配Node18+的ES特性支持
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "build"]
}

2. 调整源码中的导入语句 #

在TS源码里，相对导入需要指定编译后的文件后缀（即.js），TS会自动映射到对应的.ts源文件：

// index.ts
import { HelloWorld } from "./other.js";

这样编译后生成的index.js中，导入语句会保持./other.js，符合Node.js ESM的要求。

3. 确认构建流程细节 #

• 确保build目录下的package.json同样包含"type":"module"，否则Node会将该目录下的文件当作CJS解析，引发新的兼容问题。
• 构建顺序建议：先执行npx tsc编译TS代码，再复制package.json到build目录，最后执行npm install --prefix ./build --omit=dev安装生产依赖（顺序不影响结果，但确保编译后的文件已生成）。

验证结果 #

编译后检查build/index.js的内容，确认导入语句为：

import { HelloWorld } from "./other.js";

此时执行node build/index.js即可正常运行。

补充说明 #

• Node16/NodeNext解析模式严格遵循Node.js的模块规则，因此TS会强制要求源码导入符合ESM规范，这是为了保证编译后的代码能直接被Node正确解析。
• 若不想在源码中写.js后缀，也可以使用tsc-alias等工具自动替换路径，但推荐遵循官方规范的写法，避免额外依赖。

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