webpack examples 示例工程全景解析：目录结构、构建机制与全量示例索引

本篇指南以 examples/README.md 为主体，完整梳理 webpack 仓库示例工程的分类索引与每个示例覆盖的技术点，并结合 buildAll.js、build-common.js 和 template-common.js 等配套脚本，讲清楚“示例目录长什么样、如何构建、README 中的输出结果是如何被自动生成的”。读完后可独立构建任意单个示例或全量示例，并理解示例文档中代码快照背后的模板机制。

examples 目录的角色与总览

examples/ 是 webpack 仓库内面向使用者与贡献者的实战示例集合，examples/README.md 充当总目录，按主题归类了 20 多个大类（Chunk、Code Splitting、DLL、Harmony、WebAssembly、Web Worker 等）下的 70 余个具体示例目录。每个示例目录都是一个可独立编译的最小工程，覆盖：

• 模块与依赖：CommonJS、Harmony（ES Module）、CoffeeScript 等模块写法；
• 代码分割：从最简单的动态 import() 到按 chunk 命名、显式 vendor chunk、HTTP/2 激进拆分；
• 资源处理：loader 用法、WebAssembly（含 Emscripten 与 top-level await）、Web Worker；
• 库与发布形态：multi-part library、DLL、externals、模块联邦；
• 高级特性：scope hoisting、side effects 标注、source map、require.context / require.resolve、多编译器、混合路由等。

README 末尾还有一则社区约定：如果你认为缺少某个示例，请以 issue 形式反馈（见 examples/README.md “Requests” 一节）。

单个示例的目录结构约定

以 examples/commonjs 为例，一个典型示例目录包含以下文件：

文件	作用
example.js	入口源文件，示例的主体逻辑
其他源文件	被依赖的模块（如 examples/commonjs/increment.js、examples/commonjs/math.js）
template.md	带占位符的文档模板，编译后生成 README.md
webpack.config.js	该示例专属的 webpack 配置（多数示例有）
build.js	构建入口，绝大多数示例仅一行 require("../build-common")
README.md	由构建流程自动生成的文档，内嵌源码与编译产物快照

构建产物的约定是 dist/ 目录（默认输出文件名 output.js，publicPath 为 dist/）。例如 examples/commonjs/README.md 就完整展示了 example.js、increment.js、math.js 三个文件如何通过 require 组成依赖链，以及打包后 dist/output.js 中 webpackBootstrap、__webpack_modules__、模块工厂函数等产物结构。

如何构建示例：完整操作步骤

examples/README.md “Building an Example” 一节给出了 4 步操作，这里保持原文步骤并结合仓库实际脚本补充说明：

1. 在项目根目录运行 yarn 安装依赖；
2. 在项目根目录运行 yarn setup 完成仓库初始化；
3. 在项目根目录运行 yarn add --dev webpack-cli 安装 CLI（示例构建依赖 webpack-cli，缺失时构建脚本会直接抛出 “Please install webpack-cli at root.” 错误）；
4. 进入具体示例目录运行 node build.js，例如 cd examples/commonjs && node build.js。

批量构建方面，根目录 package.json 定义了脚本：

"build:examples": "cd examples && node buildAll.js"

buildAll.js 的工作方式是：通过 examples.js 扫描 examples/ 下所有含 template.md 的子目录，逐个执行 cd <dirname> && node build.js，并按 persistent-caching 示例追加一次额外构建；任一失败则在结尾抛出 <n> examples failed 错误。

构建机制源码解析：build.js 背后的三阶段流程

每个示例的 build.js 通常只有 require("../build-common") 一行，真正的工作集中在 examples/build-common.js。它按序执行三次编译并回写文档：

1. --mode production --env production（production 结果）
2. --mode development --env development --devtool none（development 结果）
3. --mode none --env none --output-pathinfo verbose（无 mode 结果）

每次编译都以 node ../bin/webpack.js 子进程方式调用本仓库的 webpack CLI，并附加一组“展示细节”参数：

• --stats-reasons --stats-used-exports --stats-provided-exports：显示模块依赖原因与导出使用情况；
• --stats-chunks --stats-modules-space 99999 --stats-chunk-origins：显示 chunk 明细与模块来源；
• --output-public-path "dist/"、--entry ./example.js --output-filename output.js：统一入口与产物名；
• 支持通过全局变量 NO_TARGET_ARGS、NO_REASONS、NO_STATS_OPTIONS、NO_PUBLIC_PATH、STATS_COLORS 关闭对应参数，便于不同示例定制输出。

编译成功后，stdout 会先做归一化再替换进模板：日期替换为 XXXX-XX-XX、时间替换为 XXXX:XX:XX、webpack x.y.z 替换为 webpack X.X.X，保证生成的文档不随时间与版本漂移。

template.md 的占位符与文档生成

examples/template-common.js 定义了文档模板的核心机制：

• replaceResults：将 __{stdout}__ 替换为本次编译的控制台输出，将 __{dist/output.js}__ 这类占位符替换为对应文件的实际内容，支持 production: / development: 前缀区分三种构建模式的结果；
• replaceBase：把绝对路径归一化（当前目录变 ./、仓库根变 (webpack)）、去除 [webpack-cli] 日志行、抹掉 in N ms 计时与超长 data URL、把 .chunkhash. 还原为 .[chunkhash]. 占位写法，并把 72 字符注释块包裹的 webpack runtime 代码折叠成 <details> 折叠块，避免产物快照淹没文档。

因此你在 examples/commonjs/README.md 等文档中看到的“编译输出 + 产物源码”都是真实构建结果而非手写快照——这也是示例文档可以长期与编译器行为保持一致的原因。

示例全量索引

以下按 examples/README.md 的分类逐一给出，链接均指向对应示例目录（其内部有源码与自动生成的 README）：

Aggressive Merging

• aggressive-merging：基于 SplitChunksPlugin 激进合并策略的 chunk 组织示例。

Chunk（chunk 拆分与命名）

• chunkhash：[chunkhash] 文件名与内容哈希的关系；
• common-chunk-and-vendor-chunk：common chunk 与 vendor chunk 的划分；
• explicit-vendor-chunk：显式指定 vendor chunk；
• extra-async-chunk、extra-async-chunk-advanced：额外异步 chunk 的基础与进阶用法；
• code-splitting-specify-chunk-name：magic comment 指定 chunk 名称；
• named-chunks：演示 named chunks 的合并行为；
• two-explicit-vendor-chunks：两个显式 vendor chunk 并存。

Code Splitting 与代码分割环境下的 context

• code-splitting：最基础的动态 import() 拆分；
• code-splitting-bundle-loader：通过 bundle-loader 实现拆分；
• code-splitting-harmony：Harmony 模块下的拆分；
• code-splitting-native-import-context、code-splitting-native-import-context-filter：原生 import() context 及过滤；
• code-splitted-require.context：代码分割环境中的 require.context；
• code-splitted-require.context-amd：AMD 下的同场景。

模块体系

• coffee-script：CoffeeScript 源码经 loader 编译后的打包；
• commonjs：最简单的 CommonJS 依赖链（example.js → increment.js → math.js）；
• mixed：CommonJS 与 AMD 混用；
• harmony：ES Module 基础用法；
• harmony-interop：Harmony 与 CommonJS 的互操作；
• harmony-library：以 ESM 形态输出库；
• harmony-unused：未使用导出的处理。

其他主题

• dll、dll-user：DLL 插件的两端（生成与消费）；
• externals：外部依赖不打包，运行时由环境提供；
• http2-aggressive-splitting：面向 HTTP/2 的激进拆分策略；
• hybrid-routing：混合路由场景；
• loader：loader 用法演示；
• multi-compiler：多编译器构建；
• multi-part-library：多文件（multi-part）库发布；
• multiple-entry-points：多入口 + 代码分割；
• require.context：require 中使用变量时自动创建 context；
• resource-hints：output.resourceHints 的各种变体（初始 chunk 自动 preload/prefetch、自定义数组、回调）以及各 parser 的 module.parser.<type>.urlHints 规则（new URL(...)、CSS url(...)、HTML <img src>），并在 SSR 中读取 stats.entrypoints[name].resourceHints；
• require.resolve：require.resolve 与 require.cache 的模块缓存清除技巧；
• scope-hoisting：模块作用域提升（concatenated module）；
• side-effects：sideEffects 标注与 tree-shaking；
• source-map：source map 配置效果对比；
• wasm-simple：最直接的 WebAssembly 模块导入；
• wasm-complex：wast-loader + top-level await 的复杂 WASM 场景；
• worker：用 webpack 构建 Web Worker。

仓库中实际存在、但总 README 未列入索引的示例

从目录结构看，examples/ 下还有更多示例目录被构建脚本自动覆盖（buildAll.js 以 template.md 存在与否判定示例），值得延伸阅读：

• 资产与 CSS：asset、asset-svg-data-uri、css；
• HTML 处理：html、html-csp、html-template、html-transform-tags、html-module-nomodule；
• 模块联邦：module-federation、module-library、module-worker、module-code-splitting；
• TS 与工具链：typescript、typescript-non-erasable；
• 缓存与性能：persistent-caching（buildAll.js 中额外构建一次）、lazy-compilation；
• HMR 与其他：hot-module-replacement、dotenv、define-config、many-pages、top-level-await、wasm-bindgen-esm、wasm-emscripten、wasm-simple-source-phase、stats-normal 等 stats 系列、virtual-modules、reexport-components、nodejs-addons、manifest-plugin、cjs-tree-shaking、common-chunk-grandchildren、code-splitting-depend-on-simple / code-splitting-depend-on-advanced、custom-javascript-parser、custom-json-modules、source-mapping-url、universal。

示例与自动化测试的衔接

示例目录不只用于展示，还参与 CI 验证：test/Examples.test.js 会遍历示例目录并执行各自 build.js，确保文档快照与真实编译行为同步。若你想核对某个示例的产物细节，推荐路径是：先读该目录的 template.md 了解文档占位结构，再看 README.md 中自动生成的三种模式（production / development / no-mode）输出，最后对照 webpack.config.js 与源码定位每个输出字段的来源。

小结

• examples/ 下每个目录都是“源码 + webpack.config.js + template.md + build.js + 生成版 README.md”的自包含工程，产物约定输出到 dist/；
• 单例构建：cd examples/<name> && node build.js；全量构建：根目录 npm run build:examples（即 cd examples && node buildAll.js），依赖 webpack-cli；
• README 中的编译输出与产物快照由 build-common.js 的三模式编译 + template-common.js 的占位符替换与归一化自动生成，时间戳、版本号、路径均经过脱敏，可放心作为行为参考。