在 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。具体分三步实现：
-
配置 tsconfig.json 输出 .js + 启用 verbatimModuleSyntax（推荐）
{ "compilerOptions": { "module": "esnext", "target": "es2020", "outDir": "./dist", "rootDir": "./src", "esModuleInterop": true, "verbatimModuleSyntax": true, // ✅ 关键：禁用自动扩展名补全，强制显式声明 "allowImportingTsExtensions": false, // ✅ 显式关闭（默认即 false，但建议明确） "skipLibCheck": true, "forceConsistentCasingInFileNames": true } } -
构建并运行时使用 .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 结构一致，即可无扩展名工作。
-
现代替代方案：使用 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' 语法，兼顾类型安全、构建确定性与运行时稳定性。
