TS ESM 自动解析 .ts 扩展名方法

本文深入解析了TypeScript项目切换至原生ESM（"type": "module"）后无法省略.ts扩展名导入的根源问题——Node.js ESM加载器不识别.ts为合法运行时扩展，而启用allowImportingTsExtensions又违背标准、破坏工具链兼容性；文章摒弃临时妥协方案，提出标准化、可落地的三步解法：通过verbatimModuleSyntax禁用TS启发式补全、配置tsc输出结构一致的.js产物、配合tsx/bun/Vite等现代运行时实现真正的无扩展名导入，让开发者在享受ESM规范红利的同时，兼顾类型安全、构建确定性与运行时稳定性。

在 TypeScript 项目切换为 ESM（"type": "module" + "module": "esnext"）后，省略 .ts 扩展名的导入会失败；启用 allowImportingTsExtensions 又会导致类型检查异常。本文提供符合标准、无需手动加扩展名的安全解决路径。

在 TypeScript 项目切换为 ESM（"type": "module" + "module": "esnext"）后，省略 .ts 扩展名的导入会失败；启用 allowImportingTsExtensions 又会导致类型检查异常。本文提供符合标准、无需手动加扩展名的安全解决路径。

当 TypeScript 项目从 CommonJS 迁移至原生 ESM（即设置 "type": "module" 且 tsc 的 module 选项为 "esnext"）时，一个常见但易被忽视的兼容性问题是：Node.js 的 ESM 加载器默认不支持自动解析 .ts 源文件——它只识别 .js、.cjs、.mjs 等运行时有效扩展名，而 .ts 是编译期产物，不属于 Node.js 原生模块解析规则。

因此，以下写法会报错：

// getButton.ts
import { Button } from "../../../objects/Button"; // ❌ Node 报错：Cannot find module ".../Button"

即使 Button.ts 存在，Node.js ESM 加载器也无法自动补全 .ts 扩展名。而若强行写成：

import { Button } from "../../../objects/Button.ts"; // ❌ 编译报错（除非启用特定选项）

则会触发 TypeScript 编译错误：

An import path can only end with a '.ts' extension when 'allowImportingTsExtensions' is enabled.

⚠️ 关键误区澄清：allowImportingTsExtensions: true 并非推荐解。该选项虽允许 .ts 扩展名出现在 import 语句中，但它违背了 ESM 规范（ECMAScript 不定义 .ts 为合法模块扩展），且会导致构建工具链（如 Vite、Webpack、esbuild）行为不一致，还可能干扰类型检查与路径映射（如 paths 别名）。

✅ 正确且标准化的解决方案是：让 TypeScript 输出 .js 文件，并确保导入路径指向已生成的 .js（或 .mjs）产物，而非源码 .ts。具体分三步实现：

1. 配置 tsconfig.json 输出 .js + 启用 verbatimModuleSyntax（推荐）

   {
     "compilerOptions": {
       "module": "esnext",
       "target": "es2020",
       "outDir": "./dist",
       "rootDir": "./src",
       "esModuleInterop": true,
       "verbatimModuleSyntax": true, // ✅ 关键：禁用自动扩展名补全，强制显式声明
       "allowImportingTsExtensions": false, // ✅ 显式关闭（默认即 false，但建议明确）
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true
     }
   }

2. 构建并运行时使用 .js 入口
   编译后，Button.ts → dist/objects/Button.js，此时应导入：

   // getButton.ts（源码中仍写逻辑路径，但需确保构建后对应 .js）
   import { Button } from "../../../objects/Button"; // ✅ 正确：TS 编译器根据声明文件（.d.ts）解析类型，Node 运行时加载 dist/objects/Button.js

   ? 原理：TypeScript 在编译阶段通过 rootDir/outDir 和声明文件（.d.ts）完成类型解析；而 Node.js 运行时实际加载的是 dist/objects/Button.js（由 tsc 或 tsup 等工具生成）。只要 package.json#main 或 exports 指向正确的 .js 入口，且 import 路径与 outDir 结构一致，即可无扩展名工作。

3. 现代替代方案：使用 tsc --build + --preserveSymlinks 或工具链集成
   若采用 Vite / tsx / Bun 等开发环境，推荐直接启用 transpileOnly: true + esbuild 转译（跳过类型检查），或使用 tsx 运行时：

   npm install -D tsx
   # package.json scripts:
   "dev": "tsx watch src/index.ts"

   tsx 内置 ESM 支持，可自动解析 .ts 导入（底层通过 require.resolve + ts-node 式劫持），且不依赖 allowImportingTsExtensions。

? 总结：

• ❌ 避免启用 allowImportingTsExtensions —— 它是临时妥协，破坏标准化与工具链兼容性；
• ✅ 坚持“源码无扩展名 + 构建产出 .js + 运行时加载 .js”的正交设计；
• ✅ 使用 verbatimModuleSyntax: true 显式关闭 TS 的扩展名启发式补全，提升可预测性；
• ✅ 开发阶段优先选用 tsx、bun run 或 Vite 等现代运行时，它们已内置对无扩展名 .ts 导入的健壮支持。

遵循以上实践，即可在 ESM 下优雅支持干净的 import { X } from './mod' 语法，兼顾类型安全、构建确定性与运行时稳定性。

以上就是《TS ESM 自动解析 .ts 扩展名方法》的详细内容，更多关于的资料请关注golang学习网公众号！