[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 module, TypeScript 中的 allowImportingTsExtensions, TypeScript 中的 nodenext 与 bundler

TypeScript 中的 rewriteRelativeImportExtensions

一句话定义

rewriteRelativeImportExtensions 会把相对导入路径中的 .ts / .tsx / .mts / .cts 扩展名，在输出文件里改写成对应的 JavaScript 扩展名。

核心机制 / 工作原理

官方文档的定义非常直接：

• rewrite relative import paths to their JavaScript equivalent in output files

它解决的是这样一类问题：

• 源码里为了表达真实文件名，直接写了 .ts 或 .mts
• 但输出后的 JS 文件里，这些扩展名已经不对了

开启后，TypeScript 会在 emit 阶段把这些相对导入改写成目标 JS 扩展名。

最小例子 / 最小场景

{
  "compilerOptions": {
    "rewriteRelativeImportExtensions": true
  }
}

这在以下场景更容易出现价值：

• 直接写带扩展名的相对导入
• Node ESM / nodenext 风格项目
• 希望源码和输出相对路径都尽量保持明确

边界与易混淆点

它只处理“相对导入里的扩展名改写”

它不负责：

• 模块怎么找
• alias 怎么映射
• package exports 怎么选

它是 emit 期改写，不是类型检查放宽

也就是说，它主要解决的是：

• 输出 JS 的 import 路径长什么样

而不是：

• TypeScript 是否接受某条导入

它和现代 ESM 场景关系更强

官方页面还直接把更多说明链接到了 TypeScript 5.7 release notes，这也说明它属于较新的模块输出细化能力。

它和 allowImportingTsExtensions 是相邻但不同的开关

• allowImportingTsExtensions 先决定源码里能不能直接写 .ts
• rewriteRelativeImportExtensions 再决定输出时这些扩展名要不要改成 JS 版本

参考信息

• TSConfig rewriteRelativeImportExtensions: https://www.typescriptlang.org/tsconfig/rewriteRelativeImportExtensions.html