封装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 }))
      );
    },
  ],
  build: {
    transpile: ['@my/ui', 'vuetify'],
  },
});

方案验证 #

1. Peer依赖要求：组件库仅声明Vuetify为peer依赖，不会将其打包进库文件，完全由消费应用提供。
2. 自动导入与摇树优化：组件库编译时会自动插入用到的Vuetify组件的导入语句，Nuxt项目的vite-plugin-vuetify也会处理自身代码的自动导入，最终打包时只会包含实际用到的组件，摇树优化生效。
3. 消费应用无需手动导入依赖：用户只需安装组件库和Vuetify，配置好Nuxt的Vuetify插件即可，无需手动导入组件库用到的Vuetify组件。

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