扩展Vue全局属性时如何保留vue-router的类型增强

核心原因 #

TypeScript中同一模块下的同名接口会自动合并，但如果插件类型文件未正确关联Vue基础类型，或是Turborepo工作区的类型解析顺序异常，就会导致vue-router的$router/$route类型被覆盖。

解决方案步骤 #

1. 修正插件类型文件的导入逻辑 #

在插件的.d.ts文件开头，明确导入Vue相关基础类型，让TypeScript识别这是对现有接口的扩展而非重新定义：

// routes-plugin.d.ts
import type { ComponentCustomProperties, RouteRecordRaw } from 'vue-router';

export {};

declare module 'vue' {
  interface ComponentCustomProperties {
    $routes: RouteRecordRaw[];
  }
}

// auth-plugin.d.ts
import type { ComponentCustomProperties } from 'vue';
import type { AuthManager } from './your-auth-manager-path'; // 导入AuthManager的类型定义

export {};

declare module 'vue' {
  interface ComponentCustomProperties {
    $auth: AuthManager;
  }
}

2. 配置应用的tsconfig.json #

在使用插件的Vue应用tsconfig.json中，确保types字段包含vue-router和自定义插件的类型，同时确认插件包的package.json正确声明类型入口：

// Vue应用的tsconfig.json
{
  "compilerOptions": {
    "types": [
      "vue-router",
      "@repo/auth-vue",
      "@repo/routes-plugin"
    ]
  }
}

// 插件包的package.json（以auth-vue为例）
{
  "types": "./dist/auth-plugin.d.ts"
}

3. 优化Turborepo的类型解析配置 #

在Turborepo根目录的tsconfig.json中，通过paths和references确保工作区包的类型能被正确解析：

{
  "compilerOptions": {
    "paths": {
      "@repo/*": ["./packages/*"]
    }
  },
  "references": [
    { "path": "./packages/auth-vue" },
    { "path": "./packages/routes-plugin" }
  ]
}

验证方式 #

在Vue组件中尝试访问this.$router、this.$route、this.$auth和this.$routes，检查TypeScript是否能正确识别所有属性的类型且无报错。

内容的提问来源于stack exchange，提问作者Alfonso Irarrázaval