webpack5 源码解读(1) —— webpack 及 webpack-cli 的启动过程

启动 webpack

本文将通过 webpack5 的入口文件源码，解读 webpack 的启动过程。

寻找入口

如下所示的 package.json 文件中，当我们执行 npm run build 命令时，实际执行了后面的 webpack 指令：

{
  // ...
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "serve": "webpack serve",
    "build": "webpack"
  },
  // ...
}

此时 npm 会去寻找 node_modules/.bin 目录下是否存在 webpack.sh 或者 webpack.cmd 文件，最终实际找到 node_modules/webpack/bin/webpack.js 文件作为入口文件去执行。

检查 webpack-cli 是否安装

node_modules/webpack/bin/webpack.js 文件源码如下，首先首行 #!/usr/bin/env node 会告诉系统以用户的环境变量中的 node 去执行这个文件，然后封装了三个方法，初始化了一个 cli 对象，根据 cli.installed 执行不同流程：

#!/usr/bin/env node

// 执行命令
const runCommand = (command, args) => {
  // ...
};

// 检查一个包是否安装
const isInstalled = (packageName) => {
  // ...
};

// 运行 webpack-cli
const runCli = (cli) => {
  // ...
};

const cli = {
  name: 'webpack-cli',
  package: 'webpack-cli',
  binName: 'webpack-cli',
  installed: isInstalled('webpack-cli'),
  url: 'https://github.com/webpack/webpack-cli',
};

if (!cli.installed) {
  // ...
} else {
  // ...
}

cli.installed 是执行了 isInstalled('webpack-cli') 方法。我们看一下 isInstalled，它用于判断一个包是否安装。它接收一个 packageName 参数，当处于 pnp 环境时，直接返回 true 表示已安装；否则从当前目录开始向父级目录遍历 node_modules 文件夹下是否有 packageName 对应的文件夹，有则返回 true 表示已安装；直至遍历到顶层目录还未找到则返回 false 表示未安装。

/**
 * @param {string} packageName name of the package
 * @returns {boolean} is the package installed?
 */
const isInstalled = (packageName) => {
  // process.versions.pnp 为 true 时，表示处于 Pnp 环境
  // 提供了 npm 包即插即用的环境而不必安装，所以直接返回 true
  if (process.versions.pnp) {
    return true;
  }

  const path = require('path');
  const fs = require('graceful-fs');

  let dir = __dirname;

  // 逐层向上遍历父级目录，看对应的 package 名的文件夹是否存在，从而判断包是否安装
  do {
    try {
      if (
        fs.statSync(path.join(dir, 'node_modules', packageName)).isDirectory()
      ) {
        return true;
      }
    } catch (_error) {
      // Nothing
    }
  } while (dir !== (dir = path.dirname(dir)));

  return false;
};

未安装

若 cli.installed 为 false，说明 webpack-cli 未安装，提示用户必须安装 webpack-cli，然后让用户输入 y/n 选择是否安装：用户输入 n 则直接报错退出；用户输入 y 则直接通过上面的 runCommand 方法安装 webpack-cli，安装完毕后通过 runCli 方法引入 webpack-cli 的入口文件执行 webpack-cli：

if (!cli.installed) {
  // webpack-cli 未安装
  const path = require('path');
  const fs = require('graceful-fs');
  const readLine = require('readline');

  // 提示 webpack-cli 必须安装
  const notify =
    'CLI for webpack must be installed.\n' + `  ${cli.name} (${cli.url})\n`;

  console.error(notify);

  let packageManager;

  if (fs.existsSync(path.resolve(process.cwd(), 'yarn.lock'))) {
    packageManager = 'yarn';
  } else if (fs.existsSync(path.resolve(process.cwd(), 'pnpm-lock.yaml'))) {
    packageManager = 'pnpm';
  } else {
    packageManager = 'npm';
  }

  const installOptions = [packageManager === 'yarn' ? 'add' : 'install', '-D'];

  console.error(
    `We will use "${packageManager}" to install the CLI via "${packageManager} ${installOptions.join(
      ' '
    )} ${cli.package}".`
  );
  
  // 询问用户是否安装 webpack-cli
  const question = `Do you want to install 'webpack-cli' (yes/no): `;

  const questionInterface = readLine.createInterface({
    input: process.stdin,
    output: process.stderr,
  });

  // In certain scenarios (e.g. when STDIN is not in terminal mode), the callback function will not be
  // executed. Setting the exit code here to ensure the script exits correctly in those cases. The callback
  // function is responsible for clearing the exit code if the user wishes to install webpack-cli.
  process.exitCode = 1;
  questionInterface.question(question, (answer) => {
    questionInterface.close();

    const normalizedAnswer = answer.toLowerCase().startsWith('y');
    
    // 用户选择不安装，报错退出
    if (!normalizedAnswer) {
      console.error(
        "You need to install 'webpack-cli' to use webpack via CLI.\n" +
          'You can also install the CLI manually.'
      );

      return;
    }
    process.exitCode = 0;

    console.log(
      `Installing '${
        cli.package
      }' (running '${packageManager} ${installOptions.join(' ')} ${
        cli.package
      }')...`
    );
    // 用户选择安装，通过 runCommand 安装 webpack-cli
    runCommand(packageManager, installOptions.concat(cli.package))
      .then(() => {
        // 安装完毕后引入 webpack-cli 的入口文件执行
        runCli(cli);
      })
      .catch((error) => {
        console.error(error);
        process.exitCode = 1;
      });
  });
} else {
  // ...
}

已安装

若已安装 webpack-cli，则直接通过 runCli 方法引入 webpack-cli 的入口文件执行 webpack-cli：

if (!cli.installed) {
  // ...
} else {
  // 若已安装，直接引入 webpack-cli 的入口文件执行
  runCli(cli);
}

可见，webpack 的启动过程最终是去找到 webpack-cli 并执行。

启动 webpack-cli

入口文件

runCli 会找到 webpack-cli 的 package.json 中的 bin 所指向的文件引入执行，其对应的文件为 webpack-cli/bin/cli.js，下面我们看一下这个文件的内容:

#!/usr/bin/env node

"use strict";

const importLocal = require("import-local");
const runCLI = require("../lib/bootstrap");

if (!process.env.WEBPACK_CLI_SKIP_IMPORT_LOCAL) {
  // Prefer the local installation of `webpack-cli`
  if (importLocal(__filename)) {
    return;
  }
}

process.title = "webpack";

runCLI(process.argv);

它会引入 webpack-cli/lib/bootstrap.js 文件中的 runCLI 函数，并将 process.argv (即执行 webpack 命令时 webpack xxx 对应的 xxx 参数) 传入去执行。

runCLI 函数中代码如下，总共做了两件事情，首先通过 new WebpackCLI() 创建了一个 WebpackCLI 实例，然后 cli.run(args) 调用了实例的 run 方法：

const WebpackCLI = require("./webpack-cli");

const runCLI = async (args) => {
  // Create a new instance of the CLI object
  const cli = new WebpackCLI();

  try {
    await cli.run(args);
  } catch (error) {
    cli.logger.error(error);
    process.exit(2);
  }
};

module.exports = runCLI;

创建 WebpackCLI 实例

看下 WebpackCLI 这个类， new WebpackCLI() 创建 WebpackCLI 类实例时会执行其构造函数，设置了控制台的打印颜色和各种打印信息，最主要的是从 commander 包中引入了 program，将其挂载到了 this 上，稍后会讲到 Command 类的作用：

const { program, Option } = require("commander");
// ...

class WebpackCLI {
  constructor() {
    // 设置控制台打印颜色
    this.colors = this.createColors();
    // 设置各种类型控制台打印信息(error)
    this.logger = this.getLogger();

    // 将 Command 实例挂载到 this 上
    this.program = program;
    this.program.name("webpack");
    this.program.configureOutput({
      writeErr: this.logger.error,
      outputError: (str, write) =>
        write(`Error: ${this.capitalizeFirstLetter(str.replace(/^error:/, "").trim())}`),
    });
  }
  
  // ...
  
  async run(args, parseOptions) {
    // ...
  }
  
  // ...
}

解析 webpack 指令参数

cli.run(args) 方法中，首先将各个 webpack 命令添加到了数组中，然后解析 webpack xxx 指令中的 xxx 参数，将其挂载到 this.program.args 上。然后根据不同的参数，调用 loadCommandByName 方法执行不同的 webpack 指令：

async run(args, parseOptions) {
  // 执行打包
  const buildCommandOptions = {
    name: "build [entries...]",
    alias: ["bundle", "b"],
    description: "Run webpack (default command, can be omitted).",
    usage: "[entries...] [options]",
    dependencies: [WEBPACK_PACKAGE],
  };
  // 运行 webpack 并监听文件改变
  const watchCommandOptions = {
    name: "watch [entries...]",
    alias: "w",
    description: "Run webpack and watch for files changes.",
    usage: "[entries...] [options]",
    dependencies: [WEBPACK_PACKAGE],
  };
  // 查看 webpack、webpack-cli 和 webpack-dev-server 的版本
  const versionCommandOptions = {
    name: "version [commands...]",
    alias: "v",
    description:
      "Output the version number of 'webpack', 'webpack-cli' and 'webpack-dev-server' and commands.",
  };
  // 输出 webpack 各项命令
  const helpCommandOptions = {
    name: "help [command] [option]",
    alias: "h",
    description: "Display help for commands and options.",
  };
  // 其他的内置命令
  const externalBuiltInCommandsInfo = [
    // 启动 dev server
    {
      name: "serve [entries...]",
      alias: ["server", "s"],
      pkg: "@webpack-cli/serve",
    },
    // 输出相关信息，包括当前系统、包管理工具、运行中的浏览器版本以及安装的 webpack loader 和 plugin
    {
      name: "info",
      alias: "i",
      pkg: "@webpack-cli/info",
    },
    // 生成一份 webpack 配置
    {
      name: "init",
      alias: ["create", "new", "c", "n"],
      pkg: "@webpack-cli/generators",
    },
    // 生成一份 webpack loader 代码
    {
      name: "loader",
      alias: "l",
      pkg: "@webpack-cli/generators",
    },
    // 生成一份 webpack plugin 代码
    {
      name: "plugin",
      alias: "p",
      pkg: "@webpack-cli/generators",
    },
    // 进行 webpack 版本迁移
    {
      name: "migrate",
      alias: "m",
      pkg: "@webpack-cli/migrate",
    },
    // 验证一份 webpack 的配置是否正确
    {
      name: "configtest [config-path]",
      alias: "t",
      pkg: "@webpack-cli/configtest",
    },
  ];

  // 初始化已知的命令数组
  const knownCommands = [
    buildCommandOptions,
    watchCommandOptions,
    versionCommandOptions,
    helpCommandOptions,
    ...externalBuiltInCommandsInfo,
  ];
  
  // ...

  // Register own exit
  // ...

  // Default `--color` and `--no-color` options
  // ...

  // Make `-v, --version` options
  // Make `version|v [commands...]` command
  
  
  // ...

  // Default action
  this.program.usage("[options]");
  this.program.allowUnknownOption(true);
  this.program.action(async (options, program) => {
    if (!isInternalActionCalled) {
      isInternalActionCalled = true;
    } else {
      this.logger.error("No commands found to run");
      process.exit(2);
    }

    // Command and options
    // 解析传入的参数
    const { operands, unknown } = this.program.parseOptions(program.args);
    const defaultCommandToRun = getCommandName(buildCommandOptions.name);
    const hasOperand = typeof operands[0] !== "undefined";
    // 若传入参数，则将 operand 赋值为 webpack 命令后面跟的第一个参数，否则设置为默认的 build 命令
    const operand = hasOperand ? operands[0] : defaultCommandToRun;
    const isHelpOption = typeof options.help !== "undefined";
    // 如果是已知的命令，isHelpCommandSyntax 为 true；否则为 false
    const isHelpCommandSyntax = isCommand(operand, helpCommandOptions);

    if (isHelpOption || isHelpCommandSyntax) {
      // 如果不是已知命令，则输出如何获取 webpack help 信息
      let isVerbose = false;

      if (isHelpOption) {
        if (typeof options.help === "string") {
          if (options.help !== "verbose") {
            this.logger.error("Unknown value for '--help' option, please use '--help=verbose'");
            process.exit(2);
          }

          isVerbose = true;
        }
      }

      this.program.forHelp = true;

      const optionsForHelp = []
        .concat(isHelpOption && hasOperand ? [operand] : [])
        // Syntax `webpack help [command]`
        .concat(operands.slice(1))
        // Syntax `webpack help [option]`
        .concat(unknown)
        .concat(
          isHelpCommandSyntax && typeof options.color !== "undefined"
            ? [options.color ? "--color" : "--no-color"]
            : [],
        )
        .concat(
          isHelpCommandSyntax && typeof options.version !== "undefined" ? ["--version"] : [],
        );

      await outputHelp(optionsForHelp, isVerbose, isHelpCommandSyntax, program);
    }

    const isVersionOption = typeof options.version !== "undefined";
    const isVersionCommandSyntax = isCommand(operand, versionCommandOptions);

    if (isVersionOption || isVersionCommandSyntax) {
      // 如果是版本命令，则输出版本相关信息
      const optionsForVersion = []
        .concat(isVersionOption ? [operand] : [])
        .concat(operands.slice(1))
        .concat(unknown);

      await outputVersion(optionsForVersion, program);
    }

    let commandToRun = operand;
    let commandOperands = operands.slice(1);

    if (isKnownCommand(commandToRun)) {
      // 是已知的 webpack 命令，调用 loadCommandByName 函数执行相关命令
      await loadCommandByName(commandToRun, true);
    } else {
      const isEntrySyntax = fs.existsSync(operand);

      if (isEntrySyntax) {
        // webpack xxx 其中 xxx 文件夹存在，则对 xxx 文件夹下面的内容进行打包
        commandToRun = defaultCommandToRun;
        commandOperands = operands;

        await loadCommandByName(commandToRun);
      } else {
        // webpack xxx 的 xxx 不是已知命令且不是文件夹则报错
        this.logger.error(`Unknown command or entry '${operand}'`);

        const levenshtein = require("fastest-levenshtein");
        const found = knownCommands.find(
          (commandOptions) =>
            levenshtein.distance(operand, getCommandName(commandOptions.name)) < 3,
        );

        if (found) {
          this.logger.error(
            `Did you mean '${getCommandName(found.name)}' (alias '${
              Array.isArray(found.alias) ? found.alias.join(", ") : found.alias
            }')?`,
          );
        }

        this.logger.error("Run 'webpack --help' to see available commands and options");
        process.exit(2);
      }
    }

    await this.program.parseAsync([commandToRun, ...commandOperands, ...unknown], {
      from: "user",
    });
  });

  // 解析指令参数挂载到 this.program.args 上
  await this.program.parseAsync(args, parseOptions);
}

执行打包指令

loadCommandByName 方法中，主要是根据不同的 webpack 指令执行不同的功能，我们主要关注 webpack 打包过程，执行 webpack 打包相关的命令时（build 或 watch），最终运行了 runWebpack 方法：

const loadCommandByName = async (commandName, allowToInstall = false) => {
  const isBuildCommandUsed = isCommand(commandName, buildCommandOptions);
  const isWatchCommandUsed = isCommand(commandName, watchCommandOptions);

  if (isBuildCommandUsed || isWatchCommandUsed) {
    await this.makeCommand(
      isBuildCommandUsed ? buildCommandOptions : watchCommandOptions,
      
      // ...
      
      async (entries, options) => {
        if (entries.length > 0) {
          options.entry = [...entries, ...(options.entry || [])];
        }

        await this.runWebpack(options, isWatchCommandUsed);
      },
    );
  }
  // ...
};

创建 compiler

看一下 runWebpack 的代码，里面主要做的事情就是调用 createCompiler 方法创建 compiler(这是贯穿了 webpack 后续打包过程中的一个重要的对象，后面会详细讲到)：

async runWebpack(options, isWatchCommand) {
  // eslint-disable-next-line prefer-const
  let compiler;
  let createJsonStringifyStream;

  // ...

  // 创建 compiler
  compiler = await this.createCompiler(options, callback);

  // ...
}

运行 webpack

createCompiler 方法中，解析 options 中的各项打包配置，然后又回到了引入 webpack 包，运行其 main 入口文件，开始执行打包：

async createCompiler(options, callback) {
  if (typeof options.nodeEnv === "string") {
    process.env.NODE_ENV = options.nodeEnv;
  }

  let config = await this.loadConfig(options);
  config = await this.buildConfig(config, options);

  let compiler;

  try {
    // 运行 webpack 
    compiler = this.webpack(
      config.options,
      callback
        ? (error, stats) => {
            if (error && this.isValidationError(error)) {
              this.logger.error(error.message);
              process.exit(2);
            }

            callback(error, stats);
          }
        : callback,
    );
  } catch (error) {
    if (this.isValidationError(error)) {
      this.logger.error(error.message);
    } else {
      this.logger.error(error);
    }

    process.exit(2);
  }

  // TODO webpack@4 return Watching and MultiWatching instead Compiler and MultiCompiler, remove this after drop webpack@4
  if (compiler && compiler.compiler) {
    compiler = compiler.compiler;
  }

  return compiler;
}

总结

总结一下 webpack5 中执行打包命令时， webpack 和 webpack-cli 的启动过程：

• 启动 webpack
  • 检查 webpack-cli 是否安装
• 启动 webpack-cli
  • 解析 webpack 指令参数
  • 执行打包指令
  • 创建 compiler
  • 运行 webpack 主文件