TypeScript编译配置详解 | 面试准备

▌ 技术引导
TypeScript 编译配置的深度理解是工程化落地的关键，真实项目中 90% 的构建问题都源于 tsconfig.json 的设置不当。我见过太多人因为忽略模块解析策略，导致项目初始化时模块找不到。在实际工作中，配置中 resolution 的引用路径和 moduleResolution 模式必须对齐，否则会引发一系列连锁反应。还有一件事特别容易被忽略——typeRoots 和 declarationDir 的搭配，它直接决定了类型声明文件的生成位置和查找范围。如果你使用 ts-node 做开发，必须在 tsconfig.json 中配置 compilerOptions 的 module 为 esnext 并且 target 为 es2020，否则 esm 模块无法正确解析。另外，exclude 和 include 配置项的边界设定也决定了构建效率，我见过一个项目因为没排除 node_modules，导致编译时间翻倍。最终，一个清晰、标准化的 tsconfig.json 不仅能提升构建效率，也能让团队协作更顺畅。

▌ 技术参考

一 TypeScript 编译配置不仅是 tsconfig.json 文件，它还涉及 ts-node、tsc、webpack 等工具的配合使用。模块解析模式对项目结构影响深远，比如在 monorepo 环境下，使用 moduleResolution: 'node' 会带来额外的路径问题，而 moduleResolution: 'classic' 则更适合传统项目，但会丧失模块路径的灵活性。typeRoots 配置项可以指定类型声明文件的目录，通常设置为 ['./node_modules/@types', './typings'] 能覆盖大多数情况，但如果你使用自定义类型声明，必须确保声明文件的路径与 typeRoots 一致，否则 TypeScript 会完全忽略类型信息。我见过太多项目因为没配置 typeRoots，导致类型提示失效，开发体验极差。

二 tsconfig.json 的 compilerOptions 部分决定了编译行为，其中 module 和 target 是必须关注的两个字段。如果你使用 esm 模块，必须设置 module: 'ESNext' 并且 target: 'ES2020'，否则模块导入导出会出错。有时候为了兼容旧项目，会保留 module: 'commonjs'，但这样会降低代码的现代性，增加构建脚本的复杂度。另外，target 设置为 es2020 后，某些语法如 BigInt、Promise.allSettled 等才能被正常编译，否则会报错。我之前在使用 ts-node 时，因为没设置 target，导致项目运行时报出语法错误，调试花了整整两天时间。

三 编译器选项中的 strict 模式是开发中必不可少的配置，它包含 strictNullChecks、strictFunctionTypes、strictBindCallApply 等子项。启用 strict 模式能显著减少 runtime 的 null 异常，但也会让部分类型推断失效，需要配合类型断言或者类型守卫来处理。比如在处理第三方库时，如果库的类型声明文件不完整，启用 strictNullChecks 会导致大量错误，这时候可以选择性地关闭某些 strict 子项。不过，我见过有些团队为了追求代码质量，会将 strict 模式强制开启，并通过类型声明文件的完善来规避问题，这种方法虽然更严格，但长期来看能提升代码健壮性。

四 编译输出路径和 sourcemap 配置对调试至关重要。outputDir 通常设置为 dist 或 build，但如果你使用 tsconfig-paths 或 jest，可能需要额外的配置来确保模块解析正确。sourcemap 的设置可以通过 sourceMap: true 来开启，但生产环境一般建议关闭，因为生成 sourcemap 会增加构建时间。另外，我可以告诉你一个细节，当使用 --module esnext 时，sourcemap 生成的路径会变成 dist/xxx.js.map，这个路径必须与打包工具的配置对齐，否则调试时会找不到对应源码。我之前在使用 webpack 时，因为没正确设置 module 的 sourcemap 选项，导致调试器无法正确映射代码，浪费了大量时间。

五 在大型项目中，tsconfig.json 的 exclude 和 include 配置会影响构建性能。排除 node_modules 和 test 目录是最常见的做法，但有时候项目结构复杂，需要更精细的控制。比如在使用 monorepo 管理时，exclude 配置项可以设置为 ['/.spec.ts', 'node_modules', 'build', 'dist']，这样能确保测试文件和构建目录不会被误编译。include 通常设置为 ['./src//']，但如果项目有多个源码目录，必须将它们全部列出来，否则编译会遗漏某些文件。我在一个项目中因为 include 设置错误，导致部分业务模块无法被编译，最终排查出问题花了三个小时。

六 编译配置中的 resolveJsonModule 和 esModuleInterop 是两个容易被忽略但非常关键的选项。resolveJsonModule 主要用于导入 JSON 文件，如果项目需要读取配置文件或者定义常量，必须开启它，否则会报错。esModuleInterop 的作用是让 CommonJS 模块能与 ES 模块兼容，特别是在使用第三方库时，如果不启用，可能会遇到模块导出风格冲突的问题。我之前在使用一个 npm 包时，因为没配置 esModuleInterop，导致模块的 default 导出无法被正确识别，最终只能手动修改导入语句才能通过。

七 配置中的 lib 和 esmodule 等选项对兼容性有很大影响。lib 是 TypeScript 编译器自带的标准库，比如 'es2020'、'dom' 等，如果你项目中用到 Promise、Symbol 等特性，必须确保 lib 包含这些模块。否则，TypeScript 会报出找不到模块的错误。同时，esModule 是一个关键的编译模式，它决定模块是否以 ES 模块格式导出。如果使用模块打包工具，比如 vite 或 rollup，必须确保 esModule 设置为 true，否则模块打包会失败。我之前在配置 vite 时，不小心把 esModule 设置为 false，导致打包后的模块无法被正确加载，项目无法运行。

八 在开发阶段，使用 ts-node 是一种高效手段，但它的配置和常规编译存在差异。ts-node 的配置文件通常位于 tsconfig.json，但需要额外设置 compilerOptions 的 module 为 'ESNext'，并且 target 设置为 'ES2020'，否则会报错。另外，ts-node 不支持某些高级编译选项，如 target: 'es5' 或 module: 'commonjs'，如果需要兼容旧环境，建议使用 tsc 预编译。我在一个团队中发现，有人将 ts-node 的配置和常规 tsc 混淆，导致开发时没问题，但上线时却出现模块错误，最终排查出 ts-node 的配置没有正确同步。

九 项目中如果使用了 tsconfig-paths，必须在 tsconfig.json 的 compilerOptions 中配置 paths 字段，同时确保 package.json 的 type 字段为 module。paths 可以定义别名，比如 'utils' 指向 './src/utils/index.ts'，但必须配合 baseUrl 使用，否则路径解析会出问题。我见过一些项目因为没配置 baseUrl，导致别名无法生效，进而出现模块找不到的错误。另外，tsconfig-paths 的使用要视项目结构而定，如果项目是单体结构，建议使用相对路径，而不是别名，这样更稳定。

十 在构建工具中，TypeScript 的配置通常需要与 webpack、vite、rollup 等工具配合。比如在使用 vite，需要在配置文件中引入 tsconfig-paths 插件，同时设置 tsconfigPath: './tsconfig.json'。在 rollup 中，如果使用 typescript 插件，必须确保 tsconfig.json 中的 compilerOptions 包含 module 和 target，并且设置 outDir 为 dist。我之前在使用 rollup 时，因为没有正确设置 outDir，导致输出目录混乱，项目文件全部堆在了根目录，最后不得不手动清理。

十一 exportDefault 是一个常见的配置项，尤其是在使用 ts-node 时，它决定了模块是否导出默认值。如果不设置 exportDefault: true，某些模块的导出方式会出错，特别是在使用 ES 模块的情况下。此外，在使用 Jest 进行测试时，必须确保 tsconfig.json 中的 moduleResolution 设置为 node，并且 module 设置为 esnext，否则测试文件无法被正确加载。我见过一个项目因为 exportDefault 设置错误，导致测试无法运行，最终发现是 moduleResolution 的问题。

十二 编译配置中的 skipLibCheck 是一个提升构建效率的选项，尤其在第三方库较多的项目中。它会跳过对标准库的类型检查，避免因为第三方库的类型文件更新导致编译时间变长。不过，开启 skipLibCheck 会带来一个隐藏问题：你可能无法及时发现第三方库类型声明中的错误。我之前在开发中因为关闭了 skipLibCheck，导致某个第三方库的类型声明文件存在 bug，编译时提示错误，但实际运行时才暴露问题，增加了调试成本。

十三 在多项目结构中，tsconfig.json 的配置可能需要多个层级。比如在 monorepo 项目中，可以创建一个 root tsconfig.json 并使用 extends 指向子模块的配置。这样能减少重复配置，提升维护效率。子模块的 tsconfig.json 可以通过 compilerOptions 的 moduleResolution: 'node' 来解决模块路径问题，同时设置 paths 字段来定义别名。我见过一个 monorepo 项目，因为没正确配置 extends，导致项目结构混乱，所有模块都指向了同一个根目录，最终不得不重新梳理配置结构。

十四 在 CI/CD 环境中，TypeScript 编译的配置必须与本地开发保持一致，否则会出现环境差异。比如在 GitHub Actions 中，需要确保 node 版本足够新，并且 TypeScript 编译命令使用 tsc --build --clean，这样能避免缓存导致的编译错误。另外，在使用 Docker 部署时，要确保 tsconfig.json 的路径正确，避免因为容器挂载问题导致编译失败。我之前在部署时遇到过 tsconfig.json 被错误覆盖的问题，最终发现是 Dockerfile 挂载路径没有正确设置。

十五 在使用 TypeScript 的类型声明文件时，必须确保 types 字段正确配置，否则类型提示和自动补全会失效。common types 是 TypeScript 自带的类型声明，比如 'esnext'、'dom' 等，如果项目中使用了第三方库，比如 axios，需要确保 'axios' 被包含在 types 数组中。有时候使用自定义类型声明，比如通过 declare module 的方式定义全局类型，但如果不设置 typeRoots，TypeScript 会忽略这些声明。我在一个项目中因为没配置 typeRoots，导致自定义类型提示无法生效，开发效率大大降低。