[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 moduleResolution, TypeScript 中的 rootDirs

TypeScript 中的 moduleSuffixes

一句话定义

moduleSuffixes 用来覆盖 TypeScript 解析模块时尝试的文件名后缀顺序。

核心机制 / 工作原理

官方文档的定义很直接：

• override the default list of file name suffixes to search when resolving a module

例如：

{
  "compilerOptions": {
    "moduleSuffixes": [".ios", ".native", ""]
  }
}

当代码写：

import * as foo from "./foo";

TypeScript 就会按顺序尝试：

• ./foo.ios.ts
• ./foo.native.ts
• ./foo.ts

官方文档还特别提醒：

• 最后的空字符串 "" 很重要
• 没有它，TypeScript 就不会再回退到普通 ./foo.ts

最小例子 / 最小场景

它最常见于：

• React Native 多平台文件命名
• 不同目标环境使用不同源码后缀

边界与易混淆点

它不等于 alias

它不负责把某个 import 前缀映射到另一个目录，只负责：

• 同一路径名下，优先尝试哪些后缀版本

它属于模块解析顺序的细化

因此它更接近：

• TypeScript 中的 moduleResolution

而不是输出结构选项。

忘记写 "" 是常见坑

如果想保留对普通文件名的回退能力，空字符串通常必须显式写上。

参考信息

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