vue项目中tsconfig.json的配置项用法介绍
更新时间：2025年12月16日 09:42:32 作者：天河-
本文介绍了Vue项目中tsconfig.json文件的核心配置项,包括compilerOptions、include、exclude等,通过合理配置这些选项,可以提升TypeScript与Vue单文件组件、工具链的协作效率,增强类型安全性和开发体验,同时,还分享了一些常见问题的解决方法
在 Vue 项目中，tsconfig.json 是 TypeScript 编译器的核心配置文件，用于指定编译选项、类型检查规则、文件范围等。
合理配置 tsconfig.json 能确保 TypeScript 与 Vue 单文件组件（.vue）、工具链（如 Vite）正确协作，提升类型安全性和开发体验。
一、tsconfig.json基本结构
Vue 项目的 tsconfig.json 通常包含以下结构：
- json
{
"compilerOptions": { /* 编译选项 */ },
"include": [ /* 需要编译的文件 */ ],
"exclude": [ /* 排除的文件 */ ],
"extends": [ /* 继承其他配置文件 */ ]
}
二、核心配置项详解（Vue 项目常用）
1.compilerOptions（编译选项）
这是最核心的配置项，控制 TypeScript 的编译行为和类型检查规则。
| 配置项 | 作用说明 | Vue 项目常用值 |
|---|---|---|
| target | 指定编译后 JavaScript 的 ECMAScript 版本 | ESNext（支持最新语法，配合 Babel 转译） |
| module | 指定模块系统（模块化方案） | ESNext（与 ESM 兼容，支持动态导入） |
| moduleResolution | 模块解析策略（如何查找导入的模块） | Node（与 Node.js 解析规则一致） |
| strict | 启用所有严格类型检查选项（推荐开启，提升类型安全性） | true |
| jsx | 指定 JSX 处理方式（Vue 项目常用 preserve 保留 JSX 语法，由 Vue 处理） | preserve |
| sourceMap | 是否生成 SourceMap（调试时映射 TS 到 JS） | true（开发环境）/ false（生产环境） |
| resolveJsonModule | 允许导入 JSON 文件 | true |
| esModuleInterop | 允许 ESM 与 CommonJS 模块互操作（如默认导入 CommonJS 模块） | true |
| allowSyntheticDefaultImports | 允许从无默认导出的模块中默认导入（如某些第三方库） | true |
| baseUrl | 模块解析的基础目录（配合 paths 使用） | "."（项目根目录） |
| paths | 路径别名配置（需与 Vite/Webpack 的别名同步，如 @ 指向 src） | {"@/*": ["src/*"]} |
| types | 指定需要包含的类型声明文件（如 Vite、Vue 的类型） | ["vite/client", "vue", "node"] |
| skipLibCheck | 跳过对库文件（如 node_modules 中的类型）的类型检查（提升编译速度） | true |
| allowJs | 允许编译 JavaScript 文件（逐步迁移 JS 到 TS 时使用） | true（可选） |
2.include和exclude
include：指定需要 TypeScript 处理的文件或目录（支持通配符*）。exclude：指定需要排除的文件或目录（默认排除node_modules）。
Vue 项目典型配置：
- json
{
"include": [
"src/**/*.ts", // 所有 TS 文件
"src/**/*.d.ts", // 所有类型声明文件
"src/**/*.tsx", // 所有 TSX 文件
"src/**/*.vue" // 所有 Vue 单文件组件
],
"exclude": ["node_modules", "dist"] // 排除依赖和构建产物
}
3.extends
继承其他配置文件（减少重复配置），常用场景：
- 继承 Vue 官方推荐配置：
@vue/tsconfig/tsconfig.dom.json - 继承 TypeScript 官方严格配置：
strict
json
{
"extends": "@vue/tsconfig/tsconfig.dom.json",
"compilerOptions": {
// 在此覆盖或补充配置
}
}
三、Vue 项目完整配置示例
{
"extends": "@vue/tsconfig/tsconfig.dom.json",
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Node",
"strict": true,
"jsx": "preserve",
"sourceMap": true,
"resolveJsonModule": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"components/*": ["src/components/*"]
},
"types": ["vite/client", "vue", "node"],
"skipLibCheck": true,
"allowJs": true
},
"include": [
"src/**/*.ts",
"src/**/*.d.ts",
"src/**/*.tsx",
"src/**/*.vue",
"src/env.d.ts"
],
"exclude": ["node_modules", "dist"]
}
四、关键配置的使用场景
1. 路径别名（baseUrl+paths）
配合 Vite 的 resolve.alias 使用，简化模块导入：
tsconfig.json 中配置：
- json
"baseUrl": ".",
"paths": { "@/*": ["src/*"] }
代码中直接使用：
- typescript
import Home from '@/views/Home.vue' // 等价于 './src/views/Home.vue'
2. 严格模式（strict: true）
开启后会强制检查以下规则（提升代码质量）：
- 变量必须声明类型（或通过上下文推断）
null和undefined必须显式处理（避免Cannot read property 'x' of undefined错误）this必须有明确类型（避免在 Vue 组件中误用this）
若需要部分关闭，可单独设置子选项（如 strictNullChecks: false），但不推荐。
3. 类型声明文件（types+src/env.d.ts）
types: ["vite/client"]：导入 Vite 客户端类型（如import.meta.env）src/env.d.ts：声明 Vue 组件和环境变量类型（必须包含在include中）：
typescript
// src/env.d.ts
declare module '*.vue' {
import type { DefineComponent } from 'vue'
const component: DefineComponent<{}, {}, any>
export default component
}
interface ImportMetaEnv {
readonly VITE_API_URL: string // 声明环境变量类型
}
五、常见问题解决
*“找不到模块 .vue” 错误
确保 src/env.d.ts 中声明了 .vue 模块，且 tsconfig.json 的 include 包含该文件。
路径别名不生效
- 检查
paths配置是否与 Vite 的resolve.alias一致 - 安装
@types/node获得路径解析支持：npm install @types/node -D
第三方库缺少类型声明
- 安装对应的
@types/xxx包（如@types/lodash） - 若没有类型包，可在
src/env.d.ts中手动声明：
typescript
declare module 'untyped-lib' {
export function func(a: number): string
}
通过合理配置 tsconfig.json，可以让 TypeScript 更好地适配 Vue 项目，充分发挥类型检查的优势，减少运行时错误。
更多配置细节可参考 TypeScript 官方文档 和 Vue TypeScript 指南。
总结
以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。
相关文章
vue element-ui el-table组件自定义合计(summary-method)的坑
这篇文章主要介绍了vue element-ui el-table组件自定义合计(summary-method)的坑及解决，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2023-02-02
本篇文章主要介绍了关于页面刷新vuex数据消失问题解决方案 ，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧2017-07-07
使用axios可以很方便地获取后端返回的文件流数据,并在前端直接在浏览器下载,这篇文章主要给大家介绍了关于前端处理axios请求下载后端返回的文件流的相关资料,需要的朋友可以参考下2024-07-07
这篇文章主要给大家介绍了关于Vue3中引入scss文件的方法步骤,在实际项目中,各种样式往往有很多重复的情况,为了能够使样式的后续开发和维护更加惬意,将这些共同的代码进行命名然后调用这些变量是一个很好的选择,需要的朋友可以参考下2023-08-08
这篇文章主要介绍了vue+element表单校验功能,本文通过实例代码给大家介绍的非常详细，具有一定的参考借鉴价值，需要的朋友可以参考下2019-05-05
这篇文章主要介绍了Vue使用echarts可视化组件的方法,本文通过实例代码案例给大家详细介绍，需要的朋友可以参考下2021-07-07
这篇文章主要介绍了vue中如何携带参数跳转页面问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2023-04-04
这篇文章主要介绍了vue backtop组件的实现完整代码,本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下2021-04-04
这篇文章主要介绍了vue中如何通过函数传参数问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2023-04-04
这篇文章主要介绍了vue事件监听函数on中的this指针域使用方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2022-08-08
最新评论