如何在TypeScript中同时使用Top Level Await与路径别名？

直接上可行的配置步骤，解决你遇到的"Must use import to load ES Module"错误：

1. 调整tsconfig.json为ES模块配置 #

确保TypeScript编译配置完全适配ES模块，同时保留路径别名：

{
  "compilerOptions": {
    "target": "ES2022", // Top Level Await至少需要ES2017，选更高版本更稳妥
    "module": "ESNext", // 输出ES模块格式
    "moduleResolution": "NodeNext", // 遵循Node.js的ES模块解析规则
    "baseUrl": "./src", // 路径别名的基准目录
    "paths": {
      "@/*": ["*"] // 示例：@/xxx 对应 src/xxx 路径
    },
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"]
}

2. 配置package.json声明ES模块 #

在package.json中添加type: "module"，明确告诉Node.js整个项目采用ES模块规范：

{
  "name": "your-project",
  "type": "module",
  "scripts": {
    // 后续添加启动/编译脚本
  },
  // ...其他项目配置
}

3. 调整ts-node-dev启动命令 #

替换原启动命令，适配ES模块和路径别名的加载逻辑：

ts-node-dev --loader ts-node/esm --loader tsconfig-paths/esm src/index.ts

• --loader ts-node/esm：让ts-node-dev以ES模块模式处理TypeScript文件
• --loader tsconfig-paths/esm：确保路径别名在ES模块环境下正常生效

如果要写到package.json的scripts里：

"scripts": {
  "dev": "ts-node-dev --loader ts-node/esm --loader tsconfig-paths/esm src/index.ts"
}

4. 编译时的路径别名处理 #

tsc编译后不会自动替换路径别名，需要用工具处理，推荐tsc-alias：

1. 安装依赖：

npm install tsc-alias --save-dev

2. 修改build脚本：

"scripts": {
  "build": "tsc && tsc-alias"
}

编译完成后，代码中的路径别名会被替换为正确的相对路径，保证生产环境正常运行。

注意事项 #

• 项目中统一用import导入模块，不要混用require（ES模块环境下require会触发报错）
• 确保tsconfig-paths为最新版本，避免兼容性问题：npm update tsconfig-paths
• 不要给文件加.cjs后缀，保持.ts即可，配合type: module使用

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