从零打造一个Vue 3组件库：开发、打包与发布到NPM

作为一名前端开发者，开发一个自己的Vue 3组件库不仅能提升技术能力，还能为社区贡献力量。本文将带你从零开始，基于Vue
3和Vite，开发一个简单的UI组件库（包含一个按钮组件），并打包发布到NPM。文章涵盖项目搭建、组件开发、按需加载支持、测试与发布的全流程，适合想进阶Vue
3开发的你！欢迎关注我的博客和公众号（微信搜索：小贺前端笔记），更多干货和实战项目等你来发现！

为什么开发Vue 3组件库？

• 技术提升：深入理解Vue 3的响应式系统和组件封装。
• 项目复用：在多个项目中复用高质量组件，提升效率。
• 社区贡献：发布到NPM，获得社区反馈，积累个人影响力。

1. 项目初始化

我们使用Vite作为构建工具，因为它对Vue 3支持优秀，速度快且配置简单。

1.1 创建项目

npm create vite@latest my-vue3-ui --template vue
cd my-vue3-ui
npm install

1.2 安装必要依赖

组件库需要支持样式封装和按需加载，安装以下依赖：

npm install -D vite-plugin-dts @vitejs/plugin-vue sass

• vite-plugin-dts：生成TypeScript类型声明文件。
• @vitejs/plugin-vue：支持Vue单文件组件。
• sass：用于编写组件样式。

1.3 项目结构

创建一个清晰的目录结构，便于维护：

my-vue3-ui/
├── src/
│   ├── components/         # 组件目录
│   │   └── Button.vue      # 示例按钮组件
│   ├── index.ts            # 组件库入口
│   └── styles/             # 全局样式
│       └── index.scss      # 全局样式入口（可选）
├── vite.config.ts          # Vite配置文件
├── package.json
└── README.md

2. 开发一个按钮组件

我们以一个简单的Button组件为例，支持type（primary/success）和disabled属性。

2.1 创建Button.vue

在src/components/Button.vue中编写组件代码：

<template>
  <button :class="['my-button', `my-button--${type}`]" :disabled="disabled">
    <slot />
  </button>
</template>

<script setup lang="ts">
defineProps<{
  type?: 'primary' | 'success';
  disabled?: boolean;
}>();
</script>

<style lang="scss">
.my-button {
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
  transition: background-color 0.3s;

  &--primary {
    background-color: #409eff;
    color: white;
    &:hover {
      background-color: #66b1ff;
    }
  }

  &--success {
    background-color: #67c23a;
    color: white;
    &:hover {
      background-color: #85ce61;
    }
  }

  &:disabled {
    background-color: #c0c4cc;
    cursor: not-allowed;
  }
}
</style>

• 变更：移除 scoped 属性，确保样式可以被 Vite 提取到全局 CSS 文件（dist/style.css）。
• 使用 <script setup> 简化代码。
• 支持 type 和 disabled 属性，样式用 SCSS 实现主题化和 hover 效果。

2.2 导出组件

在src/index.ts中导出组件并提供install方法，支持全局注册：

import { App } from 'vue';
import Button from './components/Button.vue';

const components = [Button];

const install = (app: App) => {
  components.forEach((component) => {
    app.component(component.name || 'MyButton', component);
  });
};

export { Button };
export default { install };

• 注意：添加 component.name || 'MyButton'，防止组件未定义 name 属性时注册失败。

3. 配置Vite打包

为了让组件库支持按需加载和TypeScript，我们需要配置Vite。

3.1 修改vite.config.ts

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import dts from 'vite-plugin-dts';
import { resolve } from 'path';

export default defineConfig({
  plugins: [
    vue(),
    dts({ insertTypesEntry: true }),
  ],
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'MyVue3UI',
      fileName: 'my-vue3-ui',
      cssFileName: 'style', // 确保CSS文件名为style.css
    },
    rollupOptions: {
      external: ['vue'],
      output: {
        globals: {
          vue: 'Vue',
        },
      },
    },
    cssCodeSplit: false, // 合并所有CSS到一个文件
  },
});

• build.lib.cssFileName: 'style'：确保 CSS 输出为 dist/style.css。
• cssCodeSplit: false：将所有 CSS 合并到单一文件。
• external: ['vue']：将 Vue 设为外部依赖，避免打包到组件库中。

3.2 配置package.json

修改package.json，添加入口和类型声明：

{
  "name": "my-vue3-ui",
  "version": "0.1.0",
  "main": "./dist/my-vue3-ui.umd.js",
  "module": "./dist/my-vue3-ui.es.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/my-vue3-ui.es.js",
      "require": "./dist/my-vue3-ui.umd.js"
    },
    "./dist/style.css": "./dist/style.css"
  },
  "files": ["dist"],
  "scripts": {
    "build": "vite build",
    "publish": "npm publish --access public"
  },
  "peerDependencies": {
    "vue": "^3.0.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.0",
    "sass": "^1.70.0",
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.7.0"
  }
}

• 变更：添加 devDependencies，明确依赖版本，确保环境一致。
• exports：确保 CSS 文件可通过 import 'my-vue3-ui/dist/style.css' 引入。

4. 添加全局样式（可选）

在src/styles/index.scss中定义全局样式（当前为空，因为样式已内联在组件中）：

/* src/styles/index.scss */
/* 暂时为空，未来可添加全局样式 */

在src/index.ts中导入样式（可选）：

import './styles/index.scss';

• 说明：由于按钮样式已在 Button.vue 中定义，index.scss 当前为空。如果未来需要全局样式，可以在此添加。
• Vite 会自动提取 Button.vue 中的非 scoped 样式到 dist/style.css。

5. 测试组件库

在本地测试组件库是否正常工作。

5.1 创建测试页面

在src/App.vue中测试Button组件：

<template>
  <div>
    <MyButton type="primary">Primary Button</MyButton>
    <MyButton type="success" disabled>Success Button</MyButton>
  </div>
</template>

<script setup>
import { Button as MyButton } from './index';
</script>

运行 npm run dev，检查按钮的样式和功能是否正常（蓝色主按钮、绿色成功按钮、灰色禁用状态）。

5.2 本地链接测试

使用 npm link 测试组件库：

1. 在组件库目录运行：

   npm run build
   npm link
   

2. 创建一个新的 Vue 3 测试项目（如果没有）：

   npm create vite@latest test-project --template vue
   cd test-project
   npm install
   

3. 在测试项目中运行：

   npm link my-vue3-ui
   

4. 在测试项目的 src/main.ts 中导入并使用：

   import { createApp } from 'vue';
   import App from './App.vue';
   import MyVue3UI from 'my-vue3-ui';
   import 'my-vue3-ui/dist/style.css';
   
   const app = createApp(App);
   app.use(MyVue3UI);
   app.mount('#app');
   

5. 在测试项目的 src/App.vue 中使用组件：

   <template>
     <div>
       <MyButton type="primary">主按钮</MyButton>
       <MyButton type="success" disabled>成功按钮</MyButton>
     </div>
   </template>
   
   <script setup>
   import { Button as MyButton } from 'my-vue3-ui';
   </script>
   

6. 运行测试项目：

   npm run dev
   

   验证按钮是否显示正确样式。

6. 发布到NPM

6.1 登录NPM

确保你有NPM账号，运行：

npm login

6.2 打包与发布

npm run build
npm publish --access public

6.3 注意事项

• 确保 package.json 中的 name 唯一（建议改为 @yourname/my-vue3-ui）。
• 发布前运行 npm run build，检查 dist 目录是否包含 my-vue3-ui.es.js、my-vue3-ui.umd.js、style.css 和 index.d.ts。
• 更新版本号（npm version patch）后重新发布。

你在开发Vue组件库时遇到过哪些问题？欢迎在评论区分享你的经验！

相关推荐

想深入学习Vue 3和前端开发？以下是几篇值得一读的文章：
Vue 3 中的新特性：Suspense和Teleport
从初级到高级前端：如何写出高质量代码，迈向职业新高度