【项目配置文件】TypeScript 编译器的配置文件

前言

之前不是出了一篇项目搭建的笔记吗？都放在一篇里的话，内容有点太多，太杂了，后面相关的就单开一个。
等最后写得差不多了，再给每一个相关联的笔记做个链接跳转的目录，方便大家浏览。
（在此之前就需要大家等待一下，或者到我的专栏里找到 后台管理系统–学习笔记 中，找博客啦）

这里主要分享一下关于 tsconfig.json 文件、 tsconfig.app.json 文件、tsconfig.node.json 文件、基础配置。

一、 tsconfig.json 文件

（这里放一个坑位，详细配置的博客链接，以后会补上）

1.项目配置的中心枢纽

• 定义编译规则
  • 它是TypeScript编译器的配置文件，用于指定如何将TypeScript代码编译成JavaScript代码。
  • 例如，它可以定义编译的目标版本（如编译为ES5、ES6等），这决定了生成的JavaScript代码的语法特性，以适应不同的运行环境（如旧版本浏览器或现代浏览器、Node.js环境等）。
• 模块解析设置
  • 确定模块的解析方式，如使用node模块解析策略（适用于Node.js环境下的模块加载方式）或其他自定义的模块解析策略。
  • 这对于正确处理项目中的模块导入和导出非常关键，确保在编译过程中能够准确找到所需的模块文件。

2.文件包含与排除管理

• 指定编译范围
  • 通过include和exclude属性，可以精确地指定哪些文件或文件夹应该被包含在编译范围内，哪些应该被排除。
  • 这有助于优化编译过程，避免编译不必要的文件。
  • 例如，可以将测试文件（通常位于test文件夹）排除在编译范围之外，只编译实际构成应用程序的源代码文件。

3.编译选项定制

• 类型检查设置
  • 配置类型检查的严格程度。
  • 可以设置为严格模式（strict），在这种模式下，TypeScript会对类型进行更细致的检查，有助于发现更多潜在的类型错误，提高代码质量。
  • 也可以根据项目需求调整具体的类型检查选项，如是否对null和void类型进行严格检查等。
• 源映射生成
  • 确定是否生成源映射（sourceMap）文件。
  • 源映射文件允许在调试时将编译后的JavaScript代码映射回原始的TypeScript代码，这对于在浏览器或其他运行环境中调试TypeScript代码非常有用，使开发者能够在熟悉的TypeScript代码结构上进行调试操作。

4.项目结构与依赖管理的体现

• 路径映射
  • 可以定义路径映射（paths）选项，用于简化模块导入路径。
  • 当项目结构较为复杂时，通过路径映射可以将较长的相对或绝对模块导入路径简化为更易于管理和阅读的形式，同时也有助于提高代码的可维护性。
• 与外部库的交互
  • 如果项目依赖于外部的TypeScript库，tsconfig.json可以配置如何处理这些库的类型定义文件（.d.ts）。
  • 可以通过types属性指定需要包含的类型定义文件，确保在编译过程中能够正确识别和使用外部库的类型信息。

5.配置示例

以下是一个较为常见的tsconfig.json文件示例，可以根据实际项目需求进行调整：

{
  "compilerOptions": {
    "target": "es5", // 编译目标为ES5版本
    "module": "commonjs", // 使用CommonJS模块系统
    "sourceMap": true, // 生成源映射文件，方便调试
    "strict": true, // 启用严格模式，进行更严格的类型检查
    "esModuleInterop": true, // 允许在CommonJS和ES模块之间互操作
    "skipLibCheck": true, // 跳过对声明文件（.d.ts）的类型检查
    "forceConsistentCasingInFileNames": true // 强制文件名大小写一致
  },
  "include": [
    "src/**/*" // 包含src目录下的所有文件
  ],
  "exclude": [
    "node_modules", // 排除node_modules目录
    "dist" // 排除dist目录（通常是编译输出目录）
  ]
}

这个示例配置具有以下特点：

• 目标版本：
  • 将TypeScript代码编译为ES5版本的JavaScript代码，以确保在广泛的环境中具有较好的兼容性，尤其是一些旧版本的浏览器。
• 模块系统：
  • 选择commonjs模块系统，这在Node.js环境中非常常用，也便于与许多依赖库和工具进行交互。如果你的项目主要运行在浏览器环境且使用模块加载器（如Webpack等），也可以考虑其他模块格式（如esm）。
• 源映射：
  • 生成源映射文件，这对于在开发过程中调试代码非常有帮助。当在浏览器中调试时，可以通过源映射将编译后的JavaScript代码映射回原始的TypeScript代码，使得调试信息更加准确和易于理解。
• 严格模式：
  • 启用严格模式可以提高代码质量，通过更严格的类型检查发现潜在的错误。例如，它会检查变量的初始化、函数参数的类型匹配等，有助于编写更健壮的代码。
• 模块互操作和跳过类型检查：
  • esModuleInterop设置允许在CommonJS和ES模块之间更顺畅地互操作，方便在项目中使用不同类型的模块。skipLibCheck选项在一些情况下可以提高编译速度，特别是当项目中引用了大量的第三方声明文件且你确定这些声明文件的准确性时。
• 文件名大小写一致：
  • forceConsistentCasingInFileNames确保在不同操作系统上对文件名的大小写处理一致，避免因大小写问题导致的文件引用错误，特别是在团队协作或跨平台开发中很有用。
• 包含：
  • 指示编译器包含src目录下的所有文件。通常，src目录是存放项目源代码的主要位置，这种配置可以方便地将整个项目的源代码纳入编译范围。
• 排除：
  • 排除node_modules目录是常见的做法，因为这个目录通常包含项目的第三方依赖，这些依赖的源代码不需要被编译。同时，排除dist目录（如果它是编译输出目录）可以避免重复编译已经生成的文件，提高编译效率。

【注意】
以上示例只是一个基础的配置模板，实际项目中的tsconfig.json可能会根据项目的具体需求、使用的框架和工具等因素进行更复杂的配置。
例如，如果项目使用了TypeScript的装饰器，可能需要启用相关的实验性特性；
如果是一个React项目，可能需要针对React的类型定义和模块解析进行特殊配置。

二、tsconfig.app.json 文件

tsconfig.json 文件是 TypeScript 编译器的配置文件，TypeScript 编译器可以根据它的规则来对代码进行编译。
（这里放一个坑位，详细配置的博客链接，以后会补上）

1. 项目特定配置

• 在基于TypeScript 的项目中，尤其是像 Angular 这样的框架项目中，tsconfig.app.json是针对应用程序（app）部分特定的 TypeScript 配置文件。
• 它与项目根目录下的tsconfig.json文件协同工作。
• tsconfig.json通常包含适用于整个项目的基础 TypeScript 配置，而tsconfig.app.json可以对应用程序相关的 TypeScript 编译进行更细致的调整。

2. 编译选项定制

• 例如，它可以指定不同的编译目标（target），像将 TypeScript 代码编译成 ES5 或者 ES6 等不同的 JavaScript 版本，以适应不同的浏览器或运行环境。
• 可以定义模块解析方式（moduleResolution），确定如何解析模块引用，是采用node风格的模块解析还是其他方式。
• 还能设置路径映射（paths），这在处理模块导入路径较长或者需要自定义模块路径时非常有用，通过设置路径映射，可以简化模块导入的路径表示。

3. 包含和排除文件

• tsconfig.app.json可以指定哪些文件或目录需要被包含（include）在TypeScript编译范围内，以及哪些文件或目录需要被排除（exclude）。
• 这有助于优化编译过程，只处理与应用程序相关的文件，避免不必要的编译操作。
• 例如，可以排除测试文件目录或者只包含特定的源文件目录。

4. 与构建系统集成

• 在项目构建过程中，构建工具（如 Webpack 等在与 TypeScript 集成时）会根据tsconfig.app.json中的配置来正确地编译应用程序的 TypeScript 代码。
• 它确保构建出来的 JavaScript 代码符合项目在运行时环境的要求，并且遵循了特定于应用程序部分的 TypeScript 设置。

5. 配置示例

以下是一个tsconfig.app.json文件的示例，可以根据自己的项目需求进行修改和调整：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist/app",
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@services/*": ["src/services/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx"
  ],
  "exclude": [
    "node_modules",
    "src/test/**/*.ts"
  ]
}

• "extends": "./tsconfig.json"：表示继承项目根目录下的tsconfig.json文件的配置，这样可以共享一些通用的配置设置，同时在tsconfig.app.json中进行特定于应用的覆盖或扩展。
• "compilerOptions"部分：
  • "outDir": "./dist/app"：指定编译后的输出目录为dist/app，将应用的编译结果放在这里。
  • "baseUrl": "."：设置基础目录，用于解析相对模块路径。
  • "paths"：定义了路径映射，使得在代码中可以使用更简洁的路径来引用模块。例如，@components/*会被映射到src/components/*，这样在导入组件时可以更方便，比如import { MyComponent } from '@components/MyComponent';。
• "include"：指定了需要被TypeScript编译器处理的文件路径模式，这里包括了src目录下的所有.ts和.tsx文件（通常是TypeScript和TypeScript React文件）。
• "exclude"：排除了node_modules目录（不需要编译第三方模块的源代码）和src/test目录下的测试文件（假设测试文件不需要包含在应用的正常编译中）。

【注意】实际的配置可能会因项目的结构、使用的框架和工具等因素而有所不同。一次性配置不完全，可以根据后期项目的需求添加配置。
例如：

• 如果项目没有使用React（即没有.tsx文件），可以相应地调整include的内容。
• 如果项目有不同的目录结构或特殊的编译需求，也需要对paths、outDir等配置进行适当修改。

三、tsconfig.node.json 文件

（这里放一个坑位，详细配置的博客链接，以后会补上）

1. 特定于Node.js环境的配置

• 在TypeScript项目中，tsconfig.node.json主要用于为Node.js环境下的TypeScript编译提供特定的配置。
• 它与tsconfig.json协同工作，tsconfig.json通常包含整个项目通用的TypeScript编译设置，而tsconfig.node.json则专注于与Node.js相关的部分。

2. 模块解析调整

• 针对Node.js的模块解析方式进行配置。
• Node.js有自己独特的模块查找和加载机制，例如，通过node_modules目录查找模块等。
• tsconfig.node.json中的compilerOptions可以定义适合Node.js环境的模块解析策略（如moduleResolution设置为node），确保在编译过程中能够准确地找到和处理Node.js项目中的模块引用。

3. 编译目标与环境适配

• 确定适合Node.js运行环境的编译目标（target）。
• Node.js对不同版本的JavaScript有不同的支持情况，通过在tsconfig.node.json中设置合适的编译目标（如es6、es2017等），可以确保编译后的JavaScript代码在Node.js环境中能够高效运行。
• 例如，如果你的Node.js版本支持ES6特性，将编译目标设置为es6可以利用这些特性，同时避免不必要的代码转换。

4. 文件包含与排除优化

• 可以指定哪些文件或目录需要被包含（include）或排除（exclude）在Node.js相关的TypeScript编译范围内。
• 这有助于优化编译过程，例如，可以排除与前端相关的文件（如果项目是一个包含前端和后端部分的全栈项目），只编译与Node.js后端服务相关的TypeScript文件。

5. 与构建工具集成

• 在使用构建工具（如Webpack或Rollup等）构建Node.js项目时，构建工具会参考tsconfig.node.json中的配置来正确地编译TypeScript代码。
• 这确保了构建出的JavaScript代码符合Node.js环境的要求，并且在运行时能够正确地加载模块、执行代码并处理各种依赖关系。

6.配置示例

以下是一个tsconfig.node.json 文件的示例，可以根据自己的项目需求进行修改和调整：

{
"compilerOptions": {
    "composite": true,
    "target": "ES2022",
    "lib": ["ES2023"],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    // "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": false,

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["vite.config.ts"]
}

以下是对这段 tsconfig.node.json 文件配置的解析：

• composite：
  • 启用复合项目编译。复合项目允许不同的项目共享相同的 TypeScript 配置，提高开发效率和一致性。
• target：
  • 设置编译目标为 ES2022，这意味着 TypeScript 代码将被编译为符合 ES2022 标准的 JavaScript 代码，以确保生成的代码可以在支持该版本 JavaScript 的环境中运行。
• lib：
  • 指定要包含的 JavaScript 库。这里指定为 ["ES2023"]，表示在编译过程中可以使用 ES2023 标准的内置库和特性。
• module：
  • 设置模块系统为 ESNext，表示使用最新的 ECMAScript 模块系统。这可以让代码利用最新的模块特性，并且在一些现代的打包工具和运行环境中更好地优化和加载模块。
• skipLibCheck：
  • 跳过对声明文件（.d.ts）的类型检查。这可以加快编译速度，特别是当项目中引用了大量的第三方声明文件时。
• moduleResolution：
  • 设置为 bundler，表示使用打包工具（如 Webpack、Rollup 等）的模块解析策略。这有助于在使用打包工具时正确地解析模块引用，确保代码在打包后的环境中能够正常运行。
• allowImportingTsExtensions（注释掉的部分）：
  • 如果启用，可能允许导入以 .ts 扩展名结尾的文件。但这里注释掉了，说明当前配置不允许这种行为。
• isolatedModules：
  • 启用独立模块模式。在这种模式下，每个 TypeScript 文件被视为一个独立的模块，有助于提高类型检查的准确性和性能。
• moduleDetection：
  • 设置为 force，强制使用特定的模块检测策略。具体的策略取决于上下文，但通常会确保模块的正确解析和加载。
• noEmit：
  • 设置为 false，表示在编译过程中会生成输出文件。如果设置为 true，则不会生成任何输出文件，通常用于只进行类型检查而不生成实际的 JavaScript 代码的情况。
• 严格模式相关设置：
  • strict：启用严格模式，进行更严格的类型检查和代码规范要求。
  • noUnusedLocals：不允许存在未使用的局部变量，有助于提高代码质量和减少潜在的错误。
  • noUnusedParameters：不允许存在未使用的函数参数，同样有助于提高代码质量。
  • noFallthroughCasesInSwitch：在 switch 语句中，不允许出现没有 break 或 return 的情况，以防止意外的逻辑错误。
• include：
  • 指定要包含在编译过程中的文件。这里只包含了 vite.config.ts 文件，说明只有这个文件会被 TypeScript 编译器处理。这可能是因为这个文件中包含了与 Node.js 项目相关的特定配置或逻辑，需要进行 TypeScript 编译以确保正确性。