Vue项目生成组件目录映射JSON失败，apply钩子未触发的解决方案

为什么自定义Webpack插件未执行？ #

1. 环境不匹配：如果你的项目是基于Vite（而非Vue CLI+Webpack），Webpack插件完全不会生效——Vite使用Rollup作为核心打包器，不兼容Webpack插件体系。你的配置中出现了build.rollupOptions，大概率是Vite项目，此时应该编写Vite插件而非Webpack插件。
2. 依赖缺失：原代码未导入path和fs模块，运行时会抛出错误，导致插件执行中断。
3. 插件注册逻辑：虽然你的configureWebpack函数看起来没问题，但如果Vue CLI合并配置时出现覆盖，也可能导致插件未被正确添加。

优化实现方式 #

情况1：Vite项目（推荐，现代Vue项目主流） #

编写Vite插件，利用Vite的钩子完成文件生成，支持递归遍历组件目录，代码更简洁：

import { defineConfig, Plugin } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
import fs from 'fs/promises'

// 生成组件映射的Vite插件
function componentsMapPlugin(): Plugin {
  return {
    name: 'vite-plugin-components-map',
    async buildStart() {
      const componentsDir = path.resolve(__dirname, 'src/components')
      const componentsMap: Record<string, string> = {}

      // 递归遍历所有.vue文件（排除index.vue）
      async function traverseDir(dir: string, relativePath = '') {
        const files = await fs.readdir(dir, { withFileTypes: true })
        for (const file of files) {
          const fullPath = path.join(dir, file.name)
          const relativeFullPath = path.join(relativePath, file.name)
          if (file.isDirectory()) {
            await traverseDir(fullPath, relativeFullPath)
          } else if (file.name.endsWith('.vue') && file.name !== 'index.vue') {
            const componentName = relativeFullPath.replace('.vue', '')
            // 转换为项目根目录相对路径，统一用/分隔
            componentsMap[componentName] = path.relative(__dirname, fullPath).replace(/\\/g, '/')
          }
        }
      }

      await traverseDir(componentsDir)
      await fs.writeFile(
        path.resolve(__dirname, 'componentsMap.json'),
        JSON.stringify(componentsMap, null, 2) // 格式化输出，可读性更好
      )
    }
  }
}

export default defineConfig({
  plugins: [vue(), componentsMapPlugin()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src/")
    }
  },
  build: {
    rollupOptions: {
      output: {
        format: 'es'
      }
    }
  },
})

情况2：Vue CLI（Webpack）项目 #

修复原Webpack插件的问题，优化代码逻辑：

import { defineConfig } from '@vue/cli-service'
import vue from '@vue/cli-plugin-vue'
import path from 'path'
import fs from 'fs/promises'
import type { Compiler } from 'webpack'

function createComponentsMapJsonPlugin() {
  return {
    apply: async (compiler: Compiler) => {
      // 选择beforeCompile钩子，在构建开始前生成文件，避免构建完成后才生成
      compiler.hooks.beforeCompile.tapPromise('CreateComponentsMapJsonPlugin', async () => {
        const componentsDir = path.join(__dirname, 'src/components')
        const componentsMap: Record<string, string> = {}

        // 递归遍历组件目录
        async function traverseDir(dir: string, relativePath = '') {
          const files = await fs.readdir(dir, { withFileTypes: true })
          for (const file of files) {
            const fullPath = path.join(dir, file.name)
            const relativeFullPath = path.join(relativePath, file.name)
            if (file.isDirectory()) {
              await traverseDir(fullPath, relativeFullPath)
            } else if (file.name.endsWith('.vue') && file.name !== 'index.vue') {
              const componentName = relativeFullPath.replace('.vue', '')
              componentsMap[componentName] = path.relative(__dirname, fullPath).replace(/\\/g, '/')
            }
          }
        }

        await traverseDir(componentsDir)
        await fs.writeFile(
          path.resolve(__dirname, 'componentsMap.json'),
          JSON.stringify(componentsMap, null, 2)
        )
      })
    }
  }
}

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src/")
    }
  },
  configureWebpack: (config) => {
    // 直接修改原配置，避免解构导致的引用丢失
    config.plugins?.push(createComponentsMapJsonPlugin())
  },
})

关键优化点 #

• 递归遍历：支持组件目录下的子文件夹，覆盖更多场景
• Promise化API：使用fs.promises替代回调，代码更简洁易维护
• 路径优化：生成项目根目录相对路径，而非绝对路径，更具通用性
• 格式化输出：JSON文件格式化后可读性更强
• 环境适配：分别针对Vite和Webpack给出适配方案，解决原插件不执行的核心问题

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