当前位置：首页 > 文章列表 > 文章 > 前端 > TS ESM 自动解析 .ts 扩展名方法

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

2026-04-04 18:27:24 0浏览收藏

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

TypeScript ESM 导入中自动解析 .ts 文件扩展名的解决方案

在 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。

? 总结：