封装Vuetify3组件库在Nuxt中使用时组件无法自动导入问题

问题背景 #

开发Vuetify 3组件库时，将Vuetify设为peer依赖，在Nuxt项目中使用时出现错误：

[Vue warn]: Failed to resolve component: v-btn If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.

临时方案是手动导入或全局注册Vuetify组件，但会导致包体积过大，需要满足以下三个条件的替代方案：

• 组件库仅将Vuetify作为peer依赖
• 消费应用可自动导入Vuetify组件并享受摇树优化
• 消费应用无需手动导入组件库用到的Vuetify依赖

原因分析 #

组件库编译时未处理Vuetify组件的自动导入逻辑，导致编译后的组件模板中仍保留 v-btn 这类原始标签；而Nuxt的 vite-plugin-vuetify 默认仅处理项目 src 目录内的代码，不会解析 node_modules 中组件库的模板标签，因此Vue无法识别这些组件。

解决方案 #

1. 调整组件库的Vite配置 #

在组件库的 vite.config.ts 中启用Vuetify的自动导入插件，同时确保Vuetify被标记为外部依赖，不打包进库文件：

import { fileURLToPath, URL } from 'node:url';
import { resolve } from 'node:path';
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vueJsx from '@vitejs/plugin-vue-jsx';
import vuetify from 'vite-plugin-vuetify';
export default defineConfig({
  plugins: [
    vue(),
    vueJsx(),
    // 启用Vuetify自动导入，关闭内置样式（由消费应用处理）
    vuetify({ autoImport: true, styles: 'none' }),
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
  build: {
    lib: {
      entry: resolve(__dirname, 'src/main.ts'),
      name: '@my/ui',
      fileName: 'my-ui',
    rollupOptions: {
      // 保留Vue和Vuetify为外部依赖
      external: ['vue', 'vuetify'],
      output: {
        globals: {
          vue: 'Vue',
          vuetify: 'Vuetify',

2. 组件库Package.json声明Peer依赖 #

确保 package.json 中明确声明Vuetify为peer依赖，提示消费应用安装对应版本：

{
  "peerDependencies": {
    "vue": "^3.3.0",
    "vuetify": "^3.0.0"

3. 优化Nuxt项目的Vuetify配置 #

修改Nuxt项目的 plugins/vuetify.ts ，移除全局注册所有组件的代码，依赖自动导入实现按需加载：

import 'vuetify/styles';
import { createVuetify } from 'vuetify';
export default defineNuxtPlugin((nuxtApp) => {
  const vuetify = createVuetify({
    // 无需手动注册components/directives，autoImport会自动处理
  nuxtApp.vueApp.use(vuetify);

Nuxt的 nuxt.config.ts 保持现有配置即可，确保 transpile 包含组件库和Vuetify：

import { defineNuxtConfig } from 'nuxt';
import vuetify from 'vite-plugin-vuetify';
export default defineNuxtConfig({
  css: ['@/assets/css/main.css'],
  modules: [
    async (options, nuxt) => {
      nuxt.hooks.hook('vite:extendConfig', (config) =>
        config.plugins.push(vuetify({ autoImport: true }))