二、Webpack 与 Webpack CLI 版本对应
2.1 版本要求
官方要求：
code
┌─────────────────────────────────────────┐
│ Node.js >= 14.15.0 │
│ Webpack = 5.x（如 5.88.2） │
│ Webpack CLI = 5.x（如 5.1.4） │
└─────────────────────────────────────────┘查看方式：
code
Webpack 官网 → API → Command Line Interface2.2 两个项目的关系
code
┌─────────────────────────────────────────┐
│ Webpack │
│ （核心打包库） │
│ CommonJS 规范 │
│ 处理打包流程 │
└─────────────────────────────────────────┘
↕
┌─────────────────────────────────────────┐
│ Webpack CLI │
│ （命令行工具） │
│ TypeScript 编写 │
│ 接收命令行参数 │
└─────────────────────────────────────────┘GitHub 仓库：
code
https://github.com/webpack/webpack
https://github.com/webpack/webpack-cli三、环境搭建完整流程
3.1 项目初始化
bash
# 1. 创建项目目录
mkdir webpack-learn
cd webpack-learn
# 2. 初始化项目
npm init -y
# 3. 创建测试文件
mkdir src
touch src/index.js
touch src/utils.js
touch webpack.config.js3.2 项目结构
code
webpack-learn/
├── webpack/ # Webpack 源码
├── webpack-cli/ # Webpack CLI 源码
├── src/
│ ├── index.js
│ └── utils.js
├── webpack.config.js
├── package.json
└── node_modules/3.3 创建测试代码
src/utils.js：
javascript
export function sum(a, b) {
return a + b
}src/index.js：
javascript
import { sum } from "./utils.js"
const res = sum(1, 2)
console.log(res)webpack.config.js：
javascript
module.exports = {
mode: "development",
entry: "./src/index.js"
}3.4 下载源码
方式一：使用 Git Clone
bash
# 下载 Webpack 源码
git clone https://github.com/webpack/webpack.git
# 下载 Webpack CLI 源码
git clone https://github.com/webpack/webpack-cli.git方式二：下载 ZIP 包
code
1. 访问 GitHub 仓库
2. 点击 Code → Download ZIP
3. 解压到项目根目录四、源码构建与安装
4.1 官方贡献指南
查看位置：
code
GitHub → webpack/webpack → CONTRIBUTING.md
或
官网 → contributing documentation官方指导步骤：
code
1. Clone 项目
2. yarn install
3. yarn bootstrap
4. yarn build4.2 Webpack CLI 构建
步骤一：安装依赖
bash
cd webpack-learn
# 使用 yarn 安装（推荐）
yarn install
# 如果没有 yarn
npm install -g yarn步骤二：运行 bootstrap
bash
# 安装所有 packages 的依赖
yarn bootstrap步骤三：构建 Webpack CLI
bash
cd webpack-cli
# 构建 TypeScript
tsc --build
# 或者使用 yarn
yarn build构建产物：
code
webpack-cli/
├── src/ # TypeScript 源码
├── lib/ # 编译后的 JS
│ └── webpack-cli.js
└── bin/
└── webpack-cli.js # 入口文件4.3 Webpack 构建
查看构建配置：
javascript
// webpack/package.json
{
"scripts": {
"build": "tsc --build",
"prebuild:ci": "yarn install && node scripts/setupBuild.js"
}
}构建命令：
bash
cd webpack
# 安装依赖
yarn install
# 构建（如果需要）
yarn build注意： Webpack 使用 CommonJS 规范，通常不需要额外构建。
五、npm link 详解
5.1 npm link 原理
作用：
创建软链接，将本地包链接到全局或项目中。
工作原理：
code
┌─────────────────────────────────────────────────────────┐
│ npm link 工作流程 │
├─────────────────────────────────────────────────────────┤
│ │
│ 步骤 1：npm link（在包目录执行） │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ 本地包目录 │ ──────→ │ 全局 node_modules │ │
│ │ webpack/ │ link │ webpack@local │ │
│ └─────────────┘ └─────────────────┘ │
│ │
│ 步骤 2：npm link webpack（在项目目录执行） │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ 项目目录 │ ──────→ │ 全局 node_modules │ │
│ │ node_modules │ link │ webpack@local │ │
│ └─────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘5.2 链接 Webpack CLI
bash
# 进入 webpack-cli 目录
cd webpack-cli
# 链接到全局
npm link
# 验证
webpack --version5.3 链接 Webpack
bash
# 进入 webpack 目录
cd webpack
# 链接到全局
npm link
# 回到项目根目录
cd ..
# 链接到项目 node_modules
npm link webpack5.4 验证链接
bash
# 查看全局 node_modules
ls /usr/local/lib/node_modules
# 或（使用 nvm）
ls ~/.nvm/versions/node/v18.15.0/lib/node_modules
# 应该看到：
# webpack -> ../../../webpack-learn/webpack
# webpack-cli -> ../../../webpack-learn/webpack-cli5.5 为什么需要 npm link webpack？
Webpack CLI 的源码逻辑：
javascript
// webpack-cli/bin/webpack-cli.js
// 检查环境变量
if (process.env.WEBPACK_PACKAGE) {
// 使用自定义路径
webpack = require(process.env.WEBPACK_PACKAGE)
} else if (process.env.WEBPACK_IS_CUSTOM) {
// 使用自定义配置
webpack = require(process.env.WEBPACK_PACKAGE)
} else {
// 默认从 node_modules 查找
webpack = require("webpack")
}关键点：
code
默认行为：
├── CLI 会从 node_modules 中查找 webpack
├── 如果找不到会提示安装
└── 所以必须在项目 node_modules 中有 webpack
解决方案：
├── 方式一：npm link webpack（推荐）
└── 方式二：设置环境变量 WEBPACK_PACKAGE环境变量方式（替代方案）：
bash
# 设置环境变量
export WEBPACK_PACKAGE=/path/to/webpack/lib/index.js
export WEBPACK_IS_CUSTOM=true六、VS Code 调试配置
6.1 创建 launch.json
方式一：通过 VS Code 界面
code
1. 点击左侧"运行和调试"
2. 点击"创建 launch.json"
3. 选择 Node.js
4. 修改配置方式二：手动创建
json
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Webpack",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/webpack-cli/bin/webpack.js",
"runtimeVersion": "18.15.0",
"args": ["--config", "webpack.config.js"],
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen"
}
]
}6.2 配置项说明
| 配置项 | 说明 |
|---|---|
name | 调试配置名称 |
type | 调试类型（node） |
program | 入口文件路径 |
runtimeVersion | Node.js 版本 |
args | 命令行参数 |
console | 控制台类型 |
internalConsoleOptions | 内部控制台选项 |
6.3 入口文件定位
Webpack CLI 入口：
javascript
// webpack-cli/bin/webpack.js
// 程序入口
const runCLI = require("../lib/webpack-cli")
// 执行 CLI
runCLI(process.argv)真正的入口函数：
javascript
// webpack-cli/lib/webpack-cli.js
function runCLI(args) {
// 读取配置
// 解析参数
// 执行打包
}6.4 调试技巧
常用快捷键（Mac）：
| 快捷键 | 功能 |
|---|---|
F5 | 开始调试 |
F9 | 切换断点 |
F10 | 单步跳过 |
F11 | 单步进入 |
Shift+F11 | 单步跳出 |
Cmd+K Cmd+K | 折叠代码 |
调试步骤：
code
步骤 1：在入口文件打断点
↓
步骤 2：按 F5 启动调试
↓
步骤 3：程序停在断点处
↓
步骤 4：使用 F10 单步执行
↓
步骤 5：观察变量和调用栈
↓
步骤 6：分析执行流程七、源码阅读技巧
7.1 入口分析
Webpack CLI 执行流程：
code
bin/webpack.js（入口）
↓
检查 CLI 是否安装
↓
检查 webpack 是否存在
↓
加载 webpack 配置
↓
runCLI(args)
↓
执行打包流程7.2 关键代码追踪
javascript
// webpack-cli/bin/webpack.js
// 1. 检查 CLI 安装
const cliInstalled = require("./utils/cli-installed")
// 2. 获取包信息
const pkg = require("../package.json")
// 3. 运行 CLI
runCLI(process.argv, pkg)7.3 阅读顺序建议
code
推荐阅读路径：
├── 1. webpack-cli/bin/webpack.js（入口）
├── 2. webpack-cli/lib/webpack-cli.js（CLI 核心）
├── 3. webpack/lib/webpack.js（Webpack 入口）
├── 4. webpack/lib/Compiler.js（编译器）
└── 5. webpack/lib/Compilation.js（编译过程）八、常见问题与解决方案
| 问题 | 原因 | 解决方案 |
|---|---|---|
webpack: command not found | 未执行 npm link | 在 webpack-cli 目录执行 npm link |
Cannot find module 'webpack' | node_modules 中无 webpack | 执行 npm link webpack |
| TypeScript 编译失败 | tsc 未安装或配置错误 | 安装依赖后运行 tsc --build |
| 断点不生效 | 入口文件路径错误 | 检查 launch.json 中的 program 路径 |
| 调试直接结束 | 没有断点或断点位置不对 | 在正确位置添加断点 |
| Source Map 不显示 | 未生成 Source Map | 检查 tsconfig.json 的 sourceMap 配置 |
九、完整流程总结
9.1 环境搭建流程图
code
┌─────────────────────────────────────────────────────────┐
│ Webpack 源码调试环境搭建流程 │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 1. 项目初始化 │
│ mkdir webpack-learn && cd webpack-learn │
│ npm init -y │
│ 创建测试文件和配置 │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 2. 下载源码 │
│ git clone webpack │
│ git clone webpack-cli │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 3. 安装依赖 │
│ yarn install │
│ yarn bootstrap │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 4. 构建项目 │
│ cd webpack-cli && tsc --build │
│ cd webpack && yarn build（可选） │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 5. 创建软链接 │
│ cd webpack-cli && npm link │
│ cd webpack && npm link │
│ npm link webpack │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 6. 配置 VS Code 调试 │
│ 创建 launch.json │
│ 配置入口文件和参数 │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 7. 开始调试 │
│ 在关键位置打断点 │
│ 按 F5 启动调试 │
│ 单步执行，分析流程 │
└─────────────────────────────────────────────────────────┘9.2 关键命令汇总
bash
# 初始化
npm init -y
# 安装依赖
yarn install
yarn bootstrap
# 构建 TypeScript
cd webpack-cli && tsc --build
# 创建软链接
cd webpack-cli && npm link
cd webpack && npm link
npm link webpack
# 验证
webpack --version
# 调试
# 使用 VS Code 按 F5 启动十、学习要点总结
-
源码调试是学习 Webpack 的最佳方式
比看文章更直接，可以深入理解每个步骤 -
npm link 是本地调试的关键
理解npm link和npm link package的区别 -
Webpack CLI 用 TypeScript 编写
需要编译后才能在 Node.js 中运行 -
环境变量可以自定义 Webpack 路径
WEBPACK_PACKAGE和WEBPACK_IS_CUSTOM -
VS Code 调试配置是标准流程
与调试普通 Node.js 程序一致
十一、延伸学习资源
官方资源
调试工具
相关知识
十二、思考题
-
为什么不直接调试 node_modules 中的代码？
-
npm link 的工作原理是什么？为什么需要执行两次 link？
-
Webpack CLI 如何找到 Webpack 核心库？
-
如何设置环境变量来指定自定义的 Webpack 路径？
-
在调试过程中，你发现了 Webpack 的哪些关键执行步骤？