模块互操作不再难：TypeScript-New-Handbook 之 esModuleInterop 等配置解密

模块互操作不再难：TypeScript-New-Handbook 之 esModuleInterop 等配置解密

【免费下载链接】TypeScript-New-HandbookIncubation repository for the new TypeScript handbook 🐣项目地址: https://gitcode.com/gh_mirrors/ty/TypeScript-New-Handbook

在 TypeScript 项目里，"模块互操作"几乎是每个新手都会踩的坑：import express from "express"明明写得没错，编译器却报错，Node 运行起来又是另一个样子。其实这一切的根源，都藏在esModuleInterop、allowSyntheticDefaultImports这几个编译配置里。本文基于开源孵化项目TypeScript-New-Handbook（新一代 TypeScript 官方手册的中文参考仓库），用最通俗的方式为你解密 TypeScript 模块互操作配置，读完就能配好属于自己的tsconfig.json。🚀

为什么会有"模块互操作"这个难题？

要理解模块互操作，得先回到 JavaScript 的模块历史。TypeScript-New-Handbook 的 chapters/Modules.md 章节用一整章篇幅梳理了这段"混乱史"，简单说就是：JavaScript 先后出现过多种互不兼容的模块规范：

模块规范	出现场景	核心特点
全局脚本	早期<script>标签	无模块，全靠全局变量
AMD	浏览器异步加载	异步加载依赖，代表是 RequireJS
CommonJS	Node.js	同步require，模块与文件一一对应
UMD	兼容各类环境	万能包装，自动检测运行环境
ES6 Modules	语言标准	静态import/export，官方统一

TypeScript 必须同时支持这些规范，于是"模块互操作"（Module Interop）就成了绕不开的课题：用 ES6 的 import 语法去加载 CommonJS 模块时，如何保证类型正确、运行正确。这就是esModuleInterop等配置要解决的问题。

esModuleInterop 是什么？默认导入的"救星"⭐

最常见的痛点场景：你安装了一个 npm 包，它的源码是用 CommonJS 写的（比如老版本的 Express），你在 TypeScript 里写：

import express from "express"; // 默认导入

在未开启esModuleInterop时，TypeScript 会报错："Module can only be default-imported using the 'esModuleInterop' flag"（TS1259）。因为 CommonJS 模块导出的是module.exports整个对象，并没有名为default的属性。

开启esModuleInterop: true后，TypeScript 会在编译产物里插入一个辅助函数，运行时自动检测 CommonJS 模块并为其补上.default属性，让默认导入语法畅通无阻。这也是目前绝大多数现代项目推荐开启该选项的原因。

esModuleInterop 与 allowSyntheticDefaultImports 的区别

新手最容易混淆的两个配置，其实作用完全不同：

配置项	作用	是否改变编译产物
allowSyntheticDefaultImports	仅让类型检查"放行"，假装有 default 属性	❌ 不改变产物，运行仍可能报错
esModuleInterop	生成辅助代码，真正兼容 CommonJS 的默认导入	✅ 改变编译产物，运行正确

一句话总结：allowSyntheticDefaultImports只管"类型层面"，esModuleInterop管"运行层面"。而且开启esModuleInterop会自动隐式开启allowSyntheticDefaultImports，所以日常开发直接开esModuleInterop就够了。这段内容在 chapters/Modules.md 的 "Synthetic Defaults and esModuleInterop" 小节有详细说明。

module 与 moduleResolution：配套的"模块双子星"

esModuleInterop不是孤军奋战，它还受两个关键配置影响：

module：决定编译成哪种模块格式

module配置控制 TypeScript 编译后输出的模块格式，可选值包括CommonJS、ES6、AMD、UMD、System等。在 reference/Compiler Options.md 中可以看到：默认值取决于target，比如target为 ES3/ES5 时默认CommonJS，为 ES6 及以上时默认ES6。

简单选择建议：

• 🖥️Node.js 服务端项目→CommonJS（或Node16/NodeNext）
• 🌐浏览器项目→ES6交给打包工具处理
• 📦发布 npm 库→ 视目标环境而定

moduleResolution：决定 import 路径如何找到文件

moduleResolution决定 TypeScript 如何把import "./foo"解析成磁盘上的文件，常见取值有classic、node（Node10）、node16、nodenext、bundler等。写 ES6 模块语法 +moduleResolution: "node"是最经典稳妥的组合；使用 Vite 等打包工具时，"bundler"模式则更贴合现代开发。

💡 小贴士：module与moduleResolution需匹配使用，配置不当会出现"模块解析失败"或"只能默认导入"之类的诡异报错。二者共同构成了模块互操作配置的完整闭环。

常见模块互操作报错速查表

结合 TypeScript-New-Handbook 中记录的内容，这里整理一份高频报错对照：

报错现象	常见原因	解决思路
"can only be default-imported using the 'esModuleInterop' flag"	未开启esModuleInterop	在 tsconfig.json 中开启
import * as express from "express"后调用express()报错	对函数使用命名空间导入	改用默认导入
"Cannot find module"	moduleResolution配置不匹配	检查 module 与 moduleResolution 组合
CommonJS 消费者找不到default导出	用 ES6 语法写了export default	使用import ... = require(...)语法

其中"用import * as导入函数"是经典的模块互操作误区，chapters/Modules.md 的 "Namespace Imports of Functions and Classes" 小节专门讲解了这个问题。

一键配置示例：最适合新手的 tsconfig.json

把知识落到实践，这里给出一份适合新手起步的模块互操作配置，直接复制即可使用：

{ "compilerOptions": { "target": "ES2020", "module": "CommonJS", "moduleResolution": "node", "esModuleInterop": true, "allowSyntheticDefaultImports": true, "strict": true, "outDir": "./dist" } }

配置完成后，import express from "express"、import fs from "fs"这类默认导入就能顺畅编译、正确运行，模块互操作不再是拦路虎。✅

总结：记住这三条就够了

1. esModuleInterop: true是模块互操作的基石，Node 项目几乎必开；
2. allowSyntheticDefaultImports只是类型层面的"放行"，别指望它解决运行问题；
3. module与moduleResolution要配套，按项目运行环境选择。

想系统学习模块互操作的完整知识，可以翻阅 TypeScript-New-Handbook 仓库中的 chapters/Modules.md（模块历史与导入语法详解）、reference/Compiler Options.md（全部编译配置说明），以及 reference/File Inclusion.md（模块解析与文件包含规则）。动手配一遍，你就彻底告别模块互操作报错了。🎉

【免费下载链接】TypeScript-New-HandbookIncubation repository for the new TypeScript handbook 🐣项目地址: https://gitcode.com/gh_mirrors/ty/TypeScript-New-Handbook