修复SPFx 1.21.1集成Vue 3.5.22的gulp配置与vue-loader问题

问题根源分析 #

1. 无清单生成问题：直接使用mergeConfig覆盖SPFx默认Webpack配置时，破坏了SPFx内置的清单生成规则与插件，导致/temp/build/manifests.js无输出且无报错。
2. .vue文件解析失败：缺少Vue 3对应的vue-loader配置及必要插件，Webpack无法识别.vue文件格式。

解决方案步骤 #

1. 安装必要依赖 #

首先安装Vue 3及配套的构建工具：

npm install vue@3.5.22 vue-loader@17.4.2 @vue/compiler-sfc --save
npm install @types/vue --save-dev

注意：Vue 3必须搭配vue-loader@17.x版本，@vue/compiler-sfc是Vue 3单文件组件的编译核心依赖。

2. 修正gulpfile.js配置 #

修改项目根目录的gulpfile.js，通过SPFx提供的additionalConfiguration扩展Webpack配置，而非直接覆盖：

const gulp = require('gulp');
const build = require('@microsoft/sp-build-web');
const { VueLoaderPlugin } = require('vue-loader');

// 扩展Webpack配置以支持Vue 3
build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfig) => {
    // 添加.vue文件的loader规则
    generatedConfig.module.rules.push({
      test: /\.vue$/,
      loader: 'vue-loader',
      options: {
        compilerOptions: {
          preserveWhitespace: false
        }
      }
    });

    // 必须添加VueLoaderPlugin（Vue 3的vue-loader强制要求）
    generatedConfig.plugins.push(new VueLoaderPlugin());

    // 让Webpack识别.vue扩展名
    if (!generatedConfig.resolve.extensions.includes('.vue')) {
      generatedConfig.resolve.extensions.push('.vue');
    }

    return generatedConfig;
  }
});

build.initialize(gulp);

3. 配置TypeScript支持.vue文件 #

• 在项目根目录的tsconfig.json中，修改compilerOptions：

{
  "compilerOptions": {
    // ...其他已有配置
    "types": ["vue"],
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

• 在src目录下创建vue.d.ts声明文件，内容如下：

declare module '*.vue' {
  import type { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

4. 重新构建并启动服务 #

执行以下命令清理缓存并启动服务：

gulp clean
gulp serve

内容的提问来源于stack exchange，提问作者Jesús López