Webpack CLI 执行流程深度解析

// webpack-cli.ts（约 2500 行）

class WebpackCLI {
  constructor() {
    // 初始化 commander 实例
    this.program = new Command();
  }

  // 大量方法...
  run() { /* 主入口 */ }
  processArguments() { /* 处理参数 */ }
  // ... 其他方法
}

export { WebpackCLI };

方式一：大纲视图
├── VS Code 左侧 → 大纲
└── 显示所有方法和属性

方式二：快捷键
├── Mac: Cmd + Shift + O
├── Windows: Ctrl + Shift + O
└── 输入方法名快速定位

方式三：函数查看器
├── 右键 → 查看符号
└── 浏览所有函数

// webpack-cli.ts 第 1092 行

async run() {
  // 1. 准备阶段（1094-1160 行）
  //    - 定义 command options
  //    - 定义辅助函数
  
  // 2. 注册命令（1161-1292 行）
  //    - 注册各种命令和选项
  
  // 3. 参数解析（1293-1794 行）
  //    - 解析命令行参数
  
  // 4. 执行命令（1279-行）
  //    - 处理参数
  //    - 执行构建
}

async run() {
  // 准备 webpack 支持的所有 options
  const options = {
    // 配置选项
    config: { /* ... */ },
    mode: { /* ... */ },
    entry: { /* ... */ },
    output: { /* ... */ },
    // ... 更多选项
  };
  
  // 定义辅助函数
  const isCommand = (name) => { /* ... */ };
  const isOption = (name) => { /* ... */ };
}

async run() {
  // 注册各种命令
  this.program
    .command('build')
    .description('构建项目')
    .action(handler);
    
  this.program
    .command('serve')
    .description('启动开发服务器')
    .action(handler);
    
  // ... 更多命令
}

async run() {
  // 解析异步参数
  await this.program.parseAsync(this.args);
}

// run 方法接收参数
run(args = process.argv) {
  this.args = args;
  // ...
}

┌─────────────────────────────────────────────────────────┐
│              run() 方法执行流程                          │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段一：准备工作（1094-1160 行）                        │
│ ├─ 定义 webpack options                                │
│ ├─ 定义辅助函数（isCommand、isOption）                  │
│ └─ 准备参数解析器                                      │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段二：注册命令（1161-1292 行）                        │
│ ├─ 注册 build 命令                                     │
│ ├─ 注册 serve 命令                                     │
│ ├─ 注册其他命令                                        │
│ └─ 注册各种 options                                    │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段三：参数解析（1293-1794 行）                        │
│ ├─ 解析环境变量                                        │
│ ├─ 检查必要参数                                        │
│ ├─ 检查冲突参数                                        │
│ └─ 准备执行上下文                                      │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 阶段四：执行命令（1795-行）                             │
│ ├─ parseAsync() 解析参数                               │
│ ├─ 触发 action handler                                 │
│ └─ 执行构建命令                                        │
└─────────────────────────────────────────────────────────┘

// run() 第 1795 行
await this.program.parseAsync(this.args);
    │
    ▼
// parseAsync 内部
parseAsync(args) {
  // 1. 准备用户参数
  const userArgs = prepareUserArgs(args);
  
  // 2. 解析命令
  const result = parseCommand(userArgs);
  
  // 3. 返回结果
  return result;
}

// 1. 检查是否需要输出帮助
outputHelpIfNeeded() {
  // 检查是否有 --help 参数
}

// 2. 检查缺失的必要参数
checkForMissingAndRequiredOptions() {
  // 检查必要参数是否存在
}

// 3. 检查冲突的参数
checkForConflictingOptions() {
  // 检查参数是否冲突
}

┌─────────────────────────────────────────────────────────┐
│  检查方法的作用：为后续执行准备合理的参数和流程         │
├─────────────────────────────────────────────────────────┤
│  就像一系列 if-else 判断：                              │
│  ├─ 参数是否合法？                                      │
│  ├─ 是否需要帮助信息？                                  │
│  ├─ 是否有冲突参数？                                    │
│  └─ 准备好执行环境                                      │
└─────────────────────────────────────────────────────────┘

// 获取命令名称
const commandName = this.getCommandName();

// 示例：
// webpack build  → commandName = 'build'
// webpack serve  → commandName = 'serve'
// webpack        → commandName = 'build'（默认）

async processArguments(command, options) {
  // 1. 检查参数
  this.checkOptions(command, options);
  
  // 2. 执行钩子
  await this.chainOrCallHooks();
  
  // 3. 执行 action handler
  const result = await this.actionHandler(command, options);
  
  return result;
}

async chainOrCallHooks(promise, event) {
  // 从当前命令及父命令中获取事件的生命周期钩子
  const hooks = this.getHooks(event);
  
  // 遍历每个钩子并执行
  for (const hook of hooks) {
    await hook();
  }
}

async actionHandler(options, program) {
  // 执行构建命令
  const result = await this.buildCommand(options);
  return result;
}

┌─────────────────────────────────────────────────────────┐
│              发布订阅模式                                │
└─────────────────────────────────────────────────────────┘

发布者（Publisher）
    │
    ▼ 发送事件
┌─────────────┐
│  事件中心   │ ← 存储所有订阅关系
│ Event Hub   │
└─────────────┘
    │
    ▼ 通知订阅者
订阅者（Subscriber）

// 1. 注册 action 回调
this.program.action(async (options, program) => {
  // 这是订阅者（回调函数）
  const command = await this.getBuiltInCommand('build');
  return command;
});

// 2. 解析参数时触发
await this.program.parseAsync(args);
// ↓
// 内部调用 actionHandler
// ↓
// 执行注册的回调函数

┌─────────────────────────────────────────────────────────┐
│         Webpack CLI 发布订阅流程                         │
└─────────────────────────────────────────────────────────┘

1. 注册订阅
   program.action(callback)
   └── 保存 callback 到 actionHandler

2. 触发事件
   program.parseAsync(args)
   └── 解析参数完成

3. 通知订阅者
   调用 actionHandler
   └── 执行 callback

4. 执行回调
   callback(options, program)
   └── 执行构建命令

┌─────────────────────────────────────────────────────────┐
│  Webpack 命令可能传递多个参数                           │
├─────────────────────────────────────────────────────────┤
│  示例：webpack build --config webpack.config.js        │
│                                                         │
│  每个命令参数：                                         │
│  ├─ 可能是同步执行                                     │
│  ├─ 可能是异步执行                                     │
│  └─ 需要统一的流程控制                                 │
│                                                         │
│  解决方案：                                             │
│  └─ parseAsync() 统一异步处理                          │
└─────────────────────────────────────────────────────────┘

// index.ts - 极简示例

import { Command } from 'commander';

class CLI {
  private program: any;
  private actionHandler: Function | null = null;

  constructor() {
    // 初始化 commander 实例
    this.program = new Command();
  }

  // 核心：注册 action 回调
  private action(listener: Function) {
    this.actionHandler = listener;
    return this;
  }

  // 解析参数
  private parseCommand() {
    if (this.actionHandler) {
      // 调用回调函数
      this.chainOrCall(null, 'build');
    }
  }

  // 链式调用
  private async chainOrCall(promise: any, event: string) {
    const fn = this.actionHandler;
    if (fn) {
      // 使用 apply 传递参数
      const result = fn.apply(null, []);
      return result;
    }
  }

  // 主入口
  run() {
    // 注册回调（发布）
    this.program.action(async (options, program) => {
      console.log('执行构建命令');
      console.log('options:', options);
      console.log('program:', program);
      return 'build';
    });

    // 保存回调
    this.actionHandler = (options: any, program: any) => {
      console.log('回调被执行');
      console.log('options:', options);
      console.log('program:', program);
    };

    // 解析参数（触发订阅）
    this.parseCommand();
  }
}

// 执行入口
new CLI().run();

┌─────────────────────────────────────────────────────────┐
│              极简示例执行流程                            │
└─────────────────────────────────────────────────────────┘

1. new CLI()
   └── 初始化 program 实例

2. program.action(callback)
   └── 保存 callback 到 actionHandler

3. run() 执行
   └── 调用 parseCommand()

4. parseCommand()
   └── 检查 actionHandler 是否存在

5. chainOrCall()
   └── 调用 actionHandler.apply()

6. 执行回调
   └── callback(options, program)

// 使用 apply 传递参数
const args = [options, program];
fn.apply(null, args);

// 等价于
fn(options, program);

// 注册时
this.program.action(async (options, program) => {
  // options 和 program 从哪里来？
  // 答案：从 apply 传递过来
});

// 调用时
const args = [options, program];
this.actionHandler.apply(null, args);
// options 和 program 会传递给回调函数

┌─────────────────────────────────────────────────────────┐
│          Webpack CLI 完整执行流程                        │
└─────────────────────────────────────────────────────────┘

用户输入：webpack build
    │
    ▼
┌─────────────────────────────────────────┐
│ 1. bin/cli.js                           │
│    入口文件                              │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 2. bootstrap.ts                         │
│    runCLI()                             │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 3. webpack-cli.ts → run()               │
│    ├─ 准备 options（1094-1160）         │
│    ├─ 注册命令（1161-1292）             │
│    ├─ 参数检查（1293-1794）             │
│    └─ parseAsync（1795）                │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 4. parseAsync()                         │
│    ├─ parseCommand()                    │
│    └─ chainOrCall()                     │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 5. actionHandler()                      │
│    执行注册的回调函数                    │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ 6. 执行构建命令                          │
│    getBuiltInCommand('build')           │
└─────────────────────────────────────────┘