如何使用JSDoc导出全局类型以复用Vue的Ref类型？

如果你想在多个文件里直接使用Ref<string>这类类型而不用每次写完整的import('vue').Ref，可以根据项目类型（TypeScript/纯JavaScript）选择以下方案：

方案一：TypeScript项目（推荐） #

在项目的类型声明文件中（比如src/vite-env.d.ts，或者新建src/types/global.d.ts）添加全局类型别名：

import type { Ref } from 'vue';

declare global {
  // 全局复用Vue的Ref类型
  type Ref<T = any> = import('vue').Ref<T>;
  // 可按需添加其他常用类型，比如ComputedRef、Reactive等
  // type ComputedRef<T = any> = import('vue').ComputedRef<T>;
}

// 必须导出空对象，确保文件被识别为模块
export {};

然后在tsconfig.json中确保该声明文件被包含：

{
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
}

之后所有文件里就能直接使用Ref<string>，无需重复导入。

方案二：纯JavaScript + JSDoc项目 #

方式1：用全局类型声明文件 #

新建global.d.ts文件（即使是JS项目，TypeScript工具链也能处理这个文件提供类型提示）：

import type { Ref } from 'vue';

declare global {
  type Ref<T = any> = import('vue').Ref<T>;
}

export {};

然后在jsconfig.json中配置：

{
  "compilerOptions": {
    "checkJs": true, // 启用JS文件的类型检查
    "module": "ESNext",
    "target": "ESNext"
  },
  "include": ["src/**/*", "global.d.ts"]
}

这样在JS文件的JSDoc中就能直接写：

/** @type {Ref<string>} */
const variable = ref('variable');

方式2：JSDoc全局类型声明 #

在项目入口文件（比如main.js）中添加全局类型定义：

/**
 * @typedef {import('vue').Ref} Ref
 * @global
 */

之后在其他JS文件顶部，需要手动声明该全局变量才能被JSDoc识别：

/* global Ref */

/** @type {Ref<string>} */
const variable = ref('variable');

这种方式需要每个文件都加/* global Ref */，不如类型声明文件方便。

额外提示：Vue 3 <script setup>自动类型推断 #

如果使用Vue 3的<script setup>语法，ref等API会自动导入，而且类型推断会自动生效，很多时候不需要手动标注类型：

<script setup>
import { ref } from 'vue';

// variable的类型自动推断为Ref<string>
const variable = ref('variable');
</script>

内容的提问来源于stack exchange，提问作者s3xysteak