网站导航
> 技术文档 > tsconfig.json常用配置

tsconfig.json常用配置

网友: 技术文档 2025-09-03 12:40:30

tsconfig.json 是 TypeScript 项目的核心配置文件，用于指定编译选项和项目结构。它告诉 TypeScript 编译器如何处理当前项目的代码。

🧩 一、基本结构

一个最简 tsconfig.json 文件如下：

{ \"compilerOptions\": { // 编译选项 }, \"include\": [ // 包含哪些目录下的文件 ], \"exclude\": [ // 排除哪些目录 ]}

⚙️ 二、常用 compilerOptions 配置详解

1. 基础设置

选项 描述 \"target\": \"es2015\" 指定编译后的 JavaScript 版本（如 es2015, esnext） \"module\": \"esnext\" 模块系统（如 commonjs, esnext） \"lib\": [\"es2020\", \"dom\", \"es2021.string\"] 支持的库（DOM API、ES 特性等） \"strict\": true 启用所有严格类型检查选项 \"esModuleInterop\": true 允许使用 ES 模块语法导入 CommonJS 模块 \"skipLibCheck\": true 跳过对 .d.ts 类型定义文件的类型检查

2. 输出相关

选项 描述 \"outDir\": \"./dist\" 输出目录 \"rootDir\": \"./src\" 源码目录 \"declaration\": true 是否生成 .d.ts 类型声明文件 \"sourceMap\": true 是否生成 .map 文件 \"removeComments\": true 删除注释 \"noEmit\": true 不输出文件，只进行类型检查

3. 模块解析

选项 描述 \"moduleResolution\": \"node\" 使用 Node.js 的模块解析策略 \"baseUrl\": \".\" 模块解析的基础路径 \"paths\": { \"@/*\": [\"src/*\"] } 路径别名映射（需配合 webpack/vite 设置） \"types\": [\"vite/client\", \"vue\"] 指定全局引入的类型定义包

4. 类型检查增强

选项 描述 \"noImplicitAny\": true 禁止对未指定类型的变量隐式推断为 any \"strictNullChecks\": true 启用严格的 null 检查 \"strictFunctionTypes\": true 严格检查函数参数类型 \"strictPropertyInitialization\": true 类属性必须在构造函数中初始化或明确赋值 \"alwaysStrict\": true 在编译出的 JS 中始终启用严格模式

5. 项目引用与构建优化（高级）

选项 描述 \"composite\": true 开启项目组合支持（用于 monorepo 或子项目） \"references\": [{ \"path\": \"../core\" }] 引用其他 tsconfig.json 项目 \"incremental\": true 启用增量编译（加快后续构建速度）

📁 三、include 和 exclude

用于控制哪些文件需要被 TypeScript 编译器处理。

{ \"include\": [\"src/**/*\"], \"exclude\": [\"node_modules\", \"**/*.spec.ts\"] }
  • include：默认是 [\"**/*\"]，即包含所有文件。
  • exclude：默认排除 node_modules、bower_components、jspm_packages。

🎯 四 、baseUrl和Paths

\"baseUrl\": \".\" 是 tsconfig.json 中的一个重要配置项，用于指定模块解析的基准路径。它在使用 相对路径导入模块（如 import xxx from \'xxx\'）时起到关键作用。

 一、作用详解

 \"baseUrl\": \".\" 的含义：

{ \"compilerOptions\": { \"baseUrl\": \".\" } }
  • 表示：所有非相对模块（non-relative module）的查找起点为当前目录（即 tsconfig.json 所在目录）。
  • 简单来说，就是告诉 TypeScript 编译器：

    “如果我写了 import utils from \'utils\'，请从项目根目录开始找这个文件。”

📁 二、举个例子说明

假设你的项目结构如下：

my-project/├── tsconfig.json├── src/│ ├── main.ts│ └── utils.ts└── shared/ └── config.ts

场景 1：没有设置 \"baseUrl\": \".\"

你必须这样写：

import utils from \'./src/utils\'

场景 2：设置了 \"baseUrl\": \".\"

你可以这样写：

import utils from \'src/utils\' import config from \'shared/config\'

因为 TypeScript 会从 baseUrl 指定的路径（.）开始查找这些模块。

🎯 三、与 \"paths\" 配合使用更强大

{ \"compilerOptions\": { \"baseUrl\": \".\", \"paths\": { \"@/*\": [\"src/*\"] } } }

然后你就可以这样写：

import utils from \'@/utils\'

这在 Vue、React 等现代前端项目中非常常见。

⚠️ 注意：构建工具（如 Webpack、Vite）也需要配置相同的别名，否则浏览器运行时报错找不到模块。

🧠 四、总结

配置 作用 \"baseUrl\": \".\" 设置非相对路径模块的查找起点为当前目录 常用于 配合 paths 实现路径别名、简化 import 路径 示例 import utils from \'src/utils\'

✅ 五、最佳实践建议

  • 如果你使用了路径别名（如 @/components），务必同时设置 \"baseUrl\": \".\" 和 \"paths\"。
  • 确保构建工具（如 Vite/Webpack）也配置了相同的别名。
  • \"baseUrl\": \".\" 对编译结果无影响，仅影响类型检查和 IDE 的智能提示。

五、types和typesRoots 

在 tsconfig.json 中，\"types\" 是一个非常重要的配置项，用于指定要包含的类型定义文件（.d.ts）或全局类型包。它主要用于控制 TypeScript 在编译时加载哪些全局类型信息。

 一、基本语法

{ \"compilerOptions\": { \"types\": [\"vue\", \"vite/client\", \"node\"] } }

✅ 含义：

  • \"types\" 数组中列出的模块名（如 \"vue\"），TypeScript 编译器会在编译过程中自动引入它们的全局类型定义。
  • 这些类型是“全局可见”的，不需要手动 import。
  • 它们通常是一些库的 .d.ts 类型声明文件。

📌 二、与 typeRoots 的关系

配置项 作用 \"types\" 指定要包含的具体类型包（按名称匹配） \"typeRoots\" 指定查找类型定义的目录路径（默认是 node_modules/@types）

示例：

{ \"compilerOptions\": { \"types\": [\"vue\", \"vite/client\"], \"typeRoots\": [\"./typings\", \"node_modules/@types\"] } }

⚠️ 如果你设置了 \"types\"，那么 只有这些指定的类型包会被加载，默认的 @types 将被忽略。

🎯 三、常见用途

1. 支持 Vue 项目的类型提示

{ \"compilerOptions\": { \"types\": [\"vue\"] } }

这样就可以识别 Vue 单文件组件中的 、defineProps 等语法。

2. 支持 Vite 的客户端 API 类型

{ \"compilerOptions\": { \"types\": [\"vite/client\"] } }

可以识别 import.meta.env、import.meta.hot 等 Vite 提供的 API。

3. 支持 Node.js 内置类型

{ \"compilerOptions\": { \"types\": [\"node\"] } }

用于支持 Node.js 的内置模块（如 fs, path）的类型提示。

4. 自定义全局类型

你可以创建自己的 .d.ts 文件，并通过 \"types\" 引入为全局类型：

步骤：
  1. 创建 global.d.ts 文件：
// global.d.ts declare module \'my-library\' { export function sayHello(): void }
  1. 在 tsconfig.json 中添加：
{ \"compilerOptions\": { \"types\": [\"my-library\"] } }

现在你就可以在任意地方使用 import { sayHello } from \'my-library\' 并获得类型提示。

🧠 四、注意事项

问题 建议 不设置 \"types\" 会自动加载所有 @types？ ✅ 是的，默认会加载所有全局类型 设置 \"types\" 后其他类型不生效？ ⚠️ 是的，只会加载你明确指定的类型 报错找不到模块类型？ ✅ 确保已安装对应的类型包，如 npm install @types/node --save-dev 是否需要配合 \"typeRoots\" 使用？ ✅ 如果你自定义了类型目录，建议一起设置

    🧪 六、示例完整配置（Vue + TS 项目）

    { \"compilerOptions\": { \"target\": \"es2018\", \"module\": \"esnext\", \"lib\": [\"es2020\", \"dom\"], \"strict\": true, \"moduleResolution\": \"node\", \"esModuleInterop\": true, \"skipLibCheck\": true, \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"declaration\": false, \"sourceMap\": true, \"moduleDetection\": \"auto\", \"experimentalDecorators\": true, \"emitDecoratorMetadata\": true, \"types\": [\"vite/client\", \"vue\"], \"baseUrl\": \".\", \"paths\": { \"@/*\": [\"src/*\"] } }, \"include\": [\"src/**/*\"], \"exclude\": [\"node_modules\"]}

    📌 七、常见问题解答

    问题 解决方式 报错找不到模块？ 检查 moduleResolution 是否设为 node Vue 单文件组件报错？ 添加 \"types\": [\"vue\"] 并安装 @vue/runtime-dom 使用了装饰器不生效？ 添加 \"experimentalDecorators\": true 路径别名无法识别？ 设置 baseUrl 和 paths，并确保构建工具也配置了相同别名 构建太慢？ 启用 \"incremental\": true
    网络标签：

    相关问题