====== 什么是 mts 文件 ======
''.mts'' 是 TypeScript 的**ES Module 专用扩展名**,m 就是 module 的意思。它的作用是:不管当前项目根目录的 package.json 里写没写 ''"type": "module"'',这个文件都按 **ESM(ES 模块)** 来处理。
这套扩展名(''.mts'' / ''.cts'')是 TypeScript 4.5 引入的,配套的 Node16 / NodeNext 模块解析在 4.7 定型。
===== 一、和其他扩展名的对应关系 =====
^ 源文件 ^ 模块格式 ^ 编译后产物 ^ 声明文件 ^
| ''.ts'' | 看最近的 package.json:''"type": "module"'' 是 ESM,否则是 CJS | ''.js'' | ''.d.ts'' |
| ''.mts'' | **始终是 ESM** | ''.mjs'' | ''.d.mts'' |
| ''.cts'' | **始终是 CommonJS** | ''.cjs'' | ''.d.cts'' |
| ''.mjs'' / ''.cjs'' | 这俩是 JavaScript 文件,不是 TS 源文件 | — | — |
记法:''m'' = module(ESM),''c'' = commonjs。''.mts'' 是给 TS 写的,''.mjs'' 是它编译出来的结果。
===== 二、主要特点 =====
- **强制 ESM,忽略 package.json**:这是它存在的全部意义。项目整体是 CJS 时,想单独让某个文件用 ESM,就把它改名成 ''.mts''。
- **产出 .mjs,声明是 .d.mts**:TypeScript 靠扩展名就能决定输出的模块系统,不用再靠 ''module'' 选项去猜。
- **天然就是模块**:即使文件里一个 import/export 都没有,也不会被当成全局脚本,变量不会污染全局作用域。
- **相对导入必须带"编译后"的扩展名**:''./util.mts'' 要写成 ''import ... from "./util.mjs"''(TypeScript 会自动映射回 ''.mts'' 源文件);普通的 ''util.ts'' 则写 ''./util.js''。因为 Node 的 ESM 规定不能省略扩展名。真想直接写 ''.ts'' / ''.mts'' 后缀,需要开 ''allowImportingTsExtensions''(并要求 ''noEmit'' 或 ''emitDeclarationOnly'')。
- **可以用 ESM 才有的东西**:顶层 await、''import.meta.url''、动态 ''import()''。
- **不能用 CJS 才有的东西**:''require''、''module.exports''、''__dirname''、''__filename'' 全都没有,用了就是运行时 ReferenceError。需要 require 时用 ''module.createRequire(import.meta.url)'';Node 20.11+ 可直接用 ''import.meta.dirname'' / ''import.meta.filename''。
- **''import x = require("x")'' 这种写法只能出现在 .cts 里**,写进 ''.mts'' 会直接报错。
- **tsconfig 必须配对上**:''module'' / ''moduleResolution'' 建议设成 ''node16'' 或 ''nodenext'',扩展名才会真正影响模块格式判定;否则顶层 await 之类的语法也会报错。
===== 三、什么时候用它 =====
- 项目整体是 CJS(没写 ''"type": "module"''),但某个文件想用 ESM。
- 反过来:项目整体是 ESM,但某个文件必须是 CJS(比如只支持 CJS 的旧工具配置)。
- 发布 npm 包时同时提供两种入口:''src/index.mts'' → ''dist/index.mjs'',''src/index.cts'' → ''dist/index.cjs''。
- 需要用顶层 await 等只在 ESM 下合法的语法,用 ''.mts'' 明确表态,省得别人误判成 CJS。
- **不必用的场合**:老的 Node CJS 项目,或者全程交给打包器处理、不关心模块格式时,普通 ''.ts'' 就够了,没必要特意改扩展名。
===== 四、例子 =====
// src/util.mts
export function greet(name: string): string {
return `hi ${name}`;
}
export interface User { id: number; name: string; }
// src/main.mts
import { greet } from "./util.mjs"; // 注意:写的是编译后的 .mjs
import type { User } from "./util.mjs"; // 只导入类型
const user: User = { id: 1, name: "ts" };
const res = await fetch("https://example.com"); // 顶层 await 允许
console.log(greet(user.name), import.meta.url);
// tsconfig.json
{
"compilerOptions": {
"target": "es2022",
"module": "node16",
"moduleResolution": "node16",
"outDir": "dist",
"declaration": true,
"strict": true
},
"include": ["src"]
}
编译与运行:
tsc
node dist/main.mjs
产物是 ''dist/util.mjs''、''dist/util.d.mts''、''dist/main.mjs''。
===== 五、常见坑 =====
- **直接让 node 跑 .mts 会失败**(旧版本报 ''Unknown file extension ".mts"'')。要么先编译,要么用 tsx / ts-node / esbuild 这类工具,要么用较新 Node 的类型剥离(22.6+ 加 ''--experimental-strip-types'',23.6+ 默认开启)。
- **忘记给相对导入加扩展名** → ''node16'' / ''nodenext'' 下 TypeScript 会直接报错,配 ''commonjs'' 则可能编译通过但运行时报 ''ERR_MODULE_NOT_FOUND''。
- **在 .mts 里写 require / __dirname** → 运行时 ReferenceError。
- **package.json 的 exports 要按条件分开写**:''"import"'' 指向 ''.mjs''、''"require"'' 指向 ''.cjs''(类型则分别指向 ''.d.mts'' / ''.d.cts''),否则用户实际加载到的可能还是另一种格式。
- **开了 ''verbatimModuleSyntax'' 后**,类型必须写成 ''import type'' / ''export type'',否则编译时不会帮你擦除。
- **多个 .mts 之间共享类型时**要导出类型而不是值,避免生成多余的运行时 import。
===== 六、小结 =====
''.mts'' 就是「这个文件一定是 ESM」的显式声明:产物 ''.mjs''、声明 ''.d.mts''、能用顶层 await 和 import.meta,但用不了 require / __dirname。什么时候改扩展名、什么时候不改,本质只看一件事——**这个文件的模块格式是否和所在项目的默认值不一致**。
相关:[[typescript:module与cjs的区别|module 与 CommonJS 的区别]]、[[typescript:导入模块|ES 模块导入 / 导出语法]]、[[typescript:第十一章_类型声明文件|类型声明文件(.d.ts)]]