Skip to content
Lv1TypeScript进度 10 / 14

第 10 章:模块与 tsconfig 工程化 ​

前面都在一个文件里写代码。真实项目有几十上百个文件,模块系统决定它们怎么互相引用,tsconfig 决定编译器怎么理解这些引用。


学习目标 ​

  • 分清命名导出与默认导出,知道团队为什么更推荐命名导出
  • 理解 ESM 与 CommonJS 的本质差异,会用 package.json 与新后缀控制模块类型
  • 掌握三种常见的 module + moduleResolution 组合,知道各自对应什么运行环境
  • 会配置路径别名,并知道为什么光配 tsconfig 不够
  • 能逐个解释 strict 家族里最常拦你的几项

10.1 导出与导入 ​

命名导出(推荐) ​

typescript
// utils/format.ts
export function formatPrice(amount: number): string {
  return `¥${amount.toFixed(2)}`
}

export const TAX_RATE = 0.13
typescript
// main.ts
import { formatPrice, TAX_RATE } from './utils/format'

导入名必须和导出名一致(可以用 as 改名)。好处是"找引用"特别准,改名时编辑器能可靠地批量更新。

默认导出 ​

typescript
// logger.ts
export default function logger(msg: string) {
  console.log(msg)
}
typescript
// main.ts
import anything from './logger'   // 名字随便起

默认导出的问题是导入方可以随便起名:同一个模块,A 文件叫 logger,B 文件叫 log,C 文件叫 myLogger。搜索、重构、读代码都变困难。

团队约定 ​

场景建议
工具函数、类型、常量命名导出
一个文件只导出一个主体(如 React 组件)默认导出也行,但团队统一
需要整体命名空间import * as utils from './utils'

一句实用建议:新项目统一用命名导出。默认导出除了少打几个字,几乎没有优势,而在大型项目里"搜不到、改不动"的代价很大。


10.2 只导入类型:import type ​

typescript
import type { User } from './types'
import { createUser } from './service'

import type 明确表示"这个导入只用于类型标注,编译后完全删除"。它有两个好处:

  1. 避免循环依赖:类型导入不产生运行时引用,A 和 B 互相引用类型也不会形成环;
  2. 打包更干净:类型导入不会被误打进产物。

配合 verbatimModuleSyntax: true(TS 5.0 引入),编译器会严格区分"类型导入"和"值导入",写混了直接报错。这个选项适合与"单文件转译"工具(esbuild、SWC)配合的项目,因为那些工具无法判断某个导入到底是不是类型。

typescript
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.exportsimport / export
加载方式同步、运行时异步、静态分析
顶层 await不支持支持
静态分析 / tree-shaking难好
典型环境老 Node 项目现代 Node、浏览器、打包器
文件后缀.js(默认).mjs,或 .js + "type": "module"

怎么指定一个文件是 ESM ​

两种方式:

  1. package.json 里写 "type": "module",该目录下所有 .js 都按 ESM 解释;
  2. 用后缀强制:.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(最省事) ​

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist"
  }
}

适合:传统 Node 服务、脚本、不想折腾模块类型的小项目。import 语法照写,编译后自动变成 require。

组合二:Node + ESM(现代 Node) ​

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist"
  }
}

配 package.json 的 "type": "module"。两条硬规则:

  • 相对导入必须写扩展名,而且写编译后的 .js;
  • 引入 CJS 包时,import 的行为由 Node 决定,有时需要 createRequire。
typescript
import { helper } from './helper.js'   // 源文件是 helper.ts

组合三:打包器(Vite / webpack / Next.js) ​

json
{
  "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 路径别名 ​

深层相对路径很难看:

typescript
import { formatPrice } from '../../../utils/format'

改成别名:

json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
typescript
import { formatPrice } from '@utils/format'

但只改 tsconfig 是不够的。 tsconfig.paths 只是告诉编译器"去哪里找类型",运行时(Node)和打包器并不认这个别名。还要同步配一处:

环境需要配什么
Viteresolve.alias
webpackresolve.alias
tsx / ts-nodetsconfig-paths 或 tsx 的自动支持
纯 node dist/需要打包时替换,或用 tsc-alias 后处理
typescript
// 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 是一组开关的集合。逐个打开也可以,但建议先整体开,再针对性关。

选项作用常见报错
strictNullChecksnull/undefined 不能赋给其他类型Type 'null' is not assignable to type 'string'
noImplicitAny推断不出类型时报错,不静默变 anyParameter 'x' implicitly has an 'any' type
strictFunctionTypes函数参数逆变检查Type '(d: Dog) => void' is not assignable to...
strictPropertyInitialization类字段必须在构造函数初始化Property 'x' has no initializer
strictBindCallApplybind/call/apply 参数类型检查参数不匹配
noImplicitThisthis 必须有明确类型'this' implicitly has type 'any'
alwaysStrict产物加 "use strict"—
useUnknownInCatchVariablescatch 变量是 unknown访问 err.message 报错

几个"不开在 strict 里,但强烈建议开"的:

json
{
  "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只检查类型无产物

常见分工:

json
// package.json
{
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "typecheck": "tsc --noEmit"
  }
}

tsc 不做打包(早期的 outFile 只支持 AMD,已不推荐)。"编译"和"打包"是两件事,现代项目通常让 tsc 只管类型,打包交给专门的工具。

如果要发布一个库给别人用,还需要生成声明文件:

json
{
  "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 CJSESM 静态、异步、支持顶层 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'> 背后的机制。

👉 第 11 章:类型运算入门

本文阅读--次|全站访问--次|访客--人