Init_Make_Sea：真正读懂 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 处理：根据 source-map 配置注入对应插件
    if (options.devtool) {
        if (options.devtool.includes("source-map")) {
            new SourceMapDevToolPlugin(options.devtool).apply(compiler);
        } else if (options.devtool === "eval-source-map") {
            new EvalSourceMapDevToolPlugin(options.devtool).apply(compiler);
        }
        // ...
    }

    // ③ Runtime 注入：根据目标环境注入运行时代码
    new RuntimePlugin(compiler.options.target).apply(compiler);

    // ④ 【v5 新增】persistent cache 处理
    if (options.cache && options.cache.type === "filesystem") {
        new LazyCompilationPlugin(options.lazyCompilation).apply(compiler);
    }

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

// 📍 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() 方法（约 L1100~L1150）

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（约 L1400~L1420）：入口函数
addEntry(context, entry, optionsOrName, callback) {
    // ...
    this._addEntryItem(context, entry, optionsOrName, callback);
}

// _addEntryItem（约 L1420~L1440）：创建入口 Module
_addEntryItem(context, entry, optionsOrName, callback) {
    // ...
    this.addModuleChain(
        context,
        entry,
        undefined,  // module 不存在，需要新建
        undefined,
        {},
        (err, module) => { callback(err); }
    );
}

// addModuleChain（约 L1460~L1500）：核心构建链路
addModuleChain(context, dependency, originModule, preFactorizations, options, callback) {
    // ...

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

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

// 📍 lib/Compilation.js — handleModuleCreation（约 L1500~L1580）

handleModuleCreation({factory, dependencies, originModule, ...}, callback) {
    // 创建 Module 对象
    this.createModule(
        factory,
        dependencies,
        originModule,
        (err, createdModule) => {

            // 将 Module 加入构建队列
            const addModuleResult = this.addModule(module);

            // ⭐ 构建 Module（读文件 → loader → AST → 依赖收集）
            this.buildModule(module, (err) => {
                // 构建完成后，处理该模块的依赖
                this.processModuleDependencies(
                    createdModule,
                    (err) => {
                        // ⭐⭐⭐ 递归：对新发现的依赖再次调用 handleModuleCreation
                        callback(err);
                    }
                );
            });
        }
    );
}

// 📍 lib/Compilation.js — buildModule（约 L1580~L1620）

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

// 📍 lib/NormalModule.js — build() 方法（约 L800~L900）

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 字符串

        const result = this._source.source();  // loader 转译后的 JS 字符串

        // Step 3: 【关键】使用 JavascriptParser 解析 AST 并收集依赖
        const result = this.parser.parse(
            this._astOrSource,      // AST 或源码字符串
            {
                current: this,       // 当前 module 引用
                module: this,
                compilation: compilation,
                // ...
            },
            (err, result) => {
                // result.dependencies 就是收集到的所有依赖数组
                this.dependencies = result.dependencies;
                this.blocks = result.blocks;
                this.variables = result.variables;

                // Step 4: 调用 handleParseResult 处理依赖
                callback();
            }
        );
    });
}

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

class JavascriptParser {
    // parse() 方法：AST 解析入口
    parse(source, state, callback) {
        // Step 1: 使用 acorn 将源码解析为 AST
        let ast;
        try {
            ast = acorn.parse(source, {
                ecmaVersion: 2022,
                sourceType: "module",
                // ... 其他 parser 选项
            });

            // Step 2: 【核心】遍历 AST，触发各类语句钩子
            this.walkStatement(ast);  // 遍历顶层语句
            this.walkExpressions(ast); // 遍历表达式
        } catch (error) {
            return callback(error);
        }

        // Step 3: 返回收集到的依赖
        callback(null, {
            dependencies: state.current.dependencies,
            blocks: state.current.blocks,
            variables: state.current.variables
        });
    }

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

    // 当遇到 require() 调用时的处理
    call(expression) {
        if (expression.callee.type === "Identifier" &&
            expression.callee.name === "require") {
            // ⭐ 触发 call 钩子
            this.hooks.call.call(expression);
        }
    }

    // 当遇到 require.ensure() 时的处理（代码分割）
    ensure(expression) {
        this.hooks.ensure.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, // 导入顺序
                    parser.state.module                  // 所属模块
                );
                dep.loc = statement.loc;                 // 源码位置信息

                // ⭐ 将依赖添加到当前 Module
                parser.state.current.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 中
    dependencyFactory.set(CssDependency, new CssModuleFactory());
}

// 📍 lib/Compilation.js — seal() 方法（约 L2780~L2950）

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

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

    // Step 3: 【关键】构建 Chunk Graph 结构
    // 将 Module 按照依赖关系分配到各个 Chunk 中
    buildChunkGraph(
        this,
        this.chunkGraph,
        this.entrypoints,
        this.options,
        this.inputFileSystem,
        () => {

            // Step 4: 触发一系列优化钩子
            // 这里的钩子是 SplitChunksPlugin 等优化插件的介入点
            this.hooks.optimizeModules.callAsync(this.modules, /* ... */);
            this.hooks.optimizeChunks.callAsync(this.chunks, /* ... */);
            this.hooks.optimizeTree.callAsync(this.chunks, this.modules, /* ... */);
            this.hooks.optimizeChunkModules.callAsync(this.chunks, this.modules, /* ... */);

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

                // Step 6: 为每个 Chunk 创建 Asset
                this.createChunkAssets(() => {

                    // Step 7: 提交资产记录
                    this.emitAssets(() => {
                        callback();
                    });
                });
            });
        }
    );
}

// 📍 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()（约 L3200~L3300）

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()（约 L4520~L4620）

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,
        });

        // 使用 Template 工厂类将 Chunk 的 Module 代码拼接成完整文件
        const source = this.mainTemplate.render(
            this.getCurrentRenderRules(),
            chunk,
            this.moduleTemplates,
            this.dependencyTemplates
        );

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

// 📍 lib/Compilation.js — emitAssets()（约 L4638~L4720）

emitAssets(callback) {
    // 遍历所有 assets，触发 assetEmitted 钩子
    for (const [filename, source] of this.assets) {
        this.hooks.assetEmitted.callAsync(
            filename,
            { content: source.buffer(), source },
            (err) => { /* ... */ }
        );
    }
    callback();
}

// 📍 lib/Compiler.js — emitAssets()（约 L592~L650）

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) => {
            // 所有文件写入完成
            this.hooks.done.callAsync(stats, () => {
                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 × 2 (main + vendor)                       │
│     ├─ SplitChunksPlugin (optimization.splitChunks)                 │
│     └─ TerserPlugin (mode=production)                               │
└─────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────┐
│  构建阶段 (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                                             │
└─────────────────────────────────────────────────────────────────────┘