16.2 tsconfig.json 核心配置：模块、路径别名、编译目标

在上一节我们了解了如何在 Node.js 项目中运行 TypeScript 代码（ts-node、tsx、tsc 编译），而真正让 TypeScript 与 Node.js 契合度达到生产标准的关键，在于 tsconfig.json 的配置。这个文件决定了 TypeScript 编译器如何理解你的代码、输出什么格式的 JavaScript、以及如何解析模块路径。本节集中讲解与 Node.js 开发最密切的三组核心配置：模块系统、编译目标、路径别名，并结合真实开发场景给出推荐配置。

1. 模块系统配置：module 与 moduleResolution

Node.js 生态中同时存在 CommonJS（require）和 ES Modules（import/export）两套模块规范。TypeScript 通过 module 和 moduleResolution 两个选项来适配这两种范式。

module —— 输出模块格式

module 指定 TypeScript 编译后生成的 JavaScript 使用哪种模块规范。对于 Node.js 项目，常用值有：

• "commonjs"：输出 require / module.exports，兼容绝大多数传统 Node.js 工具和包。
• "nodenext"（或 "node16"）：从 TypeScript 4.7 开始引入，会根据文件的 .mts/.cts 扩展名或 package.json 的 type 字段自动输出对应的 ESM 或 CommonJS。这是目前最贴合现代 Node.js 的选项。
• "esnext" 或 "es2022"：输出 import/export 语法，一般配合前端打包工具使用，在 Node.js 中直接运行需要确保环境支持 ESM。

实践建议：如果你的项目是全新 Node.js 服务，并且准备使用 ESM（package.json 中设置 "type": "module"），推荐直接使用 "module": "nodenext"。如果仍需兼容 CommonJS 生态，可以保守使用 "commonjs"，或采用混合模式（通过文件扩展名区分）。

moduleResolution —— 模块解析策略

moduleResolution 决定了 TypeScript 如何查找模块定义。取值通常与 module 搭配：

• "node"：经典的 Node.js 解析策略，对应 module: "commonjs"。
• "nodenext"（或 "node16"）：支持 exports 字段、条件导出等现代包入口解析，与 module: "nodenext" 配套。
• "bundler"：适用于打包工具（Vite、Webpack）前端项目，不适合纯 Node.js 后端。

配置对应关系：

| 项目类型 | module | moduleResolution |
|---------|--------|------------------|
| Node.js CommonJS 项目 | commonjs | node |
| Node.js ESM 项目 | nodenext | nodenext |
| 前端/打包工具项目 | esnext | bundler |

常见陷阱：很多开发者错误地使用了 module: "esnext" 搭配 moduleResolution: "node"，这会导致模块解析不符合 Node.js 的 ESM 规范（例如无法识别 package.json 的 exports 字段）。统一使用 nodenext 可以避免这些问题。

2. 编译目标配置：target 与 lib

target —— 生成哪个版本的 JavaScript

target 告诉 TypeScript 编译器将代码降级到哪个 ECMAScript 标准的语法。对于 Node.js 后端项目，不需要像前端那样考虑老旧浏览器兼容，设置原则是尽可能匹配当前 Node.js 版本支持的 ES 特性，以获得最佳性能并减少多余转译。

Node.js 各版本对 ES 语法的支持情况（简化）：

• Node.js 18 完全支持 ES2022（含 top-level await、类静态块等）。
• Node.js 20 支持 ES2023。
• Node.js 22 即将支持 ES2024。

因此，如果你的运行环境是 Node.js 18+，可以直接设置 "target": "ES2022"；Node.js 20+ 可设置为 "ES2023"。避免设置为 "ES5" 或 "ES6"，因为那会产生大量冗余的降级代码（如 async/await 被转义为生成器），拖慢运行效率且增大体积。

lib —— 声明可用的运行时 API 类型

lib 指定 TypeScript 在编译时可以使用哪些内置类型的声明。如果不设置，默认会根据 target 自动选择一组默认的 lib（例如 target: "ES2022" 会默认包含 lib.es2022 等）。但 Node.js 环境下，浏览器专用的 DOM 类型并不存在，不应该包含 "DOM"。通常保持默认即可，如果有特殊需求（例如需要使用 "ES2023.sharedmemory"），可以显式覆盖。

如果项目只运行在 Node.js 环境，建议不设置 lib 或仅添加一些必要的如 "ES2022"。也可以安装 @types/node，它提供了 Node.js 专用 API 的类型声明（如 Buffer、process），这通过 types 配置或 /// <reference types="node" /> 生效，但与 lib 无关。

3. 路径别名：baseUrl 与 paths

相对路径引用（../../../utils/format）是项目中最常见的烦恼之一。TypeScript 通过 baseUrl 和 paths 提供了路径别名的编译时支持，可以让代码清爽很多：

"compilerOptions": {
  "baseUrl": "./src",
  "paths": {
    "@/*": ["./*"],
    "@utils/*": ["./utils/*"],
    "@models/*": ["./models/*"]
  }
}

这样，在源码中就可以使用：

import { formatDate } from '@utils/date';
import { User } from '@models/user';

重要提醒：paths 仅在 TypeScript 编译阶段起作用（类型检查和生成 .d.ts），不会改变输出的 JavaScript 代码中的路径！也就是说，tsc 编译后，@utils/date 依然会原样保留在 require 或 import 语句中，而 Node.js 本身并不认识这些别名。因此，你还需要一个运行时路径解析方案才能让程序正常运行。

常用的运行时别名解决方案：

• 使用 ts-node 的 tsconfig-paths：在 tsconfig.json 同级目录下运行 ts-node -r tsconfig-paths/register src/index.ts，它会根据 paths 配置动态重定向模块。
• 使用 tsx：tsx 默认会读取 tsconfig.json 中的 paths 并正确解析，无需额外插件。
• 使用构建工具：如果用 tsup、esbuild 打包，它们通常会把别名转换为相对路径。
• 结合 Node.js 的 import.meta.resolve 或第三方运行时：如 tsimp。

因此，当你决定使用路径别名时，一定要确保运行时环境能够正确解析。否则会出现“编译通过，运行报错”的问题。

生产环境建议：如果最终是编译成 JavaScript 再部署，可以使用 tsc-alias 或 tsconfig-paths 作为构建步骤，将别名路径替换成真实相对路径，从而无需依赖运行时解析。

4. 其他常用且必要的配置

结合实际 Node.js 项目，一个可用的 tsconfig.json 通常会包含以下辅助选项：

• "rootDir": "./src" 和 "outDir": "./dist"：明确源码与输出的目录结构。rootDir 如果不设置，可能会导致输出目录保留原始目录层级（比如 src/ 被视为根目录，输出时不会包含 src 前缀，可能引起混淆）。
• "strict": true：开启所有严格的类型检查，包括 strictNullChecks、noImplicitAny 等。这是写出健壮 Node.js 代码的前提。
• "esModuleInterop": true：允许用 import express from 'express' 的方式导入 CommonJS 模块，并添加 __importDefault 辅助函数。与 allowSyntheticDefaultImports 配合使用，兼容性极好。
• "skipLibCheck": true：跳过对 node_modules 中 .d.ts 文件的类型检查，显著加快编译速度，并避免某些第三方类型声明问题导致编译失败。
• "forceConsistentCasingInFileNames": true：强制文件名大小写一致，避免在 macOS 和 Linux 之间部署时出现模块找不到的错误。
• "resolveJsonModule": true：允许直接 import JSON 文件，并自动推导类型。
• "declaration": true：生成 .d.ts 类型声明文件，适用于库的开发。
• "sourceMap": true：生成 Source Map，方便调试。

5. 一个面向 Node.js 20 的 tsconfig.json 示例

假设我们的项目是一个使用 Express 的 REST API 服务，源码位于 src/，编译输出到 dist/，并且使用 ESM（"type": "module" 在 package.json 中声明）。

{
  "compilerOptions": {
    /* 基础选项 */
    "target": "ES2023",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["ES2023"],
    
    /* 输出设置 */
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,
    
    /* 路径别名 */
    "baseUrl": "./src",
    "paths": {
      "@/*": ["./*"],
      "@utils/*": ["./utils/*"],
      "@middlewares/*": ["./middlewares/*"]
    },
    
    /* 严格检查 */
    "strict": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    
    /* 编译性能与兼容 */
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    
    /* 其他 */
    "allowJs": false,
    "isolatedModules": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

这个配置兼顾了现代 Node.js 特性、路径别名便利性以及严格类型安全，可以直接用于大多数中大型项目。团队成员的 IDE 也能根据此配置提供精确的智能提示。

小结

tsconfig.json 是 TypeScript 与 Node.js 桥梁的蓝图。模块系统的选择决定了代码如何组织，编译目标决定了 JavaScript 的运行效率，路径别名则影响代码的可维护性。这三项配置加上一些实用的辅助选项，就构成了 Node.js 项目的坚实基础。记住两个关键原则：

• 让 TypeScript 产出与你的 Node.js 环境最匹配的代码，而不是与浏览器兼容。
• 路径别名需要运行时配合，团队必须在本地开发和生产部署阶段统一解析方案。

掌握这些配置，不仅能减少因为配置混乱引发的“代码与运行不一致”的问题，还能显著提升开发体验和长期维护效率。