模块互操作不再难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浏览器异步加载异步加载依赖代表是 RequireJSCommonJSNode.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 flagTS1259。因为 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、nodeNode10、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 modulemoduleResolution配置不匹配检查 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这类默认导入就能顺畅编译、正确运行模块互操作不再是拦路虎。✅总结记住这三条就够了esModuleInterop: true是模块互操作的基石Node 项目几乎必开allowSyntheticDefaultImports只是类型层面的放行别指望它解决运行问题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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考