人人都会AI编程

17.2 Webpack 构建 Vue 项目

更新时间：2026-07-11

虽然 Vite 已成为 Vue 3 的默认构建工具，但大量存量项目和企业级应用仍运行在 Webpack 之上。理解 Webpack 如何与 Vue 协同工作，对于维护老项目或需要深度定制构建流程的场景依然重要。

vue-loader：让 Webpack 认识 .vue 文件

Webpack 本身只理解 JavaScript 和 JSON，无法直接处理 .vue 单文件组件。vue-loader 就是解决这个问题的核心 loader。它会将 .vue 文件解析成三块独立的代码段，并分别交给对应的 loader 继续处理：

  • <template> → vue-template-compiler 预编译成渲染函数（或直接在 vue-loader 中处理）
  • <script> → babel-loader 转译 JS/TS
  • <style> → css-loader、sass-loader 等，支持 scoped 样式隔离

一个典型的 Webpack 配置片段如下：

// webpack.config.js
const { VueLoaderPlugin } = require('vue-loader')

module.exports = {
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      },
      {
        test: /\.js$/,
        loader: 'babel-loader',
        exclude: /node_modules/
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin()  // 必须添加，负责克隆其他规则并应用到 .vue 文件的对应块
  ]
}

VueLoaderPlugin 的作用：它的职责是复制你在 module.rules 中定义的与 .js、.css 等相关的 loader，并将其应用到 .vue 文件内对应的语言块上。这样你不需要为 .vue 再重复定义一遍 JS 和 CSS 的处理规则。

核心 Loader 与 Plugin 配置

除了 vue-loader，一个可用的 Vue + Webpack 项目通常还需要以下配置：

处理 CSS 预处理器

// 处理 SCSS
{
  test: /\.scss$/,
  use: ['style-loader', 'css-loader', 'sass-loader']
}

在 .vue 文件的 <style lang="scss"> 中写 SCSS 时，vue-loader 会自动应用这条规则。

资源文件处理（图像、字体）
Webpack 5 内置了 asset modules，不再需要 url-loader 或 file-loader：

{
  test: /\.(png|jpe?g|gif|svg)$/,
  type: 'asset',
  parser: {
    dataUrlCondition: {
      maxSize: 8 * 1024  // 小于 8KB 的图片转 base64
    }
  }
}

环境变量注入
使用 DefinePlugin 为应用注入编译时环境变量，例如 process.env.VUE_APP_API_BASE：

const webpack = require('webpack')
plugins: [
  new webpack.DefinePlugin({
    __VUE_OPTIONS_API__: true,      // 开启/关闭选项式 API 支持
    __VUE_PROD_DEVTOOLS__: false   // 生产环境关闭 DevTools
  })
]

HTML 模板
使用 html-webpack-plugin 自动生成入口 HTML 并注入打包后的脚本：

const HtmlWebpackPlugin = require('html-webpack-plugin')
plugins: [
  new HtmlWebpackPlugin({
    template: './public/index.html',
    title: 'My Vue App'
  })
]

Tree Shaking：剔除无用代码

Vue 3 的 API 设计天然支持 Tree Shaking。例如你只使用了 ref 和 computed，watch、onMounted 等未使用的导出就不会被打包。前提是 Webpack 的 mode 设置为 production，并且确保模块是 ESM 格式。

在 package.json 中指明副作用文件有助于 Tree Shaking 更安全地进行：

{
  "sideEffects": [
    "*.css",
    "*.scss"
  ]
}

这里的 sideEffects 告诉 Webpack：除了 CSS/SCSS 文件可能有全局副作用（因为它们可以影响样式，没有导出却被引用），其他文件都可以安全进行死代码消除。

对于组件库的按需引入（如 Element Plus），需要配合 babel-plugin-import 或确保库本身已经做好 Tree Shaking 适配。Vue 3 + Webpack 下，只需正常使用 ESM 版本的库并开启 production 模式，即可获得体积优化。

代码分割（Code Splitting）

Vue 项目最自然的代码分割方式是通过动态导入实现路由懒加载：

// router.js
const UserProfile = () => import('./views/UserProfile.vue')

Webpack 会将动态导入的模块拆分成独立的 chunk 文件，并在路由被访问时才加载，有效降低首屏包体积。

还可以利用 splitChunks 配置精细控制分包策略：

optimization: {
  splitChunks: {
    chunks: 'all',
    cacheGroups: {
      vendor: {
        test: /[\\/]node_modules[\\/]/,
        name: 'vendors',
        priority: 10,
        chunks: 'initial'
      },
      common: {
        minChunks: 2,
        priority: 5,
        reuseExistingChunk: true
      }
    }
  }
}

这样会将 node_modules 中引用的第三方库提取为一个稳定的 vendors 包，业务代码中重复引用超过两次的公共模块也会被提取。由于第三方库通常不会频繁变化，这有利于浏览器缓存。

打包优化实战

1. 压缩与混淆
Webpack 5 内置了 TerserWebpackPlugin，production 模式默认开启 JS 压缩。CSS 压缩可使用 css-minimizer-webpack-plugin：

const CssMinimizerPlugin = require('css-minimizer-webpack-plugin')
optimization: {
  minimizer: [
    '...',                    // 继承默认的 JS 压缩
    new CssMinimizerPlugin()  // CSS 压缩
  ]
}

2. 体积分析
使用 webpack-bundle-analyzer 直观查看包组成和重复依赖：

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin
plugins: [
  new BundleAnalyzerPlugin()  // 构建完成后自动打开分析页面
]

通过分析图可快速定位引入完整的 moment.js 而非 date-fns、图标库全量打包等问题。

3. 缓存策略
在文件名中利用内容哈希实现长效缓存：

output: {
  filename: 'js/[name].[contenthash:8].js',
  chunkFilename: 'js/[name].[contenthash:8].chunk.js'
}

只要文件内容不变，哈希就不变，浏览器可安全使用缓存。配合 SplitChunks 把稳定代码（如 vendor）单独打包，大多数访问都能命中缓存。

4. 排除不需要的解析
减少不必要的文件扫描，加快构建速度：

module: {
  noParse: /^(vue|vue-router|pinia)$/  // 这些库已经是编译好的，无需再解析
}

与 Vue CLI 的关系

实际项目中通常不需要从零手写上述配置——Vue CLI 在底层封装了完整的 Webpack 配置，并提供了 vue.config.js 进行自定义覆盖：

// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  configureWebpack: {
    plugins: [/* 额外插件 */]
  },
  chainWebpack: config => {
    // 链式修改 loader 规则
  }
})

Vue CLI 内部已经处理好了 vue-loader、CSS 预处理器、代码分割等最佳实践，大部分场景只需要在 vue.config.js 中做少量调整即可。

总结：Webpack 构建 Vue 项目的核心是 vue-loader + VueLoaderPlugin 的配合，再加上对 CSS、资源、环境变量的规则配置。通过 Tree Shaking、动态导入和合理的分包策略，可以生成体积小、缓存友好的生产包。尽管 Vite 已成为新项目首选，但掌握 Webpack 的这套体系，对维护现有项目和理解构建原理仍有现实意义。