Webpack-入口文件分析

一、webpack-cli 调用 webpack 核心的完整流程

1. webpack-cli 入口文件

webpack-cli 的入口文件位于：

node_modules/webpack-cli/bin/cli.js

该文件通过 #!/usr/bin/env node 声明为 Node.js 可执行文件。

2. 核心调用链路源码解析（简化版）

// cli.js 核心逻辑
const runCLI = async (args) => {
  // 1. 解析命令行参数
  const { options: cliOptions } = require("./utils/parse-args")(args);
  
  // 2. 加载 webpack 核心库
  const webpack = require("webpack");
  
  // 3. 读取配置文件（支持多格式）
  const config = await loadConfig(cliOptions.config);
  
  // 4. 合并配置（核心步骤）
  const mergedOptions = mergeOptions(config, cliOptions);
  
  // 5. 调用 webpack 核心
  const compiler = webpack(mergedOptions);
  
  // 6. 根据参数执行构建或 watch
  if (cliOptions.watch) {
    compiler.watch({}, (err, stats) => { /* ... */ });
  } else {
    compiler.run((err, stats) => { /* ... */ });
  }
};

runCLI(process.argv);

---

二、参数合并与配置预处理全流程

1. 配置加载阶段 (loadConfig)

源码位置 ：webpack-cli/lib/groups/ConfigGroup.js

const loadConfig = async (configPath) => {
  // 支持 .js/.ts/.cjs/.mjs 等多种配置文件格式
  const configModule = require(configPath);
  
  // 处理函数式配置
  if (typeof configModule === "function") {
    return configModule(env, argv); // env 来自 --env 命令行参数
  }
  
  // 处理 Promise 配置
  if (configModule instanceof Promise) {
    return await configModule;
  }
  
  return configModule;
};

2. 配置合并逻辑 (mergeOptions)

源码位置 ：webpack-cli/lib/utils/merge-options.js

const mergeOptions = (config, cliOptions) => {
  // 1. 合并命令行参数（如 --mode=production）
  const merged = Object.assign({}, config, cliOptions);
  
  // 2. 处理多配置模式（当配置为数组时）
  if (Array.isArray(merged)) {
    return merged.map(options => applyDefaults(options));
  }
  
  // 3. 应用默认配置
  return applyDefaults(merged);
};

const applyDefaults = (options) => {
  // 使用 Webpack 的默认配置填充器
  const defaulter = new WebpackOptionsDefaulter();
  return defaulter.process(options);
};

---

三、Webpack 核心的配置预处理

1. WebpackOptionsDefaulter 详解

源码位置 ：webpack/lib/config/WebpackOptionsDefaulter.js

class WebpackOptionsDefaulter {
  process(options) {
    // 层级式默认值设置
    this.set("context", process.cwd());
    this.set("target", "web");
    this.set("mode", "production");
    this.set("output.path", path.resolve(options.context, "dist"));
    // ... 其他 300+ 默认配置项
    return options;
  }
}

2. 环境变量替换

在配置加载后，Webpack 会处理 process.env 变量：

// 在 webpack/lib/config/normalization.js 中
const replaceEnvVariables = (value) => {
  if (typeof value === "string") {
    return value.replace(/\$\{(\w+)\}/g, (match, envVar) => {
      return process.env[envVar] || "";
    });
  }
  return value;
};

---

四、配置处理的核心技术点

1. 多配置模式处理

当检测到配置为数组时：

// webpack/lib/webpack.js
if (Array.isArray(options)) {
  // 为每个配置项创建独立的 Compiler
  compiler = new MultiCompiler(options.map(opt => webpack(opt)));
}

2. 插件系统初始化

在创建 Compiler 后：

// 应用用户插件
options.plugins.forEach(plugin => {
  if (plugin.apply) {
    plugin.apply(compiler); // 调用插件的 apply 方法
  }
});

// 应用内置插件（由 WebpackOptionsApply 触发）
new WebpackOptionsApply().process(options, compiler);

---

五、全链路流程图解

命令行输入
  │
  ↓
webpack-cli/bin/cli.js
  │
  ↓
解析参数 (--config, --mode, --watch)
  │
  ↓
加载配置文件（支持函数/Promise/多环境）
  │
  ↓
合并命令行参数与配置文件
  │
  ↓
WebpackOptionsDefaulter 填充默认值
  │
  ↓
创建 Compiler 实例
  │
  ↓
加载用户插件 + 内置插件（EntryPlugin等）
  │
  ↓
Compiler.run() 或 Compiler.watch()

---

六、调试与验证方法

1. 查看最终合并配置

在 webpack.config.js 中添加：

module.exports = (env, argv) => {
  console.log("Final Options:", argv); // 打印合并后的配置
  return { /* ... */ };
};

2. 环境变量调试

cross-env NODE_ENV=development webpack --env.analyze=1

3. 核心流程断点调试

在 VS Code 中配置：

{
  "type": "node",
  "request": "launch",
  "name": "Debug Webpack",
  "program": "${workspaceFolder}/node_modules/webpack-cli/bin/cli.js",
  "args": ["--config", "webpack.config.js"]
}

---

七、典型问题解析

1. 为什么修改配置文件后需要重启？

因为配置文件仅在 CLI 启动时加载一次（watch 模式不会重新加载配置），解决方案：

// 使用函数式配置动态读取
module.exports = env => {
  const dynamicConfig = require(`./config.${env}.js`);
  return dynamicConfig;
};

2. 插件应用顺序问题

插件按照配置数组顺序依次应用，但某些插件（如 DefinePlugin）需要优先执行：

// 正确顺序示例
plugins: [
  new webpack.DefinePlugin({ /* 应放在前面 */ }),
  new HtmlWebpackPlugin()
]

---

通过以上分析，可以完整理解从命令行输入到 webpack 核心库构建启动的全流程。核心要点包括：

1. 配置分层合并策略：命令行参数 > 配置文件 > 默认配置
2. 环境敏感处理：函数式配置、环境变量替换
3. 插件生命周期控制：用户插件先于内置插件执行