.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 是它编译出来的结果。
.mts。module 选项去猜。./util.mts 要写成 import … from “./util.mjs”(TypeScript 会自动映射回 .mts 源文件);普通的 util.ts 则写 ./util.js。因为 Node 的 ESM 规定不能省略扩展名。真想直接写 .ts / .mts 后缀,需要开 allowImportingTsExtensions(并要求 noEmit 或 emitDeclarationOnly)。import.meta.url、动态 import()。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 会直接报错。module / moduleResolution 建议设成 node16 或 nodenext,扩展名才会真正影响模块格式判定;否则顶层 await 之类的语法也会报错。“type”: “module”),但某个文件想用 ESM。src/index.mts → dist/index.mjs,src/index.cts → dist/index.cjs。.mts 明确表态,省得别人误判成 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。
Unknown file extension “.mts”)。要么先编译,要么用 tsx / ts-node / esbuild 这类工具,要么用较新 Node 的类型剥离(22.6+ 加 –experimental-strip-types,23.6+ 默认开启)。node16 / nodenext 下 TypeScript 会直接报错,配 commonjs 则可能编译通过但运行时报 ERRMODULENOT_FOUND。“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。什么时候改扩展名、什么时候不改,本质只看一件事——这个文件的模块格式是否和所在项目的默认值不一致。
相关:module 与 CommonJS 的区别、ES 模块导入 / 导出语法、类型声明文件(.d.ts)