Init_Make_Seal：真正读懂 Webpack 核心流程

// 📍 lib/webpack.js — 入口函数（完整源码约 230 行）
// 关键函数：createCompiler() — L68~L120

const createCompiler = (rawOptions, compilerIndex) => {
    // Step 1: 配置标准化（去除无效属性、统一格式）
    let options = getNormalizedWebpackOptions(rawOptions);

    // Step 2: 应用基础默认值（mode、context、devtool 等）
    applyWebpackOptionsBaseDefaults(options);

    // Step 3: 配置拦截器处理（允许外部修改配置）
    let interception;
    ({ options, interception } = applyWebpackOptionsInterception(options));

    // Step 4: 创建 Compiler 实例
    const compiler = new Compiler(
        /** @type {string} */ (options.context),
        options
    );

    // Step 5: 注入 Node 环境插件（文件系统等基础能力）
    new NodeEnvironmentPlugin({
        infrastructureLogging: options.infrastructureLogging
    }).apply(compiler);

    // Step 6: 遍历用户 plugins，逐一执行 .apply(compiler)
    if (Array.isArray(options.plugins)) {
        for (const plugin of options.plugins) {
            if (typeof plugin === "function") {
                (plugin).call(compiler, compiler);
            } else if (plugin) {
                plugin.apply(compiler);
            }
        }
    }

    // Step 7: 应用最终默认值（含 mode 相关的优化默认值）
    const resolvedDefaultOptions = applyWebpackOptionsDefaults(
        options,
        compilerIndex
    );

    // Step 8: 【v5.106+ 新增】validate 钩子
    // 允许插件在编译前做最终的配置校验
    if (options.validate) {
        compiler.hooks.validate.call();
    }

    // Step 9: 触发环境就绪钩子
    compiler.hooks.environment.call();
    compiler.hooks.afterEnvironment.call();

    // Step 10: 【核心】根据配置动态注入内置插件
    new WebpackOptionsApply().process(options, compiler, interception);

    // Step 11: 初始化完成钩子
    compiler.hooks.initialize.call();

    return compiler;
};

// 📍 lib/WebpackOptionsApply.js
// process() 方法根据不同配置分支注入对应插件

process(options, compiler, interception) {
    // ① Entry 处理：根据 entry 类型注入 EntryPlugin 或 DynamicEntryPlugin
    new EntryOptionPlugin().apply(compiler);
    compiler.hooks.entryOption.call(options.context, options.entry);

    // ② Devtool 处理：根据 devtool 字符串组合注入对应插件（示意）
    if (options.devtool) {
        if (options.devtool.includes("eval") && options.devtool.includes("source-map")) {
            new EvalSourceMapDevToolPlugin(options.devtool).apply(compiler);
        } else if (options.devtool.includes("source-map")) {
            new SourceMapDevToolPlugin(options.devtool).apply(compiler);
        }
        // ... 更多组合（eval、cheap-module- 等）
    }

    // ③ Runtime 注入：注入运行时代码处理逻辑
    new RuntimePlugin().apply(compiler);

    // ④ 【v5 新增】experiments.lazyCompilation 处理
    if (options.experiments && options.experiments.lazyCompilation) {
        new LazyCompilationPlugin(options.lazyCompilation).apply(compiler);
    }

    // ⑤ 【v5 新增】experiments.css 处理
    if (options.experiments && options.experiments.css) {
        new CssModulesPlugin().apply(compiler);
    }

    // ⑥ 持久化缓存：cache.type === "filesystem" 时注入缓存插件
    //    （AddBuildDependenciesPlugin / MemoryCachePlugin / FileCachePlugin 等）
    if (options.cache && options.cache.type === "filesystem") {
        // ... 注入缓存相关插件
    }
}

// 📍 lib/Compiler.js — 构造函数中的 hooks 定义（L80~L160）

this.hooks = Object.freeze({
    // ===== 初始化阶段 =====
    initialize: new SyncHook([]),           // 编译器初始化完成
    validate: new SyncHook([]),             // [v5.106+] 配置校验
    environment: new SyncHook([]),          // 环境变量准备好
    afterEnvironment: new SyncHook([]),     // 环境设置完成后

    // ===== 编译阶段 =====
    beforeCompile: new AsyncSeriesHook(["params"]),
    compile: new SyncHook(["params"]),
    make: new AsyncParallelHook(["compilation"]),   // ⭐ 核心钩子！
    finishMake: new AsyncSeriesHook(["compilation"]),
    afterCompile: new AsyncSeriesHook(["compilation"]),

    // ===== 生成阶段 =====
    shouldEmit: new SyncBailHook(["compilation"]),
    emit: new AsyncSeriesHook(["compilation"]),
    assetEmitted: new AsyncSeriesHook(["file", "info"]),
    afterEmit: new AsyncSeriesHook(["compilation"]),

    // ===== 运行控制 =====
    beforeRun: new AsyncSeriesHook(["compiler"]),
    run: new AsyncSeriesHook(["compiler"]),
    watchRun: new AsyncSeriesHook(["compiler"]),
    done: new AsyncSeriesHook(["stats"]),
    // ... 更多 hooks
});

// 📍 lib/Compiler.js — compile() 方法（约 L1380）

compile(callback) {
    // 创建 CompilationParams（包含 NormalModuleFactory 和 ContextModuleFactory）
    const params = this.newCompilationParams();

    this.hooks.beforeCompile.callAsync(params, err => {
        if (err) return callback(err);

        this.hooks.compile.call(params);

        // ⭐ 创建 Compilation 对象 —— 单次构建过程的管理者
        const compilation = this.newCompilation(params);

        // ⭐⭐⭐ 触发 make 钩子 —— 进入「构建阶段」的入口
        this.hooks.make.callAsync(compilation, err => {
            if (err) return callback(err);

            this.hooks.finishMake.callAsync(compilation, err => {
                if (err) return callback(err);

                // 使用 process.nextTick 让出主线程
                process.nextTick(() => {
                    compilation.finish(err => {
                        if (err) return callback(err);

                        // ⭐⭐⭐ 调用 seal() —— 进入「生成阶段」
                        compilation.seal(err => {
                            if (err) return callback(err);

                            // 触发 afterCompile 钩子 —— 编译完成收尾
                            this.hooks.afterCompile.callAsync(compilation, err => {
                                if (err) return callback(err);
                                return callback(null, compilation);
                            });
                        });
                    });
                });
            });
        });
    });
}

// 📍 lib/EntryPlugin.js（约 L40~L60）

class EntryPlugin {
    constructor(context, entry, options = {}) {
        this.context = context;
        this.entry = entry;
        this.options = options || "default";
    }

    apply(compiler) {
        // 创建入口依赖对象（EntryDependency 记录入口路径和类型）
        const dep = EntryPlugin.createDependency(this.entry, this.options);

        // ⭐ 监听 make 钩子 —— 这是构建阶段的真正起点
        compiler.hooks.make.tapAsync("EntryPlugin", (compilation, callback) => {
            compilation.addEntry(
                this.context,
                dep,
                this.options,
                err => {
                    callback(err);
                }
            );
        });
    }
}

// 📍 lib/Compilation.js — addEntry 及其调用链

// addEntry（约 L2511）：入口函数
addEntry(context, entry, optionsOrName, callback) {
    // ...
    this._addEntryItem(context, entry, optionsOrName, callback);
}

// _addEntryItem（约 L2440）：创建入口 Module
_addEntryItem(context, entry, optionsOrName, callback) {
    // ...
    this.addModuleChain(
        context,
        entry,
        (err, module) => { callback(err); }
    );
}

// addModuleChain（约 L2444）：核心构建链路
addModuleChain(context, dependency, callback) {
    // ...

    // ⭐ 根据依赖类型选择对应的 Module Factory
    const moduleFactory = this.dependencyFactories.get(dependency.constructor);

    // ⭐ 进入模块创建核心流程
    this.handleModuleCreation(
        {
            factory: moduleFactory,
            dependencies: [dependency],
            contextInfo,
            context
        },
        (err) => { callback(err, module); }
    );
}

// 📍 lib/Compilation.js — handleModuleCreation（约 L2205）

handleModuleCreation({factory, dependencies, originModule, contextInfo, context, ...}, callback) {
    // Step 1: factorizeModule —— 调用 factory.create() 将 Dependency 工厂化为 Module
    this.factorizeModule(
        { factory, dependencies, originModule, contextInfo, context },
        (err, factoryResult) => {
            if (err) { this.errors.push(err); return callback(err); }
            const newModule = factoryResult.module;

            // Step 2: addModule —— 加入模块集合（内部含去重判断）
            this.addModule(newModule, (err, module) => {
                if (err) { this.errors.push(err); return callback(err); }

                // ⭐ Step 3: buildModule（读文件 → loader → AST → 依赖收集）
                this.buildModule(module, (err) => {
                    if (err) return callback(err);

                    // Step 4: 处理该模块收集到的依赖
                    this.processModuleDependencies(
                        module,
                        (err) => {
                            // ⭐⭐⭐ 递归：对新发现的依赖再次调用 handleModuleCreation
                            callback(err);
                        }
                    );
                });
            });
        }
    );
}

// 📍 lib/Compilation.js — buildModule（约 L2000 附近）

buildModule(module, callback) {
    // 触发 buildModule 钩子后调用 module.build() —— 对于 NormalModule 来说：
    //   1. 读取原始文件内容
    //   2. 执行 loader chain（通过 loader-runner）
    //   3. 将结果交给 parser 做 AST 分析
    this.hooks.buildModule.call(module);
    module.build(this.options, this, this.resolverFactory, this.inputFileSystem, err => {
        // ...
        callback();
    });
}

// 📍 lib/NormalModule.js — build() 方法（约 L1300 附近）

build(options, compilation, resolverFactory, fileSystem, callback) {
    // Step 1: 读取文件内容
    return this.doBuild(options, compilation, resolverFactory, fileSystem, err => {
        // Step 2: doBuild 内部调用 loader-runner
        // 所有配置的 loader 按规则（enforce/pre/normal/post）依次执行
        // 最终输出标准的 JavaScript 字符串（存于 this._source）

        try {
            const source = this._source.source();

            // Step 3: 【关键】JavascriptParser 同步解析 AST 并收集依赖
            // 依赖通过 state.current.addDependency() 挂到当前模块上
            this.parser.parse(this._ast || source, {
                source,
                current: this,       // 当前 module 引用
                module: this,
                compilation: compilation,
                options
            });
        } catch (parseErr) {
            return callback(parseErr);
        }

        // Step 4: 解析得到的依赖交由上层 processModuleDependencies 递归处理
        callback();
    });
}

// 📍 lib/javascript/JavascriptParser.js — 核心解析方法（约 L4892）

class JavascriptParser {
    // parse() 方法：AST 解析入口（同步执行，解析失败直接抛错）
    parse(source, state) {
        // Step 1: 使用 acorn 将源码解析为 AST
        let ast;
        ast = acorn.parse(source, {
            ecmaVersion: "latest",
            sourceType: "module",
            // ... 其他 parser 选项
        });

        // Step 2: 【核心】触发 program 钩子后遍历 AST
        if (this.hooks.program.call(ast) === undefined) {
            this.prewalkStatements(ast.body);  // 预遍历（函数提升等）
            this.walkStatements(ast.body);     // 逐语句遍历，触发各类钩子
        }

        // Step 3: 依赖已在遍历过程中通过 state.current.addDependency() 收集完成
        return state;
    }

    // 当遇到 import 语句时的处理
    import(statement, source) {
        // ⭐ 触发 import 钩子 —— HarmonyImportDependencyParserPlugin 监听此钩子
        this.hooks.import.call(statement, source);
    }

    // 当遇到 require() 调用时的处理
    // call 是 HookMap，按被调用函数名分发（如 "require"、"require.ensure"）
    call(expression) {
        if (expression.callee.type === "Identifier" &&
            expression.callee.name === "require") {
            // ⭐ 触发 call 钩子
            this.hooks.call.for("require").call(expression);
        }
    }

    // 当遇到 import() 动态导入时的处理（代码分割的入口之一）
    importCall(expression) {
        // ⭐ 触发 importCall 钩子 —— ImportParserPlugin 监听此钩子
        this.hooks.importCall.call(expression);
    }
}

// 📍 lib/dependencies/HarmonyImportDependencyParserPlugin.js（约 L150~L200）

class HarmonyImportDependencyParserPlugin {
    apply(parser) {
        // 监听 import 钩子 —— 每个 import 语句都会触发
        parser.hooks.import.tap(
            "HarmonyImportDependencyParserPlugin",
            (statement, source) => {
                // 清除缓存，确保每次都重新解析
                parser.state.lastHarmonyImportOrder =
                    (parser.state.lastHarmonyImportOrder || 0) + 1;

                // ⭐ 创建 HarmonyImportDependency 对象
                const dep = new HarmonyImportDependency(
                    source,                              // 模块路径
                    parser.state.lastHarmonyImportOrder  // 导入顺序
                );
                dep.loc = statement.loc;                 // 源码位置信息

                // ⭐ 将依赖添加到当前 Module
                parser.state.module.addDependency(dep);
                parser.state.lastHarmonyImport = dep;
            }
        );

        // 同时监听 export 钩子 —— 处理 export 语句
        parser.hooks.export.tap(/* ... */);
        parser.hooks.exportImport.tap(/* ... */);
    }
}

// 📍 lib/Compilation.js — 缓存检查逻辑

// 如果开启了 filesystem cache，会先尝试从缓存恢复 Module
if (this.cache && this.cache.enabled) {
    const cacheKey = this.getCacheModuleKey(module);
    const cachedModule = await this.cache.get(cacheKey);

    if (cachedModule && !isModuleInvalid(cachedModule)) {
        // 直接使用缓存的 Module，跳过 loader 和 AST 解析
        this.addModule(cachedModule);
        return callback(null, cachedModule);
    }
}

// 缓存未命中或失效，走正常构建流程
this.buildModule(module, callback);

// 📍 lib/LazyCompilationPlugin.js（概念示意）

// 当开启 lazyCompilation 时，entry 模块不会立即构建所有依赖
// 而是在实际被请求时才触发构建
if (options.experiments?.lazyCompilation) {
    compiler.hooks.make.tapAsync("LazyCompilation", (compilation, callback) => {
        // 只编译 entry 本身，不递归处理依赖
        compilation.addEntry(entryDep, (err, entryModule) => {
            // 依赖将在运行时（如 HTTP 请求）才触发编译
            callback(err);
        });
    });
}

// 当开启 experiments.css 时，CSS 模块走特殊处理路径
if (options.experiments?.css) {
    // CSS 文件不会被转为 JS，而是由 CssModule 处理
    // 最终生成独立的 CSS asset 或注入到 JS runtime 中
    compilation.dependencyFactories.set(CssDependency, new CssModuleFactory());
}

// 📍 lib/Compilation.js — seal() 方法（约 L3261）

seal(callback) {
    // Step 1: 创建 ChunkGraph 对象
    // ChunkGraph 维护 Module ↔ Chunk 之间的映射关系
    this.chunkGraph = new ChunkGraph(this.moduleGraph);

    // Step 2: 遍历所有 entries，为每个入口创建 Chunk
    for (const [entryName, entry] of this.entries) {
        const chunk = this.addChunk(entryName);          // 创建 EntryPoint Chunk
        entrypoint.connectChunk(chunk);                   // 关联 Entrypoint 与 Chunk
    }

    // Step 3: 【关键】构建 Chunk Graph 结构（同步执行）
    // 将 Module 按照依赖关系分配到各个 Chunk 中
    buildChunkGraph(this, chunkGraphInit);
    this.hooks.afterChunks.call(this.chunks);

    // Step 4: 触发一系列优化钩子
    // 这里的钩子是 SplitChunksPlugin 等优化插件的介入点
    // 注意：optimizeModules/optimizeChunks 是 SyncBailHook（用 call），
    //       optimizeTree/optimizeChunkModules 是异步钩子（用 callAsync）
    while (this.hooks.optimizeModules.call(this.modules)) { /* 返回真值则重复执行 */ }
    while (this.hooks.optimizeChunks.call(this.chunks, this.chunkGroups)) { /* ... */ }
    this.hooks.optimizeTree.callAsync(this.chunks, this.modules, (err) => {
        if (err) return callback(err);

        this.hooks.optimizeChunkModules.callAsync(this.chunks, this.modules, (err) => {
            if (err) return callback(err);

            // Step 5: 【核心】代码生成
            this.codeGeneration((err) => {
                if (err) return callback(err);

                // Step 6: 为每个 Chunk 创建 Asset
                this.createChunkAssets((err) => {
                    if (err) return callback(err);
                    callback();
                    // 至此 seal 结束；产物写盘由 Compiler.emitAssets 完成（见 3.5）
                });
            });
        });
    });
}

// 📍 lib/ChunkGraph.js（核心数据结构示意）

class ChunkGraph {
    constructor(moduleGraph) {
        this._modules = new Set();              // 所有 Module
        this._chunks = new Set();               // 所有 Chunk
        this._chunkModuleMap = new Map();       // Chunk → Set<Module>
        this._moduleChunkMap = new Map();       // Module → Set<Chunk>
        this._entrypointChunkMap = new Map();   // Entrypoint → Chunk
    }

    // 将 Module 连接到 Chunk
    connectChunkAndModule(chunk, module) {
        if (!this._chunkModuleMap.has(chunk)) {
            this._chunkModuleMap.set(chunk, new Set());
        }
        this._chunkModuleMap.get(chunk).add(module);

        if (!this._moduleChunkMap.has(module)) {
            this._moduleChunkMap.set(module, new Set());
        }
        this._moduleChunkMap.get(module).add(chunk);
    }

    // 获取 Chunk 包含的所有 Modules
    getChunkModules(chunk, type) {
        return this._chunkModuleMap.get(chunk) || new Set();
    }

    // 获取 Module 所属的所有 Chunks
    getModuleChunks(module) {
        return this._moduleChunkMap.get(module) || new Set();
    }
}

// 📍 lib/Compilation.js — codeGeneration()（约 L3686）

codeGeneration(callback) {
    // 遍历所有需要生成代码的 Module
    for (const module of this.modules) {
        this._codeGenerationModule(
            module,
            this.artifacts,
            (err, result) => {
                // result 包含生成的代码和 sourcemap
                // 不同类型的 Module 有不同的 codeGeneration 实现：
                //
                // NormalModule:
                //   → 输出经过 loader 转译后的 JS 代码
                //   + __webpack_require__ 包装
                //   + module.exports 赋值
                //
                // CssModule (experiments.css):
                //   → 输出 CSS 字符串
                //   或 CSS Module 的映射对象
                //
                // JsonModule:
                //   → JSON.parse(...) 包装
            }
        );
    }
    callback();
}

// 📍 lib/Compilation.js — createChunkAssets()（约 L5196）

createChunkAssets(callback) {
    for (const chunk of this.chunks) {
        // 根据 output.filename 模板生成文件名
        // 如 [name].[contenthash:8].js → main.a1b2c3d4.js
        const filenameTemplate = this.outputOptions.filename;
        const filename = this.getPath(filenameTemplate, {
            chunk,
            contentHash: chunk.hash,
            hash: this.hash,
        });

        // webpack 5 渲染链路：触发 renderManifest 钩子收集渲染任务
        // （由 JavascriptModulesPlugin 等内置插件注册，拼接 runtime + 各模块代码）
        const renderManifest = [];
        this.hooks.renderManifest.call(renderManifest, { chunk, outputOptions: this.outputOptions });

        for (const entry of renderManifest) {
            // 渲染任务执行后返回 Source（含 sourcemap 信息）
            const source = entry.render();

            // ⭐ 创建 Asset 记录（此时还未写入磁盘）
            this.emitAsset(filename, source);
        }
    }
    callback();
}

// 📍 lib/Compiler.js — emitAssets()（约 L724）

emitAssets(compilation, callback) {
    // 遍历 compilation.assets，逐个写入
    let filePaths = [];
    asyncLib.forEach(
        compilation.assets,
        (source, filename, callback) => {
            // 计算最终输出路径
            const outputPath = this.outputFileSystem.join(
                this.outputPath,
                filename
            );

            // ⭐⭐⭐ 真正的文件写入操作
            this.outputFileSystem.writeFile(
                outputPath,
                source.source(),
                () => {
                    filePaths.push(outputPath);
                    callback();
                }
            );
        },
        (err) => {
            // 所有文件写入完成；done 钩子由 run() 流程在 emit 之后触发
            callback(err);
        }
    );
}

// webpack.config.js
module.exports = {
  mode: 'production',
  entry: {
    main: './src/index.js',
    vendor: './src/vendor.js'
  },
  output: {
    filename: '[name].[contenthash:8].js',
    path: path.resolve(__dirname, 'dist')
  },
  optimization: {
    splitChunks: {
      chunks: 'all'
    }
  }
};

// src/index.js
import { foo } from './utils/a.js';
import { bar } from './utils/b.js';
console.log(foo, bar);

// src/utils/a.js
import { shared } from './shared.js';
export const foo = () => shared + '-from-a';

// src/utils/b.js
import { shared } from './shared.js';
export const bar = () => shared + '-from-b';

// src/vendor.js
import lodash from 'lodash';
export default lodash;

┌─────────────────────────────────────────────────────────────────────┐
│  初始化阶段                                                         │
│  ├─ 合并配置 → 校验 schema → 创建 Compiler                          │
│  ├─ 运行用户 plugins                                                │
│  └─ WebpackOptionsApply 注入:                                       │
│     ├─ EntryOptionPlugin → 注册 EntryPlugin × 2 (main + vendor)    │
│     └─ SplitChunksPlugin (optimization.splitChunks)                 │
│     （mode=production 时 optimization.minimizer 默认含 TerserPlugin）│
└─────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────┐
│  构建阶段 (Make)                                                    │
│                                                                     │
│  Entry[main] → index.js                                             │
│    ├── Dependence: ./utils/a.js                                     │
│    │   └── Module[a.js] → Dependence: ./shared.js                   │
│    │       └── Module[shared.js] → (无新依赖 ✓)                     │
│    └── Dependence: ./utils/b.js                                     │
│        └── Module[b.js] → Dependence: ./shared.js                   │
│            └── Module[shared.js] ← 复用已有 ✓                       │
│                                                                     │
│  Entry[vendor] → vendor.js                                          │
│    └── Dependence: lodash                                           │
│        └── Module[lodash] → (无新依赖 ✓)                            │
│                                                                     │
│  Module Graph 完成: 6 个 Module                                      │
└─────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────┐
│  生成阶段 (Seal)                                                    │
│                                                                     │
│  1. 创建 Chunk:                                                     │
│     ├─ Chunk[main]  ← index.js + a.js + b.js + shared.js            │
│     ├─ Chunk[vendor] ← vendor.js + lodash                           │
│                                                                     │
│  2. SplitChunksPlugin 优化:                                         │
│     └─ shared.js 被 2 个 Chunk 共用 → 提取为独立 Chunk              │
│                                                                     │
│  3. 最终 Chunk 结构:                                                 │
│     ├─ Chunk[vendors]   ← lodash                                   │
│     ├─ Chunk[main]      ← index.js + a.js + b.js                   │
│     └─ Chunk[shared]    ← shared.js                                │
│                                                                     │
│  4. codeGeneration → createChunkAssets → emitAssets                 │
│                                                                     │
│  5. 输出文件:                                                        │
│     dist/vendors.xxxx.js                                            │
│     dist/main.xxxx.js                                               │
│     dist/shared.xxxx.js                                             │
└─────────────────────────────────────────────────────────────────────┘