一文搞清楚 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

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)

• 情况1：未引入任何类型

  • ❌ 报错：Property 'env' does not exist on type 'ImportMeta'

• 情况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 是"全局自动声明"。

用一句话概括：

• 想在单个 .d.ts 文件中声明局部类型 → 用 triple-slash
• 想让整个项目都能自动识别 → 用 tsconfig.types

🔚 结语

/// <reference types="..." /> 与 tsconfig.types 虽然看起来相似，

但它们其实是 两种加载层级不同的类型机制。

理解两者的区别，不仅能避免"为什么类型不生效"的坑，

也能帮助你更好地组织大型 TypeScript 项目的类型依赖结构。