如何创建配置Vue 3 TypeScript Plugin？解决导入时TS2307模块找不到报错

错误原因排查 #

• 路径别名@未在TypeScript配置中注册，TS无法识别@/开头的导入路径
• 手动编写的.d.ts声明模块名和实际导入路径不匹配，本地开发的.ts格式插件无需额外手写空模块声明
• 文件名大小写不匹配、TS服务缓存未更新

解决步骤 #

1. 配置TS路径别名 #

在项目根目录的tsconfig.json（Vite项目用tsconfig.app.json）中添加以下配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

配置完成后重启IDE的TypeScript服务，VSCode可通过快捷键Ctrl+Shift+P选择「TypeScript: Restart TS Server」生效。

2. 删除无效的.d.ts声明 #

本地开发的插件如果本身是.ts后缀的源码文件，TypeScript会自动推导类型，不需要额外手写declare module "somePlugin"这类空声明，删除你新建的somePlugin.d.ts即可。

完整Vue3+TS插件开发示例 #

插件代码（src/plugins/somePlugin.ts） #

import type { App, Plugin } from "vue";

// 定义插件入参类型，支持使用时的类型提示
interface SomePluginOptions {
  tipText?: string;
  globalCount?: number;
}

const somePlugin: Plugin<[SomePluginOptions?]> = {
  install: async (app: App, options: SomePluginOptions = {}): Promise<void> => {
    // 示例：注册全局属性
    app.config.globalProperties.$customTip = options.tipText || "默认提示";
    // 示例：注册全局注入属性
    app.provide("PLUGIN_OPTIONS", options);
    // 可扩展注册全局组件、自定义指令等逻辑
  }
}

export default somePlugin;

入口注册代码（main.ts） #

import { createApp } from 'vue'
import App from './App.vue'
import somePlugin from '@/plugins/somePlugin'

const app = createApp(App)
// 传入插件配置时会自动触发类型校验和提示
app.use(somePlugin, {
  tipText: "自定义插件提示"
})
app.mount('#app')

独立发布插件的额外配置 #

如果你需要把插件打包为独立NPM包发布，需要在tsconfig.json中开启自动生成类型声明的配置：

{
  "compilerOptions": {
    "declaration": true,
    "outDir": "./dist"
  }
}

同时在package.json中指定类型文件入口：

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

打包后会自动生成对应的.d.ts类型文件，不需要手动编写。

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