TypeScript 项目配置

TypeScript 项目配置

基于 React + Vite ，比较完整且实用的 TypeScript 多配置拆分示例，适用于中大型项目，包含：

• 基础公共配置：tsconfig.base.json
• 前端浏览器模块配置：tsconfig.app.json
• 后端 Node.js 模块配置：tsconfig.node.json
• 顶层项目引用配置：tsconfig.json

1. tsconfig.base.json --- 公共基础配置

{
  "compilerOptions": {
    "target": "ES2020",                    // 编译目标版本，兼顾现代环境
    "module": "ESNext",                    // 代码模块格式，开发时用 ESNext
    "lib": ["ESNext"],                     // 包含的库，基础语言功能
    "allowJs": false,                      // 是否允许编译 JS 文件
    "checkJs": false,                      // 是否检查 JS 文件
    "jsx": "react-jsx",                    // React JSX 转换方式
    "strict": true,                        // 启用严格类型检查
    "moduleResolution": "Node",            // 模块解析方式，兼容 node
    "esModuleInterop": true,               // 允许 CommonJS 默认导入
    "forceConsistentCasingInFileNames": true,  // 文件名大小写一致性
    "skipLibCheck": true,                  // 跳过依赖库的类型检查，加快编译
    "isolatedModules": true,               // 允许单文件编译，兼容 Babel
    "resolveJsonModule": true,             // 支持导入 JSON
    "baseUrl": ".",                       // 基础路径，配合 paths 使用
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@assets/*": ["src/assets/*"]
    },
    "types": ["node"]                     // 默认引入 Node 类型
  },
  "exclude": [
    "node_modules",
    "dist",
    "build"
  ]
}

2. tsconfig.app.json --- 前端浏览器模块配置

{
  "extends": "./tsconfig.base.json",      // 继承基础配置
  "compilerOptions": {
    "target": "ESNext",                   // 现代浏览器支持 ESNext
    "lib": ["DOM", "DOM.Iterable", "ESNext"],  // 加入浏览器环境库
    "types": ["vite/client"]              // Vite 客户端环境类型
  },
  "include": ["src/app/**/*", "src/shared/**/*"],  // 需要编译的文件路径
  "exclude": ["src/node"]                // 排除后端代码
}

3. tsconfig.node.json --- 后端 Node.js 模块配置

{
  "extends": "./tsconfig.base.json",      // 继承基础配置
  "compilerOptions": {
    "target": "ES2020",                   // Node.js 14+ 支持 ES2020 特性
    "module": "CommonJS",                 // Node.js 典型模块格式
    "lib": ["ES2020"],                    // Node.js 环境相关库
    "types": ["node"]                     // Node 类型声明
  },
  "include": ["src/node/**/*", "src/shared/**/*"], // 包含后端代码和共享代码
  "exclude": ["src/app"]                  // 排除前端代码
}

4. tsconfig.json --- 顶层项目引用配置

{
  "files": [],                           // 这个顶层不单独编译文件
  "references": [
    { "path": "./tsconfig.app.json" },   // 引用前端模块
    { "path": "./tsconfig.node.json" }   // 引用后端模块
  ]
}

补充说明

• extends 关键字用来继承基础配置，减少重复。
• references 用来声明项目间依赖，方便增量编译和代码导航。
• include/exclude 让你区分前端和后端代码目录，避免编译不相关的代码。
• "types" 根据项目需求加载不同环境的类型声明。
• 你可以根据实际项目，增加如测试配置 tsconfig.test.json 等。

---

注意 ：通常针对 web 端，只需要 tsconfig.app.json 即可

---

5. 搭配 Vite.config.ts 配置文件路径

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'), // 控制 import 语句解析
    },
  },
})

注意 ：import path from 'path' 时可能会报错 找不到模块"path"或其相应的类型声明 ，意思是：说明 TypeScript 编译器无法识别 Node.js 内置模块 path 的类型。只需执行以下命令

npm install --save-dev @types/node

原因解析：

• TypeScript 默认只包含浏览器的类型定义；
• path 属于 Node.js 内置模块；
• 因此你必须手动引入 Node 类型定义库 @types/node 才能让 TypeScript 识别这些模块（包括 fs、path、process 等）。

---

补充：TypeScript 的价值（简洁总结）

价值点	举例说明
类型提示 & IDE 体验提升	自动补全、参数提示、跳转定义、文档弹出，写代码更快
提前发现错误	编译时就能发现类型错误、拼写错误、参数错误，减少运行时 bug
提升代码可读性 & 可维护性	明确函数/组件的输入输出，更容易理解别人写的代码
大型项目中防止"雪崩"式错误扩散	改一个接口不会悄悄影响一堆地方，类型错误会立即暴露
更强的重构能力	改名/提取/重构函数时，IDE 帮你定位所有受影响的地方
便于多人协作 &代码交接	不用问接口字段是什么、不用到处看接口文档，直接在代码里体现
更容易做自动化文档、测试生成	基于类型可以生成 Swagger、Mock、接口自动校验等