**这是本文档旧的修订版!**
什么是 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全都没有,用了就是运行时 ReferenceError。需要 require 时用、filenamemodule.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则可能编译通过但运行时报ERRMODULENOT_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。什么时候改扩展名、什么时候不改,本质只看一件事——这个文件的模块格式是否和所在项目的默认值不一致。 相关:ES 模块导入 / 导出语法、类型声明文件(.d.ts)