Vue 3 公共组件从封装到全局注册的极简指南

在 Vue 项目中，我们经常会封装一些公共组件。如何让这些组件在项目中"随处可用"，而不用在每个文件中都引入？本文将展示最简洁的实现流程。

一、完整步骤（4步搞定）

第一步：创建组件

在 src/components/common目录下创建你的组件：

javascript 复制代码

<!-- MyButton.vue -->
<template>
  <button class="my-btn">
    <slot></slot>
  </button>
</template>

<script setup>
// 组件逻辑
</script>

<style scoped>
.my-btn {
  padding: 8px 16px;
  background: #1890ff;
  color: white;
  border: none;
  border-radius: 4px;
}
</style>

第二步：创建统一导出文件

在 src/components/common/index.js中导出所有公共组件：

javascript 复制代码

// 导出单个组件
export { default as MyButton } from './MyButton.vue'
export { default as MyDialog } from './MyDialog.vue'
export { default as MyInput } from './MyInput.vue'

// 注意：这里只是导出，不是注册！

第三步：创建插件（核心步骤）

创建 src/components/common/installer.js插件文件：

javascript 复制代码

// 导入所有组件
// 使用 ES6 的命名空间导入语法，从当前目录（'.'）导入所有导出
import * as CommonComponents from '.'

// 定义要注册的组件名数组
// 这个数组列出了需要通过插件全局注册的所有组件
// 注意：这里只写组件在 CommonComponents 对象中的属性名（字符串形式）
const components = ['MyButton', 'MyDialog', 'MyInput']

// Vue 插件必须提供 install 方法
// 这是 Vue.js 插件的标准格式：导出一个包含 install 方法的对象
// 当在 main.js 中调用 app.use(插件) 时，Vue 会自动执行这个 install 方法
export default {
  // Vue 插件的安装方法
  install(app) {
    components.forEach(key => {
      const component = CommonComponents[key]
      if (component) {
        // 调用 app.component() 方法全局注册组件
        // 参数1：注册的组件名（在模板中使用的标签名）
        // 参数2：组件定义（从 CommonComponents 中取出的 Vue 组件）
        // 注册后，在项目任何 .vue 文件的 <template> 中都可以直接使用 <MyButton>
        app.component(key, component)
      }
    })
  }
}

第四步：在 main.js 中安装插件

在项目入口文件中安装插件：

javascript 复制代码

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import CommonComponents from '@/components/common/installer' // 引入插件

const app = createApp(App)

// 一行代码安装所有公共组件
app.use(CommonComponents)

app.mount('#app')

完成！现在可以随处使用

在任意 .vue文件的模板中直接使用，无需引入：

javascript 复制代码

<template>
  <!-- 可以直接使用 -->
  <MyButton>点击我</MyButton>
  <MyDialog title="提示">内容</MyDialog>
</template>

<script setup>
// 这里不需要任何 import 语句！
</script>

二、原理解析

为什么这样就能全局使用？看这个简化流程：

组件创建 → 统一导出 → 插件批量注册 → 安装插件

↓ ↓ ↓ ↓

MyButton.vue index.js installer.js main.js

关键点：

插件机制 ：app.use(Plugin)会调用插件的 install方法
批量注册 ：在 install方法中调用 app.component()注册每个组件
一次安装，处处可用：安装后，组件注册到 Vue 实例的全局组件库中

三、常见问题

Q: 为什么我的组件不显示？

A: 检查：

组件是否在 components数组中
插件是否在 main.js中通过 app.use()安装
组件名是否正确（区分大小写）

Q: 注册后还能按需引入吗？

A: 可以。全局注册和按需引入不冲突，按需引入依然有效。

Q: 会影响打包体积吗？

A: 全局注册的组件都会打入主包，即使没用到。如果组件很多，建议：

只对高频组件全局注册
低频组件按需引入
或使用 unplugin-vue-components自动导入