# TypeScript 项目实战配置

URL: https://caijiao.org/ts/part3/project-config
Source: docs/ts/part3/project-config.md
Description: 如何为 TypeScript 项目配置 tsconfig.json，处理模块解析、路径别名、严格模式配置，以及如何将构建与类型检查分离。

在实际项目中，[TypeScript](/ts/) 配置文件（`tsconfig.json`）是 TypeScript 项目的核心。通过合理的配置，可以确保项目的模块解析、类型检查和构建过程符合预期。本章节将介绍如何配置 TypeScript 项目，提升开发效率和代码质量。

## tsconfig.json 配置

`tsconfig.json` 文件用于指定 TypeScript 编译器的配置选项。该文件的配置直接影响到项目的编译和运行。

### 基本结构

一个简单的 `tsconfig.json` 配置文件可能如下所示：

```json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
```

### 主要配置项

- `target`: 指定 ECMAScript 版本。`es5` 或 `es6` 常见。
- `module`: 指定模块系统。通常使用 `commonjs`（Node.js）或 `esnext`（ES6 模块）。
- `strict`: 启用所有严格类型检查选项，建议开启以保证代码的健壮性。
- `esModuleInterop`: 允许默认导入非 ES 模块的模块。
- `skipLibCheck`: 跳过库文件的类型检查，提升编译速度。
- `forceConsistentCasingInFileNames`: 强制文件名一致性检查，避免大小写错误。

## 模块解析与路径别名

TypeScript 允许使用路径别名，使模块导入更加简洁和易于维护。配置路径别名时需要在 `tsconfig.json` 中设置 `baseUrl` 和 `paths`。

### 配置路径别名

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

### 使用路径别名

```ts
import { add } from "@utils/math";
import { Button } from "@components/Button";
```

通过配置路径别名，避免了复杂的相对路径，同时增强了代码可读性。

## 严格模式配置

启用严格模式（`strict`）是 TypeScript 的最佳实践，它包含一系列有助于提高代码质量的选项：

- `strictNullChecks`: 严格的 `null` 和 `undefined` 检查。
- `noImplicitAny`: 不允许隐式的 `any` 类型。
- `noImplicitThis`: 禁止在函数中使用隐式的 `this` 类型。
- `alwaysStrict`: 强制将代码文件转为严格模式。

启用这些选项后，TypeScript 会更严格地检查类型，减少潜在的错误。

```json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "noImplicitAny": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}
```

## 构建与类型检查分离

在实际开发中，可能希望将构建过程与类型检查过程分离。可以通过使用 `tsc` 命令进行类型检查，同时使用工具如 `webpack` 或 `vite` 进行构建。

### 使用 `tsc` 进行类型检查

```bash
tsc --noEmit
```

该命令会进行类型检查，但不会生成 JavaScript 文件。你可以将类型检查与构建流程分开，以便在构建之前发现潜在的类型错误。

### 使用 `vite` 或 `webpack` 构建

在构建工具（如 `vite` 或 `webpack`）中，你可以通过 TypeScript 插件进行构建，确保类型检查与构建过程分离。

例如，使用 Vite 时可以配置 `vite-plugin-checker` 插件进行类型检查：

```bash
npm install vite-plugin-checker --save-dev
```

```ts
import ViteChecker from "vite-plugin-checker";

export default {
  plugins: [ViteChecker({ typescript: true })],
};
```

通过这种方式，你可以确保类型检查不会影响构建流程，但仍然能够在开发过程中实时检查类型错误。