TypeScript 模块化这个东西我做了五六年前端从纯 JS 时代一路写过来真的是感触很深。以前写 JS 脚本一个文件里堆几十个函数全局变量满天飞全靠命名约定和自觉来避免冲突。后来项目大了开始用立即执行函数表达式封装命名空间再后来借助构建工具手动管理依赖顺序每一步都走得小心翼翼。TypeScript 的模块系统解决的不只是“优雅”的问题它直接从语言层面把代码组织的边界给立住了让模块与模块之间靠显式的 import/export 建立联系任何跨越边界的访问都会被编译器拦住。这篇文章我打算结合自己的实际项目经验把 TypeScript 模块从语法细节到工程落地的完整链路拆开讲一遍重点会放在那些文档里不会写细、但实战中一定会撞上的问题上。1. 模块格式的认知纠偏TypeScript 不是一种模块标准而是模块标准的“翻译官”很多人刚接触 TypeScript 的时候有一个误区觉得“TypeScript 模块”是一种和 CommonJS、ESM 并列的模块标准。其实不是。TypeScript 从来没有定义过自己的运行时模块加载机制它做的核心事情是两件一是提供一套静态类型检查下的导入导出语法二是在编译时根据你的配置把这套语法翻译成目标运行环境能识别的模块代码。理解了这一点你就能明白为什么 tsconfig.json 里的module字段那么重要为什么同样的代码设置成 commonjs 和设置成 esnext 编译出来的产物差别巨大。1.1 ES Module 语法 vs CommonJS 语法不是二选一而是看运行环境ES Module 语法是 TypeScript 源码里最自然的写法import和export关键字直接写在代码里类型检查器可以根据这些语句精确地追踪标识符的来源和去向。但问题是浏览器原生支持的 ESM 和 Node.js 的 CommonJS 在加载机制上有根本差异浏览器用script typemodule配合 HTTP 请求加载Node.js 用require同步读取文件。TypeScript 在编译时帮你做的就是把源码里的import语句翻译成目标环境能识别的东西。我给你一个具体的例子。假设源码是这样的// math.ts export function add(a: number, b: number): number { return a b; }当你把module设成commonjs编译产物是这样的use strict; Object.defineProperty(exports, __esModule, { value: true }); exports.add add; function add(a, b) { return a b; }当module设成esnext编译产物就直接保留原始形式export function add(a, number, b: number) { return a b; }这里我想提醒一个容易踩的坑很多教程会让你直接推荐module: esnext因为看起来“现代化”。但如果你的项目最终是跑在 Node.js 上的而且 Node 版本不支持 ESM比如 12 版本之前那编译产物就会直接跑不起来。反过来module: commonjs在浏览器端又需要额外引入 require.js 之类的加载器。所以这个字段的选择要基于目标运行环境而不是基于“哪种写法更先进”。1.2 编译产物里的 __esModule 和 default 导入一个让无数人失眠的细节在 CommonJS 编译模式下产物里会出现那一行Object.defineProperty(exports, __esModule, { value: true })很多初学者看到这行代码会疑惑是干什么的。它是一个标志位告诉 TypeScript/Babel 之类的编译器“这个模块是用 ES Module 的规范编译过来的不是纯 CommonJS 手写的”。为什么需要这个标志位因为在 ESM 和 CommonJS 互操作的场景下import xxx from some-cjs-module和const xxx require(some-cjs-module)对 default 导出的处理是不一致的。具体点说如果你的模块是这么写的// foo.ts export default function sayHello() { console.log(hello); }编译成 CommonJS 后实际的exports对象里并没有一个叫default的属性。但 TypeScript 编译器在遇到import sayHello from ./foo时会到foo模块的exports对象上去取.default。如果foo模块是纯手写的 CommonJS比如第三方老库它根本没有default这个属性那导入就会变成undefined。为了让 ESM 语法能兼容这些老库编译器加了__esModule标志位当它看到__esModule true时就知道直接使用该模块的exports对象而不是去找.default。这也就解释了为什么有时候在 Node.js 环境里import一个 CommonJS 模块需要用import * as pkg from pkg或者用createRequire来处理。这些细节在真实项目中早晚会碰到提前了解能省掉很多排查时间。2. 接口与类型的模块化设计从“到处定义 interface”到“按域隔离类型”写了几年 TS 之后我形成的一个习惯是接口和类型的组织方式比业务代码的组织方式更能反映一个项目的架构水平。因为类型定义描述的是数据契约模块的边界定义了数据契约的适用范围。在混乱的项目里你会发现一个全局types.ts文件里堆了上百个 interface每个模块都在引入它而在结构清晰的项目里类型会和它所属的业务域绑定通用类型单独提取跨模块类型显式引入整个依赖关系一目了然。2.1 导出位置的陷阱为什么“就近导出”优于“集中导出”我在一个中型后台管理系统里见过这样一种做法在src/types目录下建一个index.ts然后在里面写export interface User { id: number; name: string; } export interface Product { id: number; price: number; } export interface Order { id: number; userId: number; productId: number; }然后业务代码里import { User, Product, Order } from /types。这样看起来很方便但随着项目迭代这个文件会越来越臃肿而且最要命的是类型之间的依赖关系全被抹平了。你根本不知道Order这个类型到底是哪个业务模块在用后续改动Order时就只能全局搜索引用点改完心里还没底。更好的做法是把类型定义放在离业务模块最近的地方。比如用户相关的接口就放在features/user/types.ts里订单相关的放在features/order/types.ts里。如果多个模块都需要用到用户类型那要么通过features/user公开导出要么把基础类型下沉到shared/types。这样做有几个实际好处改动影响面可控改类型时只需要看本模块的引用点不需要全局排查。依赖关系清晰代码的 import 路径直接表达了业务域的依赖方向。代码审查更高效评审者看到import type { Order } from /features/order/types就能立刻知道这个模块和订单领域存在耦合而不是看到一个笼统的/types不知道从哪儿冒出来的。2.2 类型导入的区别import type 与传统 import 的底层差异TypeScript 3.8 开始支持import type语法专门用于导入类型。它的作用是在编译时明确告诉编译器“这个导入我只是用来做类型标注的运行时不依赖它”。有了这个标记编译器在编译阶段就可以直接把对应类型从产物里剔除不会生成任何运行时导入代码。这里有个常见的性能困惑。很多人以为用了import type之后编译速度会变快其实不一定。编译速度提升是编译器层面“跳过模块解析”的结果在大型项目里确实会有优化但大多数项目的编译瓶颈不在类型导入上。这个语法真正的价值在于它让代码的意图显式化了。你写import type的时候读者一眼就能看出这个模块的依赖关系里不包含“运行时代码”类型信息和逻辑实现被明确分离。此外在isolatedModules或verbatimModuleSyntax开启的情况下import type还承担着一个关键职责保证单文件编译时不会因为类型导入而引发错误。因为像 Babel 这类工具是逐个文件转译的不理解类型系统。如果源码里写了import { SomeType } from ./types而实际上SomeType是纯类型Babel 在转译时不会删掉这行代码然后在浏览器运行时就可能报“模块中找不到导出”的错误。老老实实按规范写import type这类问题就能从源头避开。3. 命名空间和模块的边界感namespace 还能不能用了什么场景下值得用早期 TypeScript 里有个很有辨识度的特性叫namespace写起来像是给代码包了一个带名字的容器内部成员可以通过namespace Foo { export const bar 1; }定义外部通过Foo.bar访问。很多从 C# 和 Java 转过来的开发者会觉得这个特性和命名空间很像用起来特别顺手。但事实上namespace 在今天这个模块化大行其道的时代适用场景已经非常有限了。3.1 namespace 的设计初衷和它的历史包袱namespace 最初的设计目标其实是在没有模块系统的情况下组织大文件。早期 TypeScript 项目如果不想引入打包器又想解决全局命名冲突的问题namespace 就是一个很好的折中方案编译产物里用立即执行函数创建局部作用域对外只暴露一个全局对象。你可以在官方远古版本的练习代码里看到这种写法它是为了解决脚本文件之间“全局变量互相污染”问题而生的。但 ES Module 标准普及之后namespace 的定位就很尴尬了。模块系统本身就有文件级作用域export 是显式边界import 是显式依赖。namespace 能解决的问题模块系统全都能解决而且更规范。如果硬在模块内部再用 namespace等于是给一个房间里又砌了一堵墙代码反而绕了一层。不过有一个场景我觉得 namespace 还是有价值的当你的代码需要在“没有模块系统”的环境里运行时。比如一个单文件的脚本工具不支持 import/export但又不想把所有常量和方法都平铺在全局作用域里。这个时候用 namespace 做一层容器保护可以让代码保持一定的组织性。但这类场景在今天的工程环境里已经非常少了。3.2 用 namespace 做类型增强一个仍值得掌握的实战技巧namespace 还有一个很少有人注意到的神奇能力它可以对其它地方定义的类型做声明合并。比如你在写第三方库的类型声明文件.d.ts时想让一个已有的 interface 增加一个属性可以直接这样写interface Window { __CUSTOM_DEBUG_MODE__?: boolean; } declare namespace NodeJS { interface ProcessEnv { MY_CUSTOM_KEY: string; } }这种“声明合并”的能力是模块系统不具备的因为模块要求显式导入导出无法跨文件自动扩充已有的类型定义。所以如果你在做插件开发、工具库类型声明或者环境变量类型扩展namespace 仍然是一把有用的利器。但如果你只是写业务代码不要因为好奇而引入它老老实实用模块就对了。4. 模块解析策略的实战选择moduleResolution 的隐藏逻辑tsconfig 里有一个单独拎出来讲都不为过的配置项moduleResolution。它控制的是 TypeScript 编译器在解析import语句时按照什么规则去文件系统里找对应的模块文件。很多诡异报错的根因最后排查下来都和它有关。4.1 classic vs node16 vs bundler三者各解决了什么问题classic是最早期的解析策略规则简单相对路径按照路径直接找文件非相对路径在全局声明里找。它没有处理node_modules的逻辑所以只在远古项目里存在现在写新项目基本不会用到它。node16/nodenext是跟着 Node.js 的 ESM/CJS 双模式设计出来的。它最大的特点是“尊重 package.json 里的 type 字段”并且会根据模块格式决定导入规则。在 node16 策略下每个文件的模块格式由它所在目录的 package.json 的type字段决定type: module时是 ESM缺省时是 CommonJS。两种格式下 import 的解析规则会跟着变比如 ESM 下必须写.js扩展名来导入相对路径的.ts文件而 CommonJS 下则不需要或者说是另一个逻辑。bundler策略是 TypeScript 5.0 新增的它面向的是使用 Vite、Webpack、Rollup 这类打包器的项目。打包器通常允许不写扩展名、允许index.ts自动解析目录、允许导入 JSON 资源等等bundler策略就去掉了 node16 下那些严格的扩展名限制模拟打包器的宽松行为。我见过一个特别典型的报错场景项目用的是 Vite但 tsconfig 里的moduleResolution沿用旧项目里的node结果一旦代码里有import route from /router这种路径别名alias编译器就疯狂报错“无法找到模块”。原因就是旧策略不认识/这种自定义路径映射而 bundler 策略天然支持 resolver 扩展。4.2 路径别名配置从报错到修复的排错链路路径别名alias是一个在实际工程里几乎必然用到的配置它让我们可以写/components/Button而不是长长的../../../components/Button。配置路径别名需要两处配合第一处是 tsconfig.json{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }第二处是打包器的 resolve 配置以 Vite 为例// vite.config.ts import { defineConfig } from vite; import { fileURLToPath, URL } from node:url; export default defineConfig({ resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)), }, }, });TS 负责的是“编译时”告诉编译器/对应 src 目录Vite 负责的是“运行时/构建时”把/替换成真实路径。很多新手只配了 tsconfig发现还是报错就以为路径别名配置有问题其实大多数时候是打包器侧没跟上。反过来只配打包器不配 tsconfig编译器又会一直报红。这个两边同步的机制我觉得值得多讲一句TS 的 paths 解析是纯静态的它不会帮你改代码。你写的/components/Button在编译产物里依然会保留成/components/Button字符串真正把它解析成src/components/Button.ts的是打包器。所以无论用什么工具链两条线都要配齐才能跑通。5. 模块的循环依赖检测为什么编译过了运行起来还是 undefined循环依赖是模块化开发里一个特别令人头大的问题。它在 TypeScript 里有个很误导人的地方编译器检查循环依赖时通常不会报错因为类型检查只关心类型正确性不关心运行时加载顺序。但一旦代码真正跑起来你可能会在运行时遇到Cannot read properties of undefined之类的错误而且报错的位置往往和实际根因隔了十万八千里。5.1 一个真实的循环依赖场景还原我举一个简单但非常经典的例子。a.tsimport { fetchUser } from ./b; export const userService { getUser(id: number) { return fetchUser(id); }, };b.tsimport { userService } from ./a; export function fetchUser(id: number) { return id 1 ? { id, name: alice } : null; } export function init() { // 在模块初始化阶段就使用 userService return userService.getUser(1); }这个例子里a.ts和b.ts形成循环依赖。在 CommonJS 模式下Node.js 加载模块的时候第一次加载a.ts会先把它整个读进来然后发现要 importb.ts就暂停a的初始化去加载b。在加载b的过程中b又发现要 importa但此时a还在初始化过程中其exports对象还没有完全填充完。所以b拿到的a只是一个部分初始化的对象如果b在“模块顶层”就立即调用userService.getUser那就会报userService is undefined。很多人会以为循环依赖只有在代码写得很乱的时候才会出现。其实不然当项目规模变大工具函数之间互相依赖、业务模块之间交叉复用循环依赖的发生概率并不低。尤其是一些全局初始化逻辑比如路由配置、状态管理 store 的初始化、权限控制的预加载这类代码天然倾向于在模块顶层执行操作最容易踩到未初始化完成的坑。5.2 检测和规避循环依赖的实用手段应对循环依赖我现在的做法是两条腿走路。第一条腿用工具自动检测。我在项目里接入了一个叫madge的工具它可以在 CI 阶段做依赖图像分析直接找出循环依赖链并把告警打到 CI 日志里。接入方式很简单npm install -D madge # 分析 src 目录下的依赖关系输出循环依赖列表 npx madge --circular --extensions ts src/如果项目很大输出消息可能会比较长但至少它能给你一个方向。更细致一点的做法是使用 ESLint 插件import/no-cycle把这个规则加进 lint 流程每次提交代码时自动检查新增依赖是否产生了环。这样比事后看日志高效得多因为它是增量检查定位到的是“这次改动引入的”循环依赖。第二条腿架构上减少循环依赖的产生条件。我的经验是把代码按依赖方向分成三层底层通用工具无业务依赖、领域服务层依赖工具层、组件/页面层依赖服务层。严格禁止底层反向依赖上层。这个规范在代码审查时强制执行比什么花哨的工具都好使。另外如果确实遇到难以立刻拆开的两两依赖我会优先采用动态导入import()把其中一个模块的加载延迟到真正需要的时候。这不影响模块拆分只是改变了加载时机常常能迅速打破运行时的初始化死锁。6. 声明文件.d.ts和模块发布的工程细节从“能用”到“能被别人用好”TypeScript 模块的管理还有一个容易被忽略但非常关键的维度就是如何把模块定义成一个可以被其他项目消费的形式。这里说的“消费”有两层意思第一层是编译期别人 import 你的模块时能不能推导出正确的类型第二层是运行期别人按 import 路径加载时能不能找到真正的实现代码。一个模块如果在类型上声明得非常完美但发布到 npm 之后别人装上无法解析那体验也是灾难性的。6.1 一个模块的 package.json 里应该声明的关键字段发布一个 TypeScript 模块到 npm 时package.json 有几个字段需要专门注意{ name: my-ts-lib, version: 1.0.0, main: ./dist/index.js, module: ./dist/index.mjs, types: ./dist/index.d.ts, exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.mjs, require: ./dist/index.js } }, files: [dist] }mainCommonJS 入口Node.js 老版本会用它。moduleESM 入口支持 ESM 的打包器会优先使用它。types类型声明入口TypeScript 编译器在解析import时会读取这个文件。exports这是 Node.js 在较新版本中支持的“条件导出”写法它把不同类型的入口条件分得更细同时还能限制模块的外部可访问文件路径如果不写exports外部可以访问到dist里任何一个文件写了之后只有exports里列出的路径可以被外部访问。这里有一个经常出现的问题如果你用了exports字段写了条件导出但 tsconfig 里moduleResolution还是旧的node策略TypeScript 可能不会读取exports字段而是直接看main和types。为了解决这个兼容问题TypeScript 4.7 之后需要把moduleResolution设成node16、nodenext或bundler让编译器理解条件导出。否则会出现一种奇怪的现象那个库在 ts-node 环境里类型正常但一打包到 Vite 项目里类型就变成any或者直接报找不到模块。6.2 构建产物声明文件是如何生成和校验的要让 TypeScript 在编译时生成.d.ts声明文件需要在 tsconfig 里开启declaration选项{ compilerOptions: { declaration: true, declarationMap: true, emitDeclarationOnly: true } }declarationMap是一个容易被忽略但非常实用的选项它生成的.d.ts.map文件可以让使用者在 IDE 里直接跳转到源码位置而不是只看到.d.ts里的声明这对调试和分析问题很有帮助。另外我还建议在发布前做一次“类型自检”。一个常见的隐患是你的源码里某些类型依赖了开发环境的依赖比如types/node里的Buffer、ProcessEnv等但实际使用者在装你的库时并没有安装types/node于是它的项目里会冒出大量“找不到名称 Buffer”的类型报错。解决办法是在发布声明文件时尽量把依赖的第三方类型也一并声明进去或者在package.json的peerDependencies里注明需要的类型依赖。更稳妥的做法是把模块内使用的所有类型都显式导出避免在.d.ts里隐式引用到用户项目里不存在的全局类型。7. 实际项目里我总结的模块拆分铁律和建议的起点配置模块化是个听起来原则明确、实践起来却极容易跑偏的话题。我在多个项目里反复调整之后沉淀下来几条自己做事时一定会遵守的铁律。这些不是 TypeScript 的官方规范而是基于大量踩坑之后的经验判断。7.1 四条模块拆分原则建议贴到团队共享文档里原则一文件导出内容尽量保持单一职责。这不是说一个文件只能导出一个函数而是说这个文件里的所有导出应该围绕同一个主题。比如format.ts里就放格式化相关的函数不要混入日期计算和 DOM 操作。如果文件导出太多要么是业务正在膨胀要么是拆分的粒度不对。原则二跨模块的共享类型收口到有限的公共出口。如果很多模块都需要User类型我建议把User放到领域根模块里显式导出而不是在各自的子模块里重复定义。重复定义短时间内没问题但一旦后端的返回结构改了你需要在五个地方同步修改忘了其中一个就会产生隐蔽的类型不一致。原则三模块之间向上依赖禁止兄弟互引。具体说是页面可以依赖领域服务领域服务可以依赖工具函数但两个业务模块之间不要互相 import 对方的内部实现。如果它们需要共享逻辑那就把共享逻辑下沉到更底层的新模块。这样做的好处是任何一个模块的删除或替换都不会牵扯到它的同级兄弟。原则四入口文件尽量只做“组装”和“再导出”。组件库的index.ts就是典型例子它不应该包含业务逻辑而应该把子模块的 API 统一收集并导出对外提供一把“钥匙串”。这样用户只需要从入口导入不需要关心内部目录结构。这对维护体验的提升是非常明显的。7.2 一份可以直接落地的起点配置如果你正在新起一个 TypeScript 项目可以按下面这份配置起步它兼顾了现代打包器生态和 Node.js 的兼容性环境上不会一开始就埋雷{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: bundler, strict: true, declaration: true, declarationMap: true, sourceMap: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true, isolatedModules: true, verbatimModuleSyntax: true, noUncheckedIndexedAccess: true, paths: { /*: [./src/*] } }, include: [src], exclude: [node_modules, dist] }几个选项值得单独说说。esModuleInterop开了之后import React from react这种默认导入才合法否则你会被迫写import * as React from react。verbatimModuleSyntax开了之后编译器会强制执行“类型导入用import type”的规范这对代码风格统一很有帮助但也意味着你需要在代码里养成好习惯。noUncheckedIndexedAccess比较严格数组下标访问会带上undefined在风格上比较适合对数据访问安全要求高的项目。strict一定要开这是 TypeScript 类型检查的基石我见过不少项目为了“快速启动”关掉了strict结果后面大量类型问题积累到几乎无法修复。还有一个小建议初始化项目时直接把declaration相关的选项都打开。哪怕你觉得自己不会被别人引用生成声明文件也是有好处的——它会在编译阶段强制编译器更严格地检查类型推断的健全性因为类型声明一旦生成就相当于把你的模块的“对外契约”固定了下来编译器必须以类型声明为基准做一次校验。很多类型问题在“只编译 JS”的模式下不会暴露开了声明生成反而更容易被揪出来。最后说一下个人的一点小体会。TypeScript 模块化这门功课学起来不难难的是在真实项目里面对不断膨胀的依赖关系时还能保持克制和清晰。模块拆分的本质不是代码的组织形式而是团队协作时责任边界的划分。你划清楚了后续的测试、重构、性能优化都有明确的作用域你划不清哪怕语法用得再花哨代码的复杂度也会像滚雪球一样越来越大。动手写代码之前先想清楚模块的边界这比任何高级技巧都重要。