当前位置：首页 > news >正文

TypeScript 项目配置

news 2025/6/14 14:41:41

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、接口自动校验等