Vue 3 自定义插件开发实战：从原理到生产级权限指令

1. 项目概述：为什么你需要亲手写一个 Vue 插件，而不是直接 npm install

“如何创建自定义 Vue.js 插件”——这行标题背后藏着的不是一道面试题，而是一条从“能用”跃升到“懂设计”的分水岭。我带过十几期前端训练营，90% 的学员能熟练用v-model、v-for和setup()写业务组件，但一问“你项目里那个全局弹窗、权限指令、请求拦截器是怎么挂载到整个应用的”，多数人会卡顿三秒，然后说：“哦…是app.use(xxx)吧？好像是在main.js里写的。”——对，语法没错，但不知道它为什么能生效、怎么控制作用域、如何避免污染全局、怎样让别人也能安全复用，就等于只拿到了遥控器，却没摸过电路板。

Vue 插件的本质，是 Vue 生态中最轻量、最可控、最贴近框架内核的扩展机制。它不依赖构建工具链（Webpack/Vite），不侵入组件生命周期，也不强制你改写已有逻辑；它只是在应用初始化那一刻，向 Vue 实例“悄悄塞进几行配置”——比如把一个函数注册成全局指令，把一个类实例挂载到app.config.globalProperties，或者向app.provide注入可响应式共享的状态。这种能力，在真实项目中解决的是三类高频痛点：

• 重复逻辑抽离：比如每个页面都要手动调用useRouter().push()做路由跳转，而你希望直接this.$go('/user')；
• 跨组件状态桥接：比如多个独立组件需要读写同一份用户偏好设置，又不想引入 Pinia 或 Vuex 这种重型方案；
• 第三方 SDK 集成封装：比如接入 Sentry 错误监控、阿里云 OSS 上传、或内部微前端通信总线，需要统一初始化、错误兜底和 API 映射。

注意，这里说的“插件”和浏览器插件（如 Vue Devtools）、VS Code 插件（如 Todo Tree）、CLI 工具插件（如@vue/cli-plugin-unit-jest）完全不是一回事。Vue 插件是纯 JavaScript 模块，它不操作 DOM、不修改浏览器环境、不生成新进程——它只和 Vue 应用实例打交道。所以当你看到热搜词里混着vue.js devtools插件下载 edge、todo-tree: failed to find vscode-ripgrep这类内容时，请立刻划清边界：那些是开发工具链的附属品，而本篇讲的，是你自己写的、跑在用户浏览器里的、决定业务逻辑走向的“代码级扩展”。

我做过一个统计：在 2023 年上线的中大型 Vue 3 项目中，平均每个项目包含 3.7 个自定义插件——其中 1.2 个用于请求层封装（含拦截、重试、错误统一处理），0.9 个用于 UI 组件增强（如v-permission指令控制按钮显隐），0.8 个用于埋点与监控（自动上报 PV/UV、性能指标、JS 错误堆栈）。这些插件没有出现在package.json的 dependencies 里，却实实在在撑起了项目的稳定性和可维护性。它们不是炫技，而是工程化落地的刚需。

所以，如果你正面临这些场景：
✅ 新项目启动，想提前规划好可复用的能力基座；
✅ 老项目越来越臃肿，utils/目录下塞满了request.js、router.js、auth.js，每次改一个就要全局 grep；
✅ 团队协作时，新人总在问“这个$message是哪里来的？”、“v-loading指令为啥在 A 页面生效，B 页面报错？”；
✅ 或者你只是想彻底搞懂app.use()底层到底做了什么——那么这篇内容就是为你写的。它不教你怎么配 Webpack，不讲 Vite 插件开发，更不涉及任何构建时的魔法；它只聚焦一件事：用最朴素的 JavaScript，写出 Vue 框架真正认可的、可预测的、可测试的扩展模块。

2. 插件设计核心：Vue 3 的插件机制到底在做什么

2.1 插件函数的签名与执行时机：install(app, options?)不是约定，而是契约

Vue 官方文档里那句“插件必须暴露一个install方法”常被误解为一种风格约定。实际上，这是 Vue 框架在源码层面硬编码的调用契约。我们来看app.use()的核心逻辑（基于 Vue 3.4 源码简化）：

// 简化版 app.use 实现逻辑 function use(plugin: Plugin, ...options: any[]) { // 1. 检查 plugin 是否为对象且有 install 方法 if (isObject(plugin) && plugin.install) { plugin.install(this, ...options) } // 2. 如果 plugin 是函数，则直接调用 else if (isFunction(plugin)) { plugin(this, ...options) } // 3. 其他情况抛出错误 else { throw new Error(`plugin must be a function or an object with install method`) } }

关键点在于：Vue 不关心你的插件叫什么名、放哪个目录、是否导出 default，它只认两件事——要么是带install方法的对象，要么是函数本身。这意味着你可以这样写插件：

// 方式一：函数式插件（最常用） export default function myPlugin(app, options = {}) { console.log('插件已安装，app 实例:', app) } // 方式二：对象式插件（适合需导出多个方法的场景） export default { install(app, options) { app.config.globalProperties.$myMethod = () => { /* ... */ } } }

但绝不能这样写：

// ❌ 错误：没有 install 方法，也不是函数 export const myPlugin = { init() { /* ... */ } // Vue 会直接报错 } // ❌ 错误：导出的是一个类，未提供 install export class MyPlugin { constructor(options) { /* ... */ } }

为什么 Vue 要强制这个契约？答案藏在它的设计哲学里：插件必须明确声明“我将对当前应用实例做什么”，而不是被动等待被注入。这避免了像某些框架那样，插件通过require或import自动触发副作用，导致初始化顺序不可控、调试困难。app.use()的调用位置，就是插件生效的精确时间点——它永远发生在createApp()之后、mount()之前，确保插件能安全访问和修改应用实例的所有配置项。

提示：app.use()支持链式调用，但不支持重复安装同一插件。Vue 内部会用Set缓存已安装插件的标识（通常是plugin.__installed标记），第二次调用会静默忽略。这点在开发调试时很关键：如果你改了插件代码却没生效，先检查是不是main.js里写了两次app.use(myPlugin)。

2.2 插件能操作的四大核心接口：全局属性、指令、组件、依赖注入

一个 Vue 插件能做的所有事情，都围绕app实例的四个关键属性展开。这不是 Vue 的“功能列表”，而是其响应式系统与组件模型耦合后自然形成的扩展入口。理解这四点，你就掌握了 95% 的插件开发场景。

2.2.1app.config.globalProperties：给所有组件实例挂载“公共方法”

这是最直观的扩展方式，相当于给每个this添加属性。比如实现一个全局提示方法：

export default function createMessagePlugin(options = {}) { const { duration = 3000, position = 'top-right' } = options // 创建一个可复用的提示函数 const showMessage = (text, type = 'info') => { // 这里可以调用你封装的 UI 组件，比如 ElMessage 或自研 Toast const message = document.createElement('div') message.className = `message-${type} ${position}` message.textContent = text document.body.appendChild(message) setTimeout(() => { message.remove() }, duration) } // 挂载到全局属性 app.config.globalProperties.$message = showMessage // 同时挂载到应用上下文（Vue 3.2+ 推荐方式） app.config.globalProperties.$message.success = (text) => showMessage(text, 'success') app.config.globalProperties.$message.error = (text) => showMessage(text, 'error') }

使用时，在任意组件中：

<script setup> import { getCurrentInstance } from 'vue' // 在 setup() 中访问 const instance = getCurrentInstance() instance?.proxy?.$message.success('操作成功！') // 或在模板中直接使用（需启用 compat 模式或 Vue 2 语法） <template> <button @click="$message.info('点击了按钮')">点我</button> </template>

⚠️ 注意事项：

• globalProperties挂载的是非响应式值。如果你挂载一个对象，后续修改该对象属性不会触发视图更新（因为 Vue 不会对this.xxx做响应式代理）。若需响应式数据，应使用provide/inject（见 2.2.4）。
• 挂载函数时，this指向的是当前组件实例，而非插件函数自身。所以showMessage内部若需访问组件 data，必须显式传参，不能依赖this。

2.2.2app.directive()：注册全局指令，让v-xxx拥有魔力

指令是 Vue 最强大的 DOM 操作抽象。一个自定义指令能做的事情，远超v-if/v-for这些内置指令。比如实现一个防抖点击指令：

export default function createDebouncePlugin(options = {}) { const { delay = 300 } = options app.directive('debounce', { // 指令绑定到元素时调用 mounted(el, binding) { let timer = null const handler = () => { if (timer) clearTimeout(timer) timer = setTimeout(() => { // binding.value 是 v-debounce="handleClick" 中的 handleClick 函数 if (typeof binding.value === 'function') { binding.value() } }, delay) } // 绑定原生 click 事件 el.addEventListener('click', handler) // 将 handler 存储在 el 上，便于 unmounted 时移除 el._debounceHandler = handler }, // 指令所在组件卸载前调用 unmounted(el) { if (el._debounceHandler) { el.removeEventListener('click', el._debounceHandler) } } }) }

使用方式极其简洁：

<template> <!-- 点击时自动防抖，无需在 methods 里写额外逻辑 --> <button v-debounce="handleSubmit">提交</button> <!-- 支持传参 --> <button v-debounce:[delay]="handleSubmit">提交（延迟500ms）</button> </template>

实操心得：指令的binding对象包含value（指令值）、arg（参数，如v-focus:input中的input）、modifiers（修饰符，如v-on:click.stop.prevent中的stop/prevent），这是实现高阶指令的关键。我曾用v-permission指令结合后端返回的权限码数组，一行代码控制按钮显隐，比在v-if里写v-if="user.permissions.includes('user:delete')"清晰十倍。

2.2.3app.component()：注册全局组件，消除import和components选项的冗余

当某个组件被高频复用（如LoadingSpinner、EmptyState、PageHeader），每次都 import + components 注册，既繁琐又易遗漏。插件可一键全局注册：

import LoadingSpinner from './components/LoadingSpinner.vue' import EmptyState from './components/EmptyState.vue' export default function createUIPlugin() { app.component('LoadingSpinner', LoadingSpinner) app.component('EmptyState', EmptyState) // 也可以注册带前缀的组件名，避免命名冲突 app.component('MyButton', () => import('./components/MyButton.vue')) }

使用时，无需任何 import：

<template> <LoadingSpinner v-if="loading" /> <EmptyState v-else-if="!data.length" /> <MyButton @click="handleClick">确定</MyButton> </template>

⚠️ 注意：全局组件注册不支持异步组件的动态导入语法（即() => import(...)）在app.component()中会立即执行，导致首屏加载变慢。正确做法是注册一个同步包装组件，内部再做懒加载：

app.component('AsyncChart', { // 这是一个同步组件定义 async setup() { const Chart = await import('./components/Chart.vue') return () => h(Chart.default) } })

2.2.4app.provide()：提供响应式依赖，让inject()能拿到“活数据”

这是 Vue 3 中最被低估、却最强大的插件能力。provide/inject解决的是跨多层组件传递响应式状态的问题，而app.provide()让这个能力在应用级别生效。比如，你想让所有组件都能访问当前用户信息，并且当用户登录状态变化时，所有依赖它的组件自动更新：

import { ref, reactive } from 'vue' export default function createUserPlugin(initialUser = null) { // 创建响应式用户状态 const user = ref(initialUser) const userInfo = reactive({ name: '', avatar: '', permissions: [] }) // 提供两个 key：一个是 ref，一个是 reactive 对象 app.provide('user', user) // 提供 ref，inject 后可 .value app.provide('userInfo', userInfo) // 提供 reactive，inject 后直接用 // 同时挂载一个登录方法到全局属性，方便调用 app.config.globalProperties.$login = (userData) => { user.value = userData Object.assign(userInfo, userData) } }

在任意子组件中：

<script setup> import { inject } from 'vue' // 注入响应式数据 const user = inject('user') // 是 ref，需 user.value const userInfo = inject('userInfo') // 是 reactive，直接 userInfo.name // 使用 computed 保持响应式 const userName = computed(() => user.value?.name || '游客') </script> <template> <div>欢迎 {{ userName }}</div> <img :src="userInfo.avatar" alt="头像" /> </template>

优势在于：provide的数据是响应式且可跨组件树共享的，比globalProperties更适合状态管理。而且，provide的 key 可以是 Symbol，彻底避免字符串 key 冲突——这是我团队内部插件的强制规范。

3. 从零实现一个生产级插件：权限控制插件v-permission

3.1 需求拆解：为什么权限指令不能只靠v-if

在后台管理系统中，“按钮权限”是最典型的场景。新手常写：

<template> <!-- ❌ 错误示范：逻辑分散，难以维护 --> <button v-if="user.permissions.includes('user:create')">新增用户</button> <button v-if="user.permissions.includes('user:edit')">编辑用户</button> <button v-if="user.permissions.includes('user:delete')">删除用户</button> </template>

问题在于：

• 重复代码：每个按钮都要写一遍user.permissions.includes()；
• 硬编码权限码：'user:create'散落在各处，重构时极易漏改；
• 无降级策略：当权限校验失败，按钮只是隐藏，但用户可能仍能通过 URL 直接访问对应功能；
• 无法统一审计：谁在什么时候请求了哪些权限，无法集中记录。

一个健壮的权限插件，必须同时解决展示控制、行为拦截、权限码标准化、审计日志四个维度。下面，我们一步步实现它。

3.2 核心架构设计：三层分离，各司其职

我采用“策略模式 + 配置驱动”的设计，将插件拆为三个部分：

这种分层让插件具备极强的可扩展性：未来要支持 RBAC（角色）、ABAC（属性）模型，只需新增策略类，无需改动指令逻辑。

3.3 实现策略层：可插拔的权限校验引擎

// strategies/permission-strategy.js class PermissionStrategy { // 默认策略：权限码数组中包含任一目标码 static includes(permissions, target) { if (!Array.isArray(target)) target = [target] return target.some(code => permissions.includes(code)) } // 精确匹配：必须完全相等 static exact(permissions, target) { if (!Array.isArray(target)) target = [target] return target.every(code => permissions.includes(code)) } // 通配符匹配：支持 'user:*'、'system:admin:*' static wildcard(permissions, target) { if (!Array.isArray(target)) target = [target] return target.some(pattern => { return permissions.some(perm => { if (pattern.includes('*')) { const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$') return regex.test(perm) } return perm === pattern }) }) } } export default PermissionStrategy

这个策略类的设计亮点在于：

• 静态方法：无需实例化，直接调用，减少内存开销；
• 统一接口：所有策略方法签名一致(permissions, target)，便于插件内部统一调度；
• 可测试性强：每个策略可单独单元测试，例如：

// test/strategies.test.js import PermissionStrategy from '../strategies/permission-strategy' describe('PermissionStrategy', () => { const userPerms = ['user:create', 'user:read', 'system:admin'] it('includes should match any permission', () => { expect(PermissionStrategy.includes(userPerms, 'user:create')).toBe(true) expect(PermissionStrategy.includes(userPerms, ['user:delete', 'user:create'])).toBe(true) }) it('wildcard should support *', () => { expect(PermissionStrategy.wildcard(userPerms, 'user:*')).toBe(true) expect(PermissionStrategy.wildcard(userPerms, 'system:admin:*')).toBe(true) }) })

3.4 实现配置层：让插件行为可配置、可审计

// config/permission-config.js const DEFAULT_CONFIG = { // 校验策略，默认使用 includes strategy: 'includes', // 权限码来源，默认从 provide 的 'user' 中取 permissions 字段 source: 'user', // 无权限时的行为：'hidden'（隐藏）、'disabled'（禁用）、'remove'（移除 DOM） mode: 'hidden', // 是否开启审计日志（console 或上报服务） audit: false, // 无权限时的降级显示文案（仅 mode='disabled' 时有效） fallbackText: '暂无权限', // 自定义审计处理器 auditHandler: (code, result, element) => { if (result === false) { console.warn(`[Permission Audit] Element ${element.tagName} denied access to ${code}`) } } } export class PermissionConfig { constructor(options = {}) { this.config = { ...DEFAULT_CONFIG, ...options } // 支持动态更新配置 this.update = (newOptions) => { Object.assign(this.config, newOptions) } } get(key) { return this.config[key] } } // 导出单例，确保全局配置一致 export const permissionConfig = new PermissionConfig()

配置层的价值在于：它让插件不再是“写死的逻辑”，而是“可配置的服务”。比如在测试环境，你可以开启audit: true，所有权限拒绝都会打印日志；在线上环境，关闭审计，提升性能。source配置则支持权限数据来自不同地方——可以是provide的user，也可以是piniastore，甚至是一个全局变量window.APP_PERMISSIONS，只需在插件初始化时指定即可。

3.5 实现指令层：将策略与配置注入 DOM

// directives/permission-directive.js import PermissionStrategy from '../strategies/permission-strategy' import { permissionConfig } from '../config/permission-config' import { inject } from 'vue' export default { // 指令绑定时调用 mounted(el, binding) { const { value: targetCodes, modifiers } = binding const { mode, strategy, source, audit, auditHandler } = permissionConfig.config // 1. 获取权限数据源 let permissions = [] try { if (source === 'user') { const user = inject('user') permissions = user?.value?.permissions || [] } else if (typeof source === 'function') { permissions = source() || [] } else { permissions = source || [] } } catch (e) { console.error('[v-permission] Failed to get permissions from source:', source, e) permissions = [] } // 2. 执行策略校验 const checkResult = PermissionStrategy[strategy]?.(permissions, targetCodes) ?? false // 3. 根据 mode 执行 DOM 操作 if (!checkResult) { switch (mode) { case 'hidden': el.style.display = 'none' break case 'disabled': el.disabled = true if (el.tagName === 'BUTTON' || el.tagName === 'INPUT') { el.setAttribute('title', permissionConfig.get('fallbackText')) } break case 'remove': el.remove() break } } // 4. 审计日志 if (audit && !checkResult) { auditHandler(targetCodes, checkResult, el) } // 5. 将校验结果缓存到元素上，供 updated 钩子使用 el._permissionResult = checkResult }, // 当指令值更新时调用（如 v-permission="dynamicCodes"） updated(el, binding) { const { value: targetCodes } = binding const { mode, strategy, source } = permissionConfig.config // 重新获取权限数据并校验 let permissions = [] try { if (source === 'user') { const user = inject('user') permissions = user?.value?.permissions || [] } else if (typeof source === 'function') { permissions = source() || [] } else { permissions = source || [] } } catch (e) { permissions = [] } const checkResult = PermissionStrategy[strategy]?.(permissions, targetCodes) ?? false if (checkResult !== el._permissionResult) { // 恢复原始状态 if (el._permissionResult === false) { switch (mode) { case 'hidden': el.style.display = '' ; break case 'disabled': el.disabled = false ; break } } // 应用新状态 if (!checkResult) { switch (mode) { case 'hidden': el.style.display = 'none' ; break case 'disabled': el.disabled = true ; break } } el._permissionResult = checkResult } } }

这个指令的精妙之处在于：

• 错误防御强：对inject失败、权限数据不存在、策略方法不存在等情况都做了兜底，避免因插件异常导致整个页面白屏；
• 状态缓存：用el._permissionResult缓存上次校验结果，updated钩子中只在结果变化时才操作 DOM，避免不必要的重绘；
• 灵活降级：mode: 'disabled'时，不仅禁用元素，还添加title提示，用户体验更友好；
• 审计闭环：auditHandler支持自定义上报逻辑，比如发送到 Sentry 或内部监控平台。

3.6 插件主入口：整合三层，暴露统一 API

// index.js import PermissionDirective from './directives/permission-directive.js' import { permissionConfig } from './config/permission-config.js' // 主插件函数 export default function createPermissionPlugin(options = {}) { // 初始化配置 permissionConfig.update(options) // 注册全局指令 app.directive('permission', PermissionDirective) // 可选：提供一个全局方法，用于程序化权限校验 app.config.globalProperties.$hasPermission = (codes) => { const { strategy, source } = permissionConfig.config let permissions = [] try { if (source === 'user') { const user = inject('user') permissions = user?.value?.permissions || [] } else if (typeof source === 'function') { permissions = source() || [] } else { permissions = source || [] } } catch (e) { permissions = [] } return PermissionStrategy[strategy]?.(permissions, codes) ?? false } // 返回一个对象，方便外部调用（如在 setup 中） return { hasPermission: (codes) => app.config.globalProperties.$hasPermission(codes), updateConfig: (newOptions) => permissionConfig.update(newOptions) } } // 同时导出配置类和策略类，方便高级用户定制 export { PermissionConfig, PermissionStrategy }

使用方式变得极其简单：

// main.js import { createApp } from 'vue' import App from './App.vue' import createPermissionPlugin from './plugins/permission' const app = createApp(App) // 安装插件，传入配置 app.use(createPermissionPlugin({ strategy: 'wildcard', mode: 'disabled', audit: import.meta.env.DEV, auditHandler: (code, result, el) => { // 开发环境上报到控制台，生产环境可发到监控服务 if (!result) { console.warn(`[PERMISSION DENIED] ${code} on ${el.tagName}`) } } })) app.mount('#app')

在组件中：

<template> <!-- 基础用法 --> <button v-permission="['user:create']">新增用户</button> <!-- 多权限，满足其一即可 --> <button v-permission="['user:edit', 'user:delete']">编辑/删除</button> <!-- 通配符 --> <button v-permission="'user:*'">用户管理</button> <!-- 动态权限码 --> <button v-permission="dynamicCodes">动态按钮</button> </template> <script setup> import { ref } from 'vue' const dynamicCodes = ref(['user:read']) </script>

4. 插件发布与工程化实践：从本地开发到 npm 包

4.1 目录结构设计：清晰、可扩展、符合社区惯例

一个成熟的 Vue 插件，目录结构必须兼顾可读性、可维护性和可发布性。我推荐这套经过多个项目验证的结构：

my-vue-plugin/ ├── src/ # 源码主目录 │ ├── index.js # 插件主入口，导出 default install 函数 │ ├── directives/ # 全局指令 │ │ └── permission-directive.js │ ├── strategies/ # 权限策略类 │ │ └── permission-strategy.js │ ├── config/ # 配置管理 │ │ ├── permission-config.js │ │ └── index.js # 导出配置类和默认实例 │ └── utils/ # 工具函数（如深克隆、类型判断） │ └── helpers.js ├── tests/ # 单元测试 │ ├── unit/ │ │ ├── directive.test.js │ │ └── strategy.test.js │ └── integration/ │ └── plugin.test.js ├── examples/ # 使用示例（可运行的 demo 项目） │ └── vite-app/ # 基于 Vite 的最小示例 ├── types/ # TypeScript 类型定义 │ └── index.d.ts ├── package.json # 包元信息，重点配置 exports 字段 ├── README.md # 详细文档：安装、使用、API、贡献指南 └── rollup.config.js # 构建配置（推荐 Rollup，轻量且对 ESM 友好）

关键设计点：

• exports字段：在package.json中精确声明入口，让打包工具（Vite/Webpack）能按需加载：

{ "exports": { ".": { "import": "./dist/my-vue-plugin.esm.js", "require": "./dist/my-vue-plugin.cjs.js" }, "./directive": { "import": "./dist/directive.esm.js", "require": "./dist/directive.cjs.js" } } }

这样用户既可以import plugin from 'my-vue-plugin'，也可以import { permissionDirective } from 'my-vue-plugin/directive'，按需引入，减小包体积。

• types字段：指向类型定义文件，让 TypeScript 用户获得完整类型提示：

{ "types": "./types/index.d.ts" }

• examples/目录：不是摆设。我要求每个插件的examples/vite-app必须能npm run dev直接运行，且覆盖所有 API 用法。这既是文档，也是集成测试。

4.2 构建配置：Rollup 打包的 5 个关键配置项

Vue 插件通常不需要复杂构建，Rollup 足够轻量高效。以下是rollup.config.js的核心配置：

import resolve from '@rollup/plugin-node-resolve' import commonjs from '@rollup/plugin-commonjs' import { terser } from 'rollup-plugin-terser' import vue from '@vitejs/plugin-vue' export default [ // ESM 构建（供现代打包工具使用） { input: 'src/index.js', output: { file: 'dist/my-vue-plugin.esm.js', format: 'es', exports: 'named' }, plugins: [ resolve(), commonjs(), terser({ compress: { drop_console: true } }) // 生产环境移除 console ] }, // CJS 构建（供 CommonJS 环境，如 Node.js 测试） { input: 'src/index.js', output: { file: 'dist/my-vue-plugin.cjs.js', format: 'cjs', exports: 'named' }, plugins: [resolve(), commonjs()] }, // UMD 构建（供 CDN 直接引入，如 unpkg） { input: 'src/index.js', output: { file: 'dist/my-vue-plugin.umd.js', format: 'umd', name: 'MyVuePlugin', globals: { 'vue': 'Vue' // 告诉 Rollup，vue 是外部依赖，不要打包进去 } }, plugins: [resolve(), commonjs()], external: ['vue'] // 明确声明外部依赖 } ]

关键点解析：

• external: ['vue']：这是最重要的配置。Vue 插件绝不应该打包 Vue 本身，否则会导致应用中存在两个 Vue 实例，引发响应式失效、事件不触发等严重问题。external告诉 Rollup：“vue 是宿主环境提供的，别动它”。
• globals配置：在 UMD 构建中，name: 'MyVuePlugin'会让插件在全局挂载window.MyVuePlugin，globals: { 'vue': 'Vue' }则告诉 Rollup，当代码中import { ref } from 'vue'时，去window.Vue上找，而不是打包一份 Vue。
• terser压缩：drop_console: true移除所有console.*，避免插件代码在生产环境输出调试日志。

构建命令写在package.json：

{ "scripts": { "build": "rollup -c", "dev": "rollup -c -w", // 监听模式，开发时实时编译 "test": "vitest" } }

4.3 发布流程：从npm login到npm publish的 7 步 checklist

发布一个 npm 包，看似一步npm publish，实则背后有严格的质量门禁。我的标准 checklist 如下：

1. ✅ 本地构建验证：运行npm run build，检查dist/目录下是否生成了.esm.js、.cjs.js、.umd.js三个文件，且大小合理（一个基础插件通常 < 5KB）。

2. ✅ 类型检查：运行tsc --noEmit，确保types/index.d.ts与源码完全匹配，无类型错误。

3. ✅ 单元测试全覆盖：运行npm test，指令逻辑、策略校验、配置更新等核心路径必须 100% 覆盖。我用 Vitest，覆盖率报告必须 ≥ 95%。

4. ✅ 示例项目验证：进入examples/vite-app，运行npm install && npm run dev，手动测试所有