TypeScript启用顶层await如何保留无.js后缀的导入体验

需要在Node.js + TypeScript项目中使用顶层await特性，切换模块配置为ESNext并添加"type": "module"后，出现导入路径需要补.js后缀、目录index导入失效、VSCode自动导入不匹配的问题，需要在保留原有CommonJS风格导入习惯的前提下使用顶层await。

不需要切换到ESM模块体系，调整tsconfig配置即可直接使用顶层await，所有原有导入写法完全兼容：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": [
      "dom",
      "es2017",
      "es2022",
      "esnext.asynciterable"
    ],
    "skipLibCheck": true,
    "sourceMap": true,
    "outDir": "./dist",
    "moduleResolution": "node"
    // 其余无关配置保持原有值即可
  }
}

• 删除package.json中添加的"type": "module"配置
• 所有原有导入逻辑无需修改：不需要手动补.js后缀，支持直接导入目录名自动解析index文件，VSCode自动导入行为完全正常
• TypeScript会自动将顶层await编译为CommonJS兼容的异步自执行函数包装逻辑，Node.js 14.8及以上版本可直接运行，兼容性更好

如果因其他项目需求必须使用原生ES模块，可按以下配置适配：

1. 调整tsconfig核心模块配置

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "NodeNext",
       "moduleResolution": "NodeNext",
       "lib": [
         "dom",
         "es2017",
         "es2022",
         "esnext.asynciterable"
       ],
       "skipLibCheck": true,
       "sourceMap": true,
       "outDir": "./dist"
       // 其余无关配置保持原有值即可
     }
   }
   

   该配置下TypeScript会自动适配Node.js ESM的路径解析规则：导入时写.js后缀会自动映射到对应.ts源文件，不需要提前编译生成js文件。
2. 修复VSCode自动导入后缀问题
   在工作区.vscode/settings.json中添加如下配置，自动补全导入时的.js后缀：

   {
     "typescript.preferences.importModuleSpecifierEnding": "js"
   }
   

3. 目录导入说明
   原生ESM规范本身不支持自动解析目录下的index文件，属于CommonJS专属特性，原生Node.js运行时无官方支持方案。如果需要省略/index.js路径，需要额外搭配构建工具（esbuild、rollup等）做路径解析转换。

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