第 10 章:模块与 tsconfig 工程化
前面都在一个文件里写代码。真实项目有几十上百个文件,模块系统决定它们怎么互相引用,
tsconfig决定编译器怎么理解这些引用。
学习目标
- 分清命名导出与默认导出,知道团队为什么更推荐命名导出
- 理解 ESM 与 CommonJS 的本质差异,会用
package.json与新后缀控制模块类型 - 掌握三种常见的
module+moduleResolution组合,知道各自对应什么运行环境 - 会配置路径别名,并知道为什么光配
tsconfig不够 - 能逐个解释
strict家族里最常拦你的几项
10.1 导出与导入
命名导出(推荐)
// utils/format.ts
export function formatPrice(amount: number): string {
return `¥${amount.toFixed(2)}`
}
export const TAX_RATE = 0.13// main.ts
import { formatPrice, TAX_RATE } from './utils/format'导入名必须和导出名一致(可以用 as 改名)。好处是"找引用"特别准,改名时编辑器能可靠地批量更新。
默认导出
// logger.ts
export default function logger(msg: string) {
console.log(msg)
}// main.ts
import anything from './logger' // 名字随便起默认导出的问题是导入方可以随便起名:同一个模块,A 文件叫 logger,B 文件叫 log,C 文件叫 myLogger。搜索、重构、读代码都变困难。
团队约定
| 场景 | 建议 |
|---|---|
| 工具函数、类型、常量 | 命名导出 |
| 一个文件只导出一个主体(如 React 组件) | 默认导出也行,但团队统一 |
| 需要整体命名空间 | import * as utils from './utils' |
一句实用建议:新项目统一用命名导出。默认导出除了少打几个字,几乎没有优势,而在大型项目里"搜不到、改不动"的代价很大。
10.2 只导入类型:import type
import type { User } from './types'
import { createUser } from './service'import type 明确表示"这个导入只用于类型标注,编译后完全删除"。它有两个好处:
- 避免循环依赖:类型导入不产生运行时引用,
A和B互相引用类型也不会形成环; - 打包更干净:类型导入不会被误打进产物。
配合 verbatimModuleSyntax: true(TS 5.0 引入),编译器会严格区分"类型导入"和"值导入",写混了直接报错。这个选项适合与"单文件转译"工具(esbuild、SWC)配合的项目,因为那些工具无法判断某个导入到底是不是类型。
import type { Order } from './types' // 只用于类型
import { createOrder } from './order' // 运行时真的要用判断标准很简单:导入的东西只在
: Type位置出现 → 用import type。
10.3 ESM 与 CommonJS
JavaScript 有两套模块系统,这不是 TS 造成的,是历史遗留。
| 维度 | CommonJS(CJS) | ES Modules(ESM) |
|---|---|---|
| 语法 | require() / module.exports | import / export |
| 加载方式 | 同步、运行时 | 异步、静态分析 |
顶层 await | 不支持 | 支持 |
| 静态分析 / tree-shaking | 难 | 好 |
| 典型环境 | 老 Node 项目 | 现代 Node、浏览器、打包器 |
| 文件后缀 | .js(默认) | .mjs,或 .js + "type": "module" |
怎么指定一个文件是 ESM
两种方式:
package.json里写"type": "module",该目录下所有.js都按 ESM 解释;- 用后缀强制:
.mjs一定是 ESM,.cjs一定是 CJS。
TS 对应的源码后缀是 .mts 和 .cts,编译后分别产出 .mjs 和 .cjs。
互操作
ESM 可以 import CJS 模块(Node 会自动包装),反过来 CJS 不能直接 require ESM(只能用动态 import())。这就是为什么"从 CJS 迁到 ESM"通常比反向容易。
esModuleInterop: true 解决的是另一件事:让 TS 允许 import express from 'express' 这种写法去引 CJS 模块(CJS 没有默认导出)。几乎所有项目都开着它。
10.4 三种常见的 tsconfig 组合
组合一:Node + CommonJS(最省事)
{
"compilerOptions": {
"target": "ES2022",
"module": "commonjs",
"moduleResolution": "node",
"esModuleInterop": true,
"strict": true,
"outDir": "dist"
}
}适合:传统 Node 服务、脚本、不想折腾模块类型的小项目。import 语法照写,编译后自动变成 require。
组合二:Node + ESM(现代 Node)
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"outDir": "dist"
}
}配 package.json 的 "type": "module"。两条硬规则:
- 相对导入必须写扩展名,而且写编译后的
.js; - 引入 CJS 包时,
import的行为由 Node 决定,有时需要createRequire。
import { helper } from './helper.js' // 源文件是 helper.ts组合三:打包器(Vite / webpack / Next.js)
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"noEmit": true,
"strict": true
}
}Bundler 模式的特点是:允许省略扩展名,允许 package.json 的 exports 字段按浏览器条件解析,因为最终由打包器负责拼装。TS 在这里只做类型检查(noEmit: true),产物交给 Vite / esbuild。
这三套组合不要混。最常见的翻车是:
module: "ESNext"配moduleResolution: "node",然后抱怨某些包的子路径导入报错。module和moduleResolution必须成对选。
10.5 路径别名
深层相对路径很难看:
import { formatPrice } from '../../../utils/format'改成别名:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@utils/*": ["src/utils/*"]
}
}
}import { formatPrice } from '@utils/format'但只改 tsconfig 是不够的。 tsconfig.paths 只是告诉编译器"去哪里找类型",运行时(Node)和打包器并不认这个别名。还要同步配一处:
| 环境 | 需要配什么 |
|---|---|
| Vite | resolve.alias |
| webpack | resolve.alias |
| tsx / ts-node | tsconfig-paths 或 tsx 的自动支持 |
纯 node dist/ | 需要打包时替换,或用 tsc-alias 后处理 |
// vite.config.ts
import { defineConfig } from 'vite'
import path from 'node:path'
export default defineConfig({
resolve: {
alias: {
'@': path.resolve(__dirname, 'src')
}
}
})这个"两处都要配"的坑几乎每个人都会踩一次。记住:tsconfig.paths 管类型,打包器 alias 管运行时。
10.6 strict 家族:谁在拦你
strict: true 是一组开关的集合。逐个打开也可以,但建议先整体开,再针对性关。
| 选项 | 作用 | 常见报错 |
|---|---|---|
strictNullChecks | null/undefined 不能赋给其他类型 | Type 'null' is not assignable to type 'string' |
noImplicitAny | 推断不出类型时报错,不静默变 any | Parameter 'x' implicitly has an 'any' type |
strictFunctionTypes | 函数参数逆变检查 | Type '(d: Dog) => void' is not assignable to... |
strictPropertyInitialization | 类字段必须在构造函数初始化 | Property 'x' has no initializer |
strictBindCallApply | bind/call/apply 参数类型检查 | 参数不匹配 |
noImplicitThis | this 必须有明确类型 | 'this' implicitly has type 'any' |
alwaysStrict | 产物加 "use strict" | — |
useUnknownInCatchVariables | catch 变量是 unknown | 访问 err.message 报错 |
几个"不开在 strict 里,但强烈建议开"的:
{
"compilerOptions": {
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"exactOptionalPropertyTypes": true
}
}noUncheckedIndexedAccess:arr[i]变成T | undefined,逼你判空。这个选项会让老项目冒出一堆错误,但它是"数组越界"这类 bug 的克星。exactOptionalPropertyTypes:区分"属性不存在"和"属性存在但值是 undefined",对 API 序列化很严格,按需开。noUnusedLocals/noUnusedParameters:清掉没用的变量,CI 里很有效。
10.7 编译与打包不是一回事
| 工具 | 干什么 | 产出 |
|---|---|---|
tsc | 类型检查 + 逐文件转译 | 目录结构的 .js + .d.ts |
| esbuild / SWC | 只转译,不检查类型 | 快,但类型错误不管 |
| Vite / webpack / Rollup | 打包、拆分、压缩、处理资源 | 单个或多个 bundle |
tsc --noEmit | 只检查类型 | 无产物 |
常见分工:
// package.json
{
"scripts": {
"dev": "vite",
"build": "tsc --noEmit && vite build",
"typecheck": "tsc --noEmit"
}
}tsc 不做打包(早期的 outFile 只支持 AMD,已不推荐)。"编译"和"打包"是两件事,现代项目通常让 tsc 只管类型,打包交给专门的工具。
如果要发布一个库给别人用,还需要生成声明文件:
{
"compilerOptions": {
"declaration": true,
"declarationMap": true,
"emitDeclarationOnly": false
}
}10.8 常见误区
误区一:module 和 moduleResolution 随便配。 → 必须成对:commonjs + node、NodeNext + NodeNext、ESNext + Bundler。混搭会出各种"找不到模块"。
误区二:配了 paths 就能在 Node 里用别名。 → 不能。paths 只影响类型解析,运行时需要打包器 alias 或 tsconfig-paths。
误区三:默认导出和命名导出只是写法不同。 → 默认导出让导入方自由命名,直接损害"查找引用"和重构可靠性。
误区四:esModuleInterop 是给 ESM 项目用的。 → 它主要解决"用 import 语法引 CJS 模块"的兼容问题,CJS 项目同样需要。
误区五:tsc 能打包。 → 不能(outFile 已废弃)。打包用 Vite / webpack / Rollup。
误区六:类型导入忘了写 import type,反正会被擦除。 → 单文件转译工具无法判断它是类型还是值,可能保留成运行时导入,导致"模块不存在"的运行时错误。养成写 import type 的习惯。
本章小结
| 要点 | 说明 |
|---|---|
| 导出方式 | 优先命名导出;默认导出损失可搜索性与重构可靠性 |
| 类型导入 | import type 编译后删除,避免循环依赖与多余打包 |
| ESM vs CJS | ESM 静态、异步、支持顶层 await;CJS 同步 |
| 三种组合 | Node+CJS、Node+ESM(NodeNext)、打包器(ESNext+Bundler) |
| ESM 后缀规则 | NodeNext 下相对导入写 .js(编译后后缀) |
| 路径别名 | tsconfig.paths 管类型,打包器 alias 管运行时,两处都要配 |
strict | 一次全开;补充 noUncheckedIndexedAccess、noImplicitOverride |
| 编译 vs 打包 | tsc 管类型与声明文件,打包交给专门工具 |
下一章预告
前面所有类型都是"手写"的。但 TS 的类型本身可以参与运算——从已有类型算出新类型。下一章讲
keyof、索引访问、映射类型和工具类型,学完你就能看懂Omit<User, 'password'>背后的机制。