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 扩展名即可。