1. 项目概述：为什么现在还要学手动搭 Webpack？

先说一个可能有点“反潮流”的观点：在 Vite 满天飞、零配置脚手架按秒生成项目的今天，我依然认为手动搭一遍 Webpack 是前端开发者绕不开的一课。原因很简单——你不亲手从 0 到 1 搭一次，就永远不知道npm run dev背后到底发生了什么，那些藏在 node_modules 里的依赖是怎么被串起来的，以及报错时那一大坨红色堆栈里，哪些信息真的有用、哪些只是噪音。

很多人刚开始学 Webpack 的时候，容易被“入门简单、配置地狱”这种矛盾描述搞懵。别被吓住。把一个项目从 0 到 1 搭起来，本质上就是把几个零散的 JS 文件、样式文件、图片资源，通过一套打包规则变成浏览器能直接执行的产物。这里面真正需要理解的核心理念不超过三个：入口（entry）、输出（output）、加载规则（rules）。如果你能把这三位祖宗伺候明白，剩下的一切都是在这条主线上做加法。

这篇文章面向的是那种“听说过 webpack 但自己一行配置都没写过”的开发者，也可能是被各种工程化项目裹挟、天天跑在现成脚手架之上却心里发虚的同学。我会用一套最小可用的配置作为起点，然后一步步把开发服务器、样式处理、代码分割、缓存优化这些真实项目里绕不开的能力加进去。每一处配置我都会解释为什么这么写，而不是让你抄完就跑。

我在这篇文章里用到的示例项目是虚构的“某前端教学示范项目”，不依赖任何第三方脚手架，从裸目录开始，一步步验证，最终产出一套可复用的开发环境模板。整个过程全程有输出验证，保证你看完之后，照着敲就能跑通。

2. 内容整体设计与思路拆解

2.1 先搞清楚 Webpack 到底在做什么

要搭建脚手架，第一步不是装依赖，而是理解打包的本质。我把这个过程类比成一个快递分拣中心：你的源码是零散的商品，Webpack 是传送带，而最终的浏览器是收件人。入口文件就是最初丢上传送带的那个包裹，它通过import、require语句告诉分拣系统“我还关联了哪些别的包裹”——这就是模块依赖图的构建过程。

传统方式下，浏览器加载 JS 是按<script>标签顺序执行的，一旦文件变多，你就要手动维护引入顺序，而且每个文件都会污染全局作用域。Webpack 把这一切变成了模块化语法，让你在开发时用import写代码，打包后自动生成一个或多个文件，并处理好依赖顺序。

这个思路拆解下来，包含几个核心点：首先，入口告诉 Webpack 从哪里开始读依赖图；其次，Loader 让 Webpack 能处理 JS 之外的资源，比如 CSS、图片、字体；最后，Plugin 则用来干预打包结果，比如压缩代码、生成 HTML、提取公共代码。三者缺一不可，后续所有配置都是围绕这三个维度展开的。

提示：刚接触时不要试图一次看懂全部配置，那是反人性的。你只需要记住每一步改动带来什么“结果差异”，动手验证一次，比看十遍文档都有用。

2.2 为什么选 Webpack 而不是别的工具

做这个最小化脚手架之前，我也犹豫过要不要直接上 Vite。对比下来，Vite 的冷启动确实快得离谱，基于原生 ESM 的开发模式很优雅。但在真实项目里，Webpack 的生态成熟度和配置项的兜底能力依然是压倒性的——特别是在你要处理复杂的代码分割策略、老项目迁移、或者需要精细控制产物体积的时候。

而且从学习角度说，Webpack 更像一个“方案齐全的定制平台”，你按需启用它的能力；而 Vite 更像一个“开箱即用的便利店”，很多东西帮你藏起来了。藏在背后确实省事，但也意味着你少了理解底层机制的机会。我的建议是：日常开发随便用 Vite 都没问题，但为了搞懂模块打包原理，至少完整地手动搭一次 Webpack，这笔时间花得值。

2.3 配置架构的整体规划

我在设计这套最小脚手架时，给自己定了三个原则：一是配置尽量少嵌套，平铺直叙，方便读者逐行看明白；二是开发环境和生产环境的能力必须分开，否则会在一些隐蔽的行为上栽跟头；三是所有配置文件的路径必须放在根目录的config文件夹里统一管理，不要散落在各个层级。

根据这三个原则，规划出的目录结构是这样的：

mock-project/ |── config/ | ├── webpack.common.js | ├── webpack.dev.js | └── webpack.prod.js |── src/ | ├── index.js | ├── style.css | └── utils/ | └── format.js |── public/ | └── index.html |── package.json

为什么不用单文件webpack.config.js？因为当项目复杂度起来之后，开发环境里的 devServer、source-map、热更新配置，和生产环境的代码压缩、缓存指纹、公共代码提取完全是两套逻辑，混在一起后只是看起来省事，一旦某个配置出问题排查起来极其头疼。拆分之后各管各的，通过webpack-merge把公共配置合并进来，逻辑清晰得多。

3. 核心细节解析与实操要点

3.1 入口和输出：脚手架的第一块地基

先说入口。入口文件是所有模块加载的起点，我的习惯是放在src/index.js，它唯一的职责就是把页面渲染所需的模块引入进来。这个文件里不要写太多业务逻辑，只做组装和挂载，比如创建一个实例、挂到某个 DOM 节点上。

输出配置里最关键的三个选项是path、filename、clean。path必须是绝对路径，所以我写的是path.resolve(__dirname, '../dist')。很多人第一次写的时候直接用相对路径，于是构建产物到处乱飞，这就是第一个坑。

// config/webpack.common.js const path = require('path'); module.exports = { entry: './src/index.js', output: { path: path.resolve(__dirname, '../dist'), filename: '[name].[contenthash:8].js', clean: true, }, };

这里解释一下我为什么用[contenthash:8]而不是[name].js。生产环境希望浏览器能长效缓存 JS 文件，只有文件内容变化时文件名才变化，否则就命中缓存。contenthash是基于文件内容生成的哈希值，内容没变哈希就不变，这样用户不需要重复下载未改动的文件。clean: true是让每次构建前自动清空dist目录，如果不用它，旧文件会一直残留，最终目录越来越脏。

3.2 Loader 的正确打开方式

Loader 是 Webpack 里最让人迷惑但又最核心的概念。把它理解为“翻译器”就对了：Webpack 默认只懂 JS，遇见别的资源就派给对应 Loader 去翻译成它认识的东西。

开发中最常用的是babel-loader，用来把 ES6+ 语法翻译成兼容性更好的 ES5。但注意，babel-loader只是搭了个桥梁，真正做语法转换的是@babel/preset-env。如果不装这个 preset，Babel 根本不知道要把代码转成什么样。

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

这里最容易被忽略的一个坑是exclude: /node_modules/。如果不排除第三方库，Babel 会把 node_modules 里成百上千个文件也逐一转译，不仅构建慢到怀疑人生，而且有些库本身是用编译后代码发布的，再转译一次可能引入诡异错误。

3.3 样式处理和资源模块

处理样式也是一个团队标准动作：css-loader+style-loader。css-loader负责解析 CSS 文件里的@import、url()这些语法，把它们变成 JS 可识别的模块；style-loader则负责把打包后的 CSS 以<style>标签的形式注入 HTML。

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

为什么开发环境用style-loader而生产环境要把 CSS 单独抽离？因为生产环境追求并行加载和缓存优化，CSS 文件应该通过<link>标签独立加载，而不是塞进 JS 里让用户先下载完脚本再渲染样式。这就涉及一个插件 ——MiniCssExtractPlugin，等到了生产环境配置那一节我再细说。

图片和字体这些静态资源，Webpack 5 内置了asset module，不再像老版本那样依赖url-loader和file-loader。配置方式很简单：

{ test: /\.(png|jpe?g|gif|svg)$/i, type: 'asset', parser: { dataUrlCondition: { maxSize: 4 * 1024, }, }, }

type: 'asset'的意思是：文件小于 4KB 时转成 base64 内嵌，减少网络请求；超过 4KB 就作为单独文件输出。这里有个经验之谈，不要把这个阈值设得太大，否则 HTML 和 JS 里塞满几十 KB 的巨型 base64 字符串，打包产物体积会失控。

3.4 开发服务器的热更新原理

开发时需要一个能实时反馈的服务器，这就是webpack-dev-server的舞台。它和传统后端服务器最大的区别在于：资源保存在内存里而不是物理磁盘上，改代码后通过 WebSocket 通知浏览器，实现局部更新或整页刷新。

我第一次配置 devServer 时犯过一个低级错误：只写了port和open就以为完事了，结果改了代码页面完全不更新。后来才发现是没开hot: true，虽然 devServer 启动了，但没有热模块替换能力，我只能手动刷新。别小看这个细节，它直接决定开发体验。

// config/webpack.dev.js const { merge } = require('webpack-merge'); const common = require('./webpack.common.js'); module.exports = merge(common, { mode: 'development', devtool: 'eval-cheap-module-source-map', devServer: { port: 3000, hot: true, open: true, historyApiFallback: true, }, });

关于devtool，我推荐开发环境用eval-cheap-module-source-map，它兼顾了构建速度和报错定位精度，能在控制台准确显示错误发生在源码第几行。生产环境的 source-map 策略要复杂得多，涉及源码风险暴露问题，一般默认none或者只在需要排查线上问题时临时开启。

4. 实操过程与核心环节实现

4.1 从零开始：初始化项目和安装依赖

实操第一步，创建一个目录并初始化 npm：

mkdir mock-project && cd mock-project npm init -y

然后安装核心依赖：

npm i -D webpack webpack-cli webpack-dev-server webpack-merge npm i -D babel-loader @babel/core @babel/preset-env npm i -D html-webpack-plugin style-loader css-loader mini-css-extract-plugin

这里注意html-webpack-plugin是干什么用的：它根据public/index.html作为模板，在构建时自动把打包后的 JS、CSS 文件用<script>和<link>标签注入进去。如果你不装它，就得手动在 HTML 里硬编码文件名，而文件名带有随机哈希值的，每次构建都得改一次，纯粹是自虐。

下载完成后，在package.json里加上 scripts：

"scripts": { "build": "webpack --config config/webpack.prod.js", "dev": "webpack serve --config config/webpack.dev.js" }

4.2 搭建公共配置与开发环境实测

先写webpack.common.js，把入口、输出、loader 这些两个环境都要用的配置集中起来。然后写webpack.dev.js合并公共配置并加上 devServer。完整配置我在前面已经贴了关键代码，这里的重点是跑起来验证。

按照前面给出的配置创建文件后，执行npm run dev，终端里会输出编译成功信息，浏览器自动打开http://localhost:3000。如果页面空白，第一件事永远是从控制台开始排查，而不是猜。常见的空页面原因：入口文件路径写错、HTML 模板里没有 div 容器、或者 JS 报错导致挂载失败。

我在这个阶段习惯做一个 5 秒自测：修改src/index.js里的一段文案，保存，看浏览器页面是否自动更新。如果更新了，说明热更新链路没问题；如果没有，检查hot: true是否配置，以及有没有在模块代码顶部加if (module.hot)相关逻辑——不过现代版本 Webpack 的hot: true已经默认可以处理大多数场景，不需要手动写。

4.3 生产构建：压缩、CSS 抽离与缓存策略

生产环境的核心诉求是“体积更小、速度更快、缓存更聪明”。先看配置文件：

// config/webpack.prod.js const { merge } = require('webpack-merge'); const common = require('./webpack.common.js'); const MiniCssExtractPlugin = require('mini-css-extract-plugin'); module.exports = merge(common, { mode: 'production', output: { filename: '[name].[contenthash:8].js', }, module: { rules: [ { test: /\.css$/, use: [MiniCssExtractPlugin.loader, 'css-loader'], }, ], }, plugins: [ new MiniCssExtractPlugin({ filename: '[name].[contenthash:8].css', }), ], optimization: { splitChunks: { chunks: 'all', }, }, });

这里出现了mode: 'production'，它的意义不只是标记环境，Webpack 会默认启用一系列优化——比如压缩 JS、tree-shaking 掉没有被引用的代码、限制警告输出等。写不写mode，构建出来的产物体积差距极其明显。

MiniCssExtractPlugin在上一节提到过，现在生产配置里正式登场。注意它必须同时出现在plugins和module.rules[].use里——loader 负责在编译阶段收集 CSS，plugin 负责生成物理 CSS 文件。

splitChunks是我在主配置里加的代码分割策略。chunks: 'all'会把公共依赖（比如 react、lodash 这类）抽离成单独文件，避免每个业务文件都重复打包一份。这个策略对体积优化效果很明显——第一次使用的时候，我的一个示例 bundle 从 800KB 降到了 350KB 左右。

4.4 完整流程验证与产物检查

配置完成后，执行npm run build。此时dist目录下生成的文件应该类似：

dist/ |── index.html |── js/ | ├── main.4f8b3a2c.js | └── vendors.7b9c01e5.js └── css/ └── main.3c4d5e6f.css

这里有个我很想强调的点：构建完成后，一定要亲手打开dist/index.html看一眼，确认引用的文件名和物理文件名一致。虽然html-webpack-plugin的原理决定了它不会出错，但亲眼确认一次，比日后被缓存问题折腾半小时要划算得多。

我在这个虚拟项目里特意验证了一个场景——改一行 CSS 文字颜色后重新构建，发现只有 CSS 文件名的哈希值变了，JS 文件的哈希值没有变。这就是正确的缓存策略应该有的表现：只让改变的文件失效，其余文件继续命中缓存。

5. 常见问题与排查技巧实录

5.1 必踩的坑之一：Loader 顺序引发的血案

Loader 的执行顺序是右到左、后写先执行。很多人第一次写style-loader和css-loader的时候，习惯按直觉顺序写：

// 错误的写法 use: ['css-loader', 'style-loader']

结果是样式根本不会注入。原因在于css-loader先处理完 CSS 语法后，会把结果传给style-loader，后者希望收到的是“一段 CSS 字符串”，结果收到的却是“JS 模块的导出”，当然无从下手。顺序写反这个坑我踩过，而且当时还怀疑是 node 版本问题，排查了半小时，最后才发现只是顺序写反了。

5.2 必踩的坑之二：路径问题与 publicPath

在 devServer 里一切正常，但构建后部署到服务器子路径（比如https://example.com/app/）时，页面样式全丢、图片 404。这时 90% 的原因是output.publicPath没有配置。

output: { path: path.resolve(__dirname, '../dist'), publicPath: '/app/', }

publicPath决定了打包产物里所有相对路径引用的前缀。不少项目上线踩到这个问题，就是因为本地开发用根路径，部署时却挂在子路径下。这个坑很难通过本地测试暴露，唯一的办法就是提前在配置里留好变量，通过环境变量注入，不要等部署时才手忙脚乱。

5.3 必踩的坑之三：热更新失效且不报错

这是一个特别折磨人的现象——一切配置看起来都对，控制台无任何错误，但改代码后页面就是纹丝不动。我在一个教学项目里复现这个场景时，发现原因是 devServer 和业务代码不在同一个进程下运行时出现了状态不同步。

排查思路从三步入手：第一步检查 URL 是否访问的是 devServer 的端口，而不是直接双击 HTML 文件；第二步确认hot: true确实在生效，看浏览器控制台有没有[webpack-dev-server] Hot Memcached之类的日志；第三步检查entry是否漏掉了webpack/hot/dev-server。如果以上都确认无误，干脆试试把所有 node_modules 删掉重新安装，很多玄学问题其实都是依赖版本不一致导致的。

5.4 常见错误速查表

5.5 独家避坑补充：分包策略的最佳实践

说到splitChunks，我多提一嘴。新手容易犯的错误是以为它就是“把代码拆分出去”这么简单，导致配置完以后页面请求数暴增，每个文件又小又碎，依然可能降低加载速度。追根究底，splitChunks要解决的是“公共代码提取”，不是“所有代码切碎”。

真正合理的策略是先把node_modules里的第三方库打成 vendors 文件——因为这部分代码极少变动，拆分后可以长期被浏览器缓存——再把业务代码和依赖框架分开。想更精细，可以用cacheGroups手动为react、lodash这类大体积库单独分组。但它的默认配置已经能覆盖大多数情况，不要过度设计。

还有一个我常用的观察指标：构建完成后去dist目录看每个文件的大小，重点关注 200KB 以上的文件。如果出现超大文件，优先检查是不是某个依赖库被打进去了，或者开启了source-map但没有设置devtool。

6. 实操心得与后续扩展建议

这套脚手架虽然是从教学视角搭建的，但它完全可以作为你在真实项目里做定制化开发的基础模板。以我个人的经验来说，有几个方向上值得继续扩展。

第一是环境变量的正确管理。用dotenv加上DefinePlugin，可以优雅地注入接口地址、调试开关等环境信息。生产构建时不带NODE_ENV=production、或者把development和production混在一个配置里，会在打包结果里埋下很多雷。

第二是 TypeScript 支持。在现有基础上加ts-loader或babel-loader的 TS preset，再配一份tsconfig.json即可。注意ts-loader的 transpileOnly 模式能大幅提升编译速度，但你可能需要额外开启 fork-ts-checker 来做类型检查。

第三是缓存策略的进阶。Webpack 5 自带filesystem cache，开启后连续构建的速度提升非常明显。第一次构建大概 12 秒，第二次可能直接到 2 秒以内。对于团队项目来说，这个提升体验几乎是无感的，但确实能省下大量 CI 构建时间。

最后想聊聊多做练习的心态。我见过不少同学看了一堆教程，觉得配置是背下来的，碰上一个疑难问题就手足无措。实际上，Webpack 的配置不是玄学，每个字段都有明确的文档说明和社区实践可供参考。你可以犯错的成本其实很低——最差的结果就是重新安装依赖，再跑一次构建而已。

在调试过程中，我建议你保持一个习惯：每次只改一个配置项，然后观察构建结果的变化。这个习惯能帮你快速排除变量，也能让你对每个配置的作用形成肌肉记忆。别把五个没验证过的配置一次性塞进来，报错了根本不知道是谁的锅。

这套最小化的配置对你来说，可能只是一篇教程的产物；但如果你按照我的路径，把它当作一个可以反复折腾的沙盒，你会在这里面找到很多比框架使用技巧更有长期价值的认知：什么是模块化、什么是依赖图、什么是资源优化，这些结晶无论未来用什么工具都能迁移过去。