一文搞清楚 TypeScript 中 triple-slash 与 tsconfig.types 有何区别？`/// <

在 Vite + TypeScript 项目中，我们常常会看到这样一段神秘的声明：

/// <reference types="vite/client" />

很多人知道“这行是用来让 TypeScript 不报错的”，但它到底和 tsconfig.json 里的 compilerOptions.types 有什么关系？
两者能互换吗？什么时候该用哪一个？

本文将带你彻底搞清楚这两者的区别与联系。

🧩 一、`/// <reference types="..." />` 是什么？

这是一种 TypeScript 的类型声明引用（Triple-slash directive） 。
作用是告诉 TypeScript 编译器：

“在编译当前文件时，请加载某个包的类型定义。”

例如：

/// <reference types="vite/client" />
/// <reference types="vite-svg-loader" />

这两行分别加载：

Vite 的运行时类型定义（让你能安全使用 import.meta.env、import.meta.glob 等）
vite-svg-loader 的类型定义（让 import Logo from './logo.svg?component' 被识别为一个 Vue 组件）

如果没有这两行，TypeScript 可能会提示：

Property 'env' does not exist on type 'ImportMeta'.

📍 通常它们被放在项目根目录的 env.d.ts 或 vite-env.d.ts 文件中，例如：

// env.d.ts
/// <reference types="vite/client" />
/// <reference types="vite-svg-loader" />

这样，整个项目的类型系统都能识别这些定义。

tsconfig.json 提供了另一种声明类型依赖的方式：

{
  "compilerOptions": {
    "types": ["vite/client", "vite-svg-loader"]
  }
}

这告诉 TypeScript：

“在项目编译时，请全局自动加载这些类型包。”

相当于在每个文件里都隐式加上了对应的 /// <reference types="..." />。

📦 它是一个项目级别的全局配置，不需要在每个文件中手动添加引用。

对比项	`/// <reference types="..."/>`	`tsconfig.json → compilerOptions.types`
作用范围	当前文件（或当前声明文件）	整个项目全局
配置位置	`.d.ts` 文件顶部	`tsconfig.json`
使用场景	插件或局部类型扩展	全局项目类型控制
是否自动加载	否，需要手动写	是，全局自动加载
常见用法	`vite/client`、`vite-svg-loader`	`node`、`jest`、`vite/client`
细粒度控制	✅（单文件级）	❌（项目级）
性能影响	小（仅当前文件）	大（可能加载更多类型）

场景	推荐做法
普通 Vite + Vue/React 项目	在 `env.d.ts` 中写 triple-slash 引用
Monorepo 或库开发	在各子包的 `tsconfig.json` 中配置 `types`
避免全局污染	用 triple-slash 仅在特定声明文件引用
明确项目全局依赖	使用 `types` 显式声明全局类型包

假设你有以下代码：

console.log(import.meta.env.MODE)

情况2：添加 triple-slash

/// <reference types="vite/client" />
console.log(import.meta.env.MODE)

✅ 不再报错，识别出类型定义。

情况3：在 tsconfig.json 中配置
```
{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}
```
✅ 整个项目都能识别，无需在文件中写 /// <reference />。

/// <reference types="..." /> 是“局部显式声明”，
tsconfig.compilerOptions.types 是“全局自动声明”。

用一句话概括：

/// <reference types="..." /> 与 tsconfig.types 虽然看起来相似，
但它们其实是 两种加载层级不同的类型机制。

理解两者的区别，不仅能避免“为什么类型不生效”的坑，
也能帮助你更好地组织大型 TypeScript 项目的类型依赖结构。