2025-02-07 关于 vue 类型声明文件 shims-vue.d.ts 的详细理解

127 阅读2分钟

1. 关于 xx.d.ts 文件类型

首先,TypeScript 声明文件(.d.ts)主要用于:

  • 类型声明:为没有类型定义的代码(如 JavaScript 模块、非代码资源)提供类型信息

  • 类型扩展:扩展或修改现有类型定义

  • 模块声明:告诉 TypeScript 如何处理特定模块或文件类型的导入

以 shims-vue.d.ts 为例:

declare module "*.vue" {
  import Vue from "vue";
  const component: ReturnType<typeof Vue.extend>;
  export default component;
}

这个声明是在"告诉" TypeScript:

  • 任何以 .vue 结尾的导入(*.vue),都应该被视为一个模块

  • 这个模块导出的是一个 Vue 组件

2. 关于 xx.d.ts 类型声明文件生效条件

在项目中如果想让其生效的话,需要在 typescript 的配置文件 tsconfig.json 中声明

{
   "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "tests/**/*.ts",
    "tests/**/*.tsx"
    "shims-vue.d.ts" // 不在src下放置增加这条
  ],
}

如果 shims-vue.d.ts 放在src目录下,就不需要引入。因为 TypeScript 有一个自动包含(Auto-inclusion)的特性。当 TypeScript 项目的 tsconfig.json 包含了某个目录(如 src/**/*)时,它会自动包含该目录下所有的:

  • .ts 文件
  • .d.ts 声明文件
  • .tsx 文件(如果启用了 JSX)

典型的 tsconfig.json 配置:

{
  "include": [
    "src/**/*.ts",    // 这条规则会自动包含 src 下的所有 .ts 和 .d.ts 文件
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

所以:

  • 当 shims-vue.d.ts 在 src 目录下时:

  • ✅ 自动被 src/**/*.ts 规则包含

  • 不需要额外配置

  • 当 shims-vue.d.ts 在项目根目录时:

  • ❌ 不在 src/**/*.ts 的匹配范围内

  • 需要在 tsconfig.json 中明确包含

这就是为什么把声明文件放在 src 目录下是最简单的方式 - 它利用了 TypeScript 的自动包含机制。

3. 是否必须声明为 shims-vue.d.ts

不需要必须命名为 shims-vue。TypeScript 不关心声明文件的具体名字,只要满足以下条件即可:

  • 文件扩展名必须是 .d.ts

  • 文件位于 TypeScript 的搜索路径内(如 src 目录)

例如,这些命名都是有效的:

src/
├── types.d.ts
├── vue-types.d.ts
├── declarations.d.ts
└── custom-vue.d.ts

使用 shims-vue.d.ts 这个名字的原因是:

  • 它是一个清晰的命名约定,表明这是 Vue 相关的类型垫片

  • Vue CLI 等工具会默认生成这个名字

  • 遵循社区约定有助于代码维护和团队协作

但从技术角度来说,文件名可以随意设置,只要保持 .d.ts 扩展名即可。