查看学习笔记
ARTICLE

Webpack构建工具配置详解

从entry、output到loaders、plugins、devServer,搞懂前端工程化的核心。

Webpack构建工具配置详解

Webpack构建工具配置详解

Webpack 是前端工程化绕不开的工具,尽管 Vite、esbuild 等"新势力"崛起,但大量存量项目与脚手架仍以 Webpack 为基础。理解 Webpack 的核心配置,对维护老项目、读懂脚手架生成的代码都至关重要。本文按 entry → output → loaders → plugins → devServer 的顺序,配练习示例。

一、Webpack 的核心概念

  • Entry:入口,构建依赖图的起点。
  • Output:输出,告诉 Webpack 把打包结果放哪。
  • Loader:把非 JS 文件(CSS、图片、TS)转换成 Webpack 能识别的模块。
  • Plugin:扩展 Webpack 功能,从打包优化到环境变量注入。
  • Mode:development / production / none,决定内置优化。
  • Module / Chunk / Bundle:模块是源码单元,Chunk 是打包过程中的块,Bundle 是最终输出。
理解 Webpack 一句话:把一切视为模块,从入口出发递归构建依赖图,最后输出静态资源。

二、最简配置

const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  }
};

三、Entry 配置

// 单入口
entry: './src/index.js'

// 多入口(多页应用)
entry: {
  home: './src/home.js',
  about: './src/about.js'
}

四、Output 配置

output: {
  path: path.resolve(__dirname, 'dist'),
  filename: '[name].[contenthash:8].js',  // 内容hash,便于长效缓存
  clean: true,                              // 构建前清空输出目录
  publicPath: '/'                           // 资源引用前缀
}

占位符说明:[name] 入口名、[hash] 编译hash、[contenthash] 内容hash、[chunkhash] chunk hash。生产推荐 [contenthash],文件不变就不变 hash,缓存命中率最高。

五、Loaders:处理非 JS 文件

1. Babel:转译 ES6+

npm install -D babel-loader @babel/core @babel/preset-env

module: {
  rules: [
    {
      test: /\.js$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: { presets: ['@babel/preset-env'] }
      }
    }
  ]
}

2. CSS 系列

npm install -D css-loader style-loader

{
  test: /\.css$/,
  use: ['style-loader', 'css-loader']  // 从右往左执行
}

// 提取 CSS 到独立文件(生产环境)
npm install -D mini-css-extract-plugin
{
  test: /\.css$/,
  use: [MiniCssExtractPlugin.loader, 'css-loader']
}

3. Sass/Less

npm install -D sass-loader sass

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

4. 静态资源(图片/字体)

Webpack 5 内置 Asset Modules,无需 file-loader/url-loader。

{
  test: /\.(png|jpg|gif|svg)$/,
  type: 'asset',           // 自动选择:小于 8kb 内联,大于则文件
  parser: {
    dataUrlCondition: { maxSize: 8 * 1024 }
  }
}

六、Plugins:扩展构建能力

1. HtmlWebpackPlugin:自动生成 HTML

const HtmlWebpackPlugin = require('html-webpack-plugin');

plugins: [
  new HtmlWebpackPlugin({
    template: './public/index.html',
    filename: 'index.html',
    inject: 'body',           // 把 script 插到 body 末尾
    minify: true              // 生产环境压缩 HTML
  })
]

2. MiniCssExtractPlugin:提取 CSS

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

plugins: [
  new MiniCssExtractPlugin({
    filename: 'css/[name].[contenthash:8].css'
  })
]

3. DefinePlugin:注入环境变量

const webpack = require('webpack');

plugins: [
  new webpack.DefinePlugin({
    'process.env.API_BASE': JSON.stringify('https://api.example.com')
  })
]

4. CleanWebpackPlugin / CopyWebpackPlugin

Webpack 5 的 output.clean: true 已取代 CleanWebpackPlugin;CopyWebpackPlugin 用于把 public 目录的静态文件原样拷贝到 dist。

七、DevServer:开发体验

devServer: {
  static: './dist',
  port: 3000,
  open: true,                  // 自动打开浏览器
  hot: true,                   // 热模块替换
  historyApiFallback: true,    // SPA 路由回退到 index.html
  proxy: {                     // 接口代理,解决跨域
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true
    }
  }
}

八、优化配置

1. 代码分割

optimization: {
  splitChunks: {
    chunks: 'all',           // 同步+异步都分割
    cacheGroups: {
      vendors: {
        test: /[\\/]node_modules[\\/]/,
        name: 'vendors',
        chunks: 'all'
      }
    }
  }
}

2. 摇树优化(Tree Shaking)

生产模式默认开启,配合 package.json 的 "sideEffects": false 移除未使用的代码。

3. 压缩

const TerserPlugin = require('terser-webpack-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

optimization: {
  minimize: true,
  minimizer: [new TerserPlugin(), new CssMinimizerPlugin()]
}

九、完整配置示例

// webpack.prod.js
const path = require('path');
const { Merge } = require('webpack-merge');
const base = require('./webpack.base');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
const TerserPlugin = require('terser-webpack-plugin');

module.exports = Merge(base, {
  mode: 'production',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'js/[name].[contenthash:8].js',
    clean: true
  },
  module: {
    rules: [
      { test: /\.css$/, use: [MiniCssExtractPlugin.loader, 'css-loader'] }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({ filename: 'css/[name].[contenthash:8].css' })
  ],
  optimization: {
    splitChunks: { chunks: 'all' },
    minimizer: [new TerserPlugin(), new CssMinimizerPlugin()]
  }
});

十、常见踩坑

  1. loader 顺序:从右往左、从下往上执行,写反了会报错。
  2. path 与 publicPath:path 是输出到磁盘的位置,publicPath 是浏览器引用资源的前缀。
  3. hash 选用:生产环境用 contenthash,避免无关改动导致缓存失效。
  4. devServer 不刷新:检查 hot 配置,或文件是否在监听范围。
  5. 构建慢:用 thread-loader 多线程、cache: { type: 'filesystem' } 持久化缓存。

十一、Webpack vs Vite

Vite 利用浏览器原生 ESM,开发启动秒级,无需打包;生产仍用 Rollup 打包。新项目优先选 Vite,老项目维护或对兼容性要求高仍可用 Webpack。两者并不互斥——理解 Webpack 的概念对学 Vite 同样有帮助。

十二、小结

Webpack 的配置看似复杂,本质就是把"入口→处理→输出"三段流程声明化表达。先把 entry/output/loader/plugin 四个核心概念吃透,再看具体场景按需引入第三方插件,构建效率与产物质量都能稳步提升。即便未来 Vite 全面取代 Webpack,这套工程化思维也会让你受益终身。

返回列表