Webpack 配置方法

FreeGuideOnline 最新 2026-07-15

bash npm init -y


接着安装 `webpack` 和 `webpack-cli` 作为开发依赖：

```bash
npm install --save-dev webpack webpack-cli

最简配置

在项目根目录下创建 webpack.config.js 文件，这是 Webpack 的核心配置文件。一个最简单的配置如下：

const path = require('path');

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

在终端运行：

npx webpack

Webpack 会从 ./src/index.js 开始打包，并在 dist 文件夹下生成 bundle.js。

核心概念详解

入口（Entry）

入口起点指示 Webpack 应该使用哪个模块来开始构建其内部依赖图。
可以配置单个或多个入口，甚至可以根据不同页面拆分。

// 单个入口（简写）
entry: './src/main.js',

// 对象形式（更灵活，适用于多页应用）
entry: {
  app: './src/app.js',
  admin: './src/admin.js',
},

输出（Output）

output 用于控制 Webpack 如何以及在哪里输出打包文件。对于多入口，可以使用占位符来防止文件名冲突：

output: {
  filename: '[name].[contenthash].js',
  path: path.resolve(__dirname, 'dist'),
  clean: true, // 每次构建前清理 /dist 文件夹
},
  • [name] 会被替换为入口的 key（如 app、admin）。
  • [contenthash] 基于文件内容生成的哈希，利于长期缓存。

Loader（加载器）

Webpack 本身只理解 JavaScript 和 JSON 文件。Loader 让 Webpack 能够处理其他类型的文件，并将它们转换为有效模块。

Loader 在 module.rules 中配置，有两个必要属性：

  • test：匹配文件的正则表达式。
  • use：指定使用的 loader 名称。

处理 CSS

安装 style-loader 和 css-loader：

npm install --save-dev style-loader css-loader

配置：

module: {
  rules: [
    {
      test: /\.css$/i,
      use: ['style-loader', 'css-loader'],
    },
  ],
},

Loader 的执行顺序是从右向左（或从下到上）。这里先由 css-loader 解析 CSS 中的 @import 和 url()，再由 style-loader 将样式注入到 DOM 中。

处理图片与字体

Webpack 5 内置了 资源模块（Asset Modules），无需额外 loader。例如处理图片：

{
  test: /\.(png|jpg|gif|svg)$/i,
  type: 'asset/resource', // 将文件发送到输出目录，并导出一个 URL
}

使用 Babel 转译 ES6+

安装 babel-loader 和相关预设：

npm install --save-dev babel-loader @babel/core @babel/preset-env

配置：

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

Plugin（插件）

Loader 用于转换特定类型的模块，而插件则可以执行范围更广的任务，如打包优化、资源管理、注入环境变量等。

使用插件时，先通过 require（或 import）引入，然后在 plugins 数组中添加实例。

HtmlWebpackPlugin

用于自动生成 HTML 文件，并自动引入打包后的 bundle。

安装：

npm install --save-dev html-webpack-plugin

配置：

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

plugins: [
  new HtmlWebpackPlugin({
    template: './src/index.html', // 模板文件
    title: 'My App',
  }),
],

MiniCssExtractPlugin

将 CSS 提取到独立文件中，而不是用 style-loader 动态注入。

安装：

npm install --save-dev mini-css-extract-plugin

配置时，用 MiniCssExtractPlugin.loader 替代 style-loader：

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

module: {
  rules: [
    {
      test: /\.css$/i,
      use: [MiniCssExtractPlugin.loader, 'css-loader'],
    },
  ],
},
plugins: [
  new MiniCssExtractPlugin({
    filename: '[name].[contenthash].css',
  }),
],

模式（Mode）

mode 参数用于启用 Webpack 内置的优化。可选值：'development'、'production'、'none'。

mode: 'development', // 或 'production'
  • development：启用有助于调试的工具（如更详细的错误信息）。
  • production：启用一系列优化，如代码压缩、tree shaking、作用域提升等。

通常，我们会为不同环境创建不同的配置文件（如 webpack.dev.js 和 webpack.prod.js），并使用 webpack-merge 合并通用配置。

开发服务器

使用 webpack-dev-server 可以提供一个简单的 Web 服务器，并实现实时重新加载。

安装：

npm install --save-dev webpack-dev-server

在 webpack.config.js 中添加 devServer 配置：

devServer: {
  static: './dist',
  hot: true,          // 启用热模块替换
  port: 3000,
},

在 package.json 中添加脚本：

"scripts": {
  "start": "webpack serve --open"
}

运行 npm start 即可启动开发服务器。

Source Map 与调试

通过 devtool 属性控制是否以及如何生成 source map。常用选项：

  • eval-source-map：开发环境推荐，速度较快且映射精确。
  • source-map：生产环境可选用，生成完整的 .map 文件，但构建较慢。
devtool: 'inline-source-map', // 示例

代码分割（Code Splitting）

代码分割允许你将代码拆分成多个 bundle，可以按需加载或并行加载，实现更小的初始下载量。

多入口方式

如前面 entry 配置所示，直接多个入口会产生多个 bundle，但这种方式重复模块较多。

SplitChunksPlugin

Webpack 内置的 SplitChunksPlugin 可以将公共依赖提取到单独 chunk。

在 optimization 中配置：

optimization: {
  splitChunks: {
    chunks: 'all',
  },
},

这样，来自 node_modules 的库会被提取到一个名为 vendors 的 chunk 中（默认行为）。

动态导入

使用 ES 的动态 import() 语法，Webpack 会自动对导入的模块进行代码分割：

// 示例：懒加载模块
button.addEventListener('click', () => {
  import('./math').then(math => {
    console.log(math.add(1, 2));
  });
});

Webpack 会为 ./math 生成一个独立的 chunk，并在点击时按需加载。

缓存与文件指纹

为了利用浏览器缓存，可以通过 [contenthash] 占位符让文件名基于内容变化：

output: {
  filename: '[name].[contenthash].js',
},

提取 CSS 时同样使用 [contenthash]，确保只有内容变化的文件会被重新下载。

环境变量与生产/开发区分

可以在配置文件中导出一个函数，从而根据命令行环境变量切换行为：

module.exports = (env, argv) => {
  const isProduction = argv.mode === 'production';

  return {
    mode: isProduction ? 'production' : 'development',
    // 根据 isProduction 决定是否使用 MiniCssExtractPlugin 等
  };
};

常用优化手段

Tree Shaking

Webpack 在生产模式下默认开启 tree shaking，它会移除 JavaScript 中未引用的代码（dead code）。确保你的代码使用 ES 模块（import/export）语法，并且不执行副作用（或在 package.json 中指定 "sideEffects": false）。

压缩

生产模式下，Webpack 5 会自动使用 TerserPlugin 压缩 JavaScript，使用 CssMinimizerPlugin 压缩 CSS。你可以手动配置 optimization.minimizer 来定制。

安装 CSS 压缩插件：

npm install --save-dev css-minimizer-webpack-plugin

配置：

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

optimization: {
  minimizer: [
    `...`, // 扩展 Webpack 5 的存在默认值
    new CssMinimizerPlugin(),
  ],
},

配置文件的分层与复用

对于大型项目，通常使用三个配置文件：

  • webpack.common.js：通用配置。
  • webpack.dev.js：开发专用配置。
  • webpack.prod.js：生产专用配置。

用 webpack-merge 合并：

npm install --save-dev webpack-merge

// webpack.dev.js
const { merge } = require('webpack-merge');
const common = require('./webpack.common.js');

module.exports = merge(common, {
  mode: 'development',
  devtool: 'inline-source-map',
  devServer: {
    static: './dist',
  },
});