Tech Codex - 开发者笔记

二、Source Map 配置

2.1 什么是 Source Map？

定义：

Source Map 是一个映射文件，包含编译后 JavaScript 代码与原始源码的映射关系。

作用：

code

┌─────────────────────────────────────────────────────────┐
│ 有了 Source Map，调试工具可以：                          │
│                                                         │
│ 1. 将编译后的代码位置映射回源码位置                      │
│ 2. 在调试时显示原始 TypeScript 代码                     │
│ 3. 在源码中打断点，在编译后代码中生效                    │
│ 4. 提供更好的调试体验                                   │
└─────────────────────────────────────────────────────────┘

2.2 配置 tsconfig.json

配置位置：

code

webpack-cli/packages/webpack-cli/tsconfig.json

配置方法：

json

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "./lib",
    "rootDir": "./src",
    // ... 其他配置
  }
}

关键配置项：

配置项	说明
`sourceMap`	生成 .map 文件
`outDir`	编译输出目录
`rootDir`	源码根目录

2.3 查看配置文件

Webpack CLI 的配置方式：

javascript

// webpack-cli/scripts/setup-build.js

const fs = require('fs');
const tsconfigPath = '../tsconfig.json';

// 读取 tsconfig.json
let tsconfig = JSON.parse(fs.readFileSync(tsconfigPath));

// 设置 sourceMap
tsconfig.compilerOptions.sourceMap = true;

// 写回文件
fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2));

说明：

Webpack CLI 在构建前会通过脚本自动设置 sourceMap: true。

三、编译 TypeScript 并生成 Source Map

3.1 编译命令

方式一：使用全局 tsc

bash

# 安装 TypeScript（如果没有）
npm install -g typescript

# 编译
cd webpack-cli/packages/webpack-cli
tsc --build

方式二：使用 npx tsc

bash

# 使用项目内的 TypeScript
cd webpack-cli/packages/webpack-cli
npx tsc --build

方式三：使用 yarn

bash

cd webpack-cli/packages/webpack-cli
yarn build

3.2 编译产物

编译前：

code

webpack-cli/packages/webpack-cli/
├── src/
│   ├── index.ts
│   ├── bootstrap.ts
│   └── webpack-cli.ts
└── bin/
    └── webpack-cli.js

编译后：

code

webpack-cli/packages/webpack-cli/
├── src/
│   ├── index.ts
│   ├── bootstrap.ts
│   └── webpack-cli.ts
├── lib/
│   ├── index.js          ← 编译产物
│   ├── index.js.map      ← Source Map
│   ├── bootstrap.js
│   ├── bootstrap.js.map
│   ├── webpack-cli.js
│   └── webpack-cli.js.map
└── bin/
    └── webpack-cli.js

3.3 Source Map 文件示例

json

// lib/index.js.map
{
  "version": 3,
  "file": "index.js",
  "sourceRoot": "",
  "sources": [
    "../src/index.ts"
  ],
  "names": [],
  "mappings": "AAAA;..."
}

关键字段：

字段	说明
`version`	Source Map 版本（通常为 3）
`file`	编译后的文件名
`sources`	原始源文件路径
`mappings`	位置映射信息（Base64 VLQ 编码）

四、VS Code 调试配置进阶

4.1 launch.json 配置

json

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Webpack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/webpack/bin/webpack.js",
      "runtimeVersion": "18.15.0",
      "args": ["--config", "webpack.config.js"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "name": "CLI Debug",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/webpack-cli/packages/webpack-cli/bin/webpack-cli.js",
      "runtimeVersion": "18.15.0",
      "args": ["--config", "webpack.config.js"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "sourceMaps": true,
      "outFiles": [
        "${workspaceFolder}/webpack-cli/packages/webpack-cli/lib/**/*.js"
      ]
    }
  ]
}

4.2 配置项说明

配置项	说明
`name`	配置名称（选择时显示）
`program`	入口文件（编译后的 JS）
`sourceMaps`	启用 Source Map 支持
`outFiles`	指定编译后文件的位置

关键点：

code

1. program 指向编译后的 JS 入口
2. sourceMaps 启用后会自动查找 .map 文件
3. outFiles 帮助 VS Code 定位编译产物
4. 断点可以打在 TS 源码中

五、调试 TypeScript 源码实战

5.1 打断点策略

入口文件断点：

javascript

// webpack-cli/packages/webpack-cli/bin/webpack-cli.js（第17行）

#!/usr/bin/env node
'use strict';

// 在这里打断点
const runCLI = require('../lib/webpack-cli').runCLI;  // ← 断点

runCLI(process.argv);

源码断点：

typescript

// webpack-cli/packages/webpack-cli/src/index.ts（第5行）

import { CLI } from './webpack-cli';

// 在这里打断点
const cli = new CLI();  // ← 断点
cli.run(process.argv);

类方法断点：

typescript

// webpack-cli/packages/webpack-cli/src/webpack-cli.ts（第86行）

export class CLI {
  constructor() {
    // 在这里打断点
    this.compiler = null;  // ← 断点
  }
}

5.2 调试流程

code

步骤 1：在 bin/webpack-cli.js 打断点
    ↓
步骤 2：选择 "CLI Debug" 配置
    ↓
步骤 3：按 F5 启动调试
    ↓
步骤 4：程序停在 bin/webpack-cli.js
    ↓
步骤 5：按 F11（单步进入）进入源码
    ↓
步骤 6：自动跳转到 src/bootstrap.ts
    ↓
步骤 7：继续单步调试 TypeScript 源码

5.3 调试演示

调试步骤详解：

code

┌─────────────────────────────────────────────────────────┐
│ 调试流程演示                                             │
└─────────────────────────────────────────────────────────┘

1. 选择调试配置
   ┌─────────────┐
   │ CLI Debug   │ ← 选择这个配置
   └─────────────┘

2. 启动调试（F5）
   → 程序停在 bin/webpack-cli.js 第17行

3. 单步进入（F11）
   → 从 JS 文件进入 lib/bootstrap.js

4. Source Map 自动映射
   → VS Code 自动打开 src/bootstrap.ts
   → 显示原始 TypeScript 代码

5. 继续调试
   → 在 TypeScript 源码中单步执行
   → 查看变量、调用栈等

5.4 调试快捷键回顾

快捷键	功能	使用场景
`F5`	开始调试	启动调试会话
`F9`	切换断点	添加/移除断点
`F10`	单步跳过	执行当前行，不进入函数
`F11`	单步进入	进入函数内部
`Shift+F11`	单步跳出	跳出当前函数
`Ctrl+Shift+F5`	重启调试	重新启动

六、Webpack 与 Webpack CLI 入口关系

6.1 入口文件对比

Webpack 入口：

javascript

// webpack/bin/webpack.js

#!/usr/bin/env node
'use strict';

// 检查是否安装了 CLI
if (!cliInstalled) {
  // 提示安装
  console.log('Please install webpack-cli');
  process.exit(1);
}

// 运行 CLI
const runCLI = require('webpack-cli').runCLI;
runCLI(process.argv);

Webpack CLI 入口：

javascript

// webpack-cli/bin/webpack-cli.js

#!/usr/bin/env node
'use strict';

const runCLI = require('../lib/webpack-cli').runCLI;
runCLI(process.argv);

6.2 入口关系图

code

┌─────────────────────────────────────────────────────────┐
│              命令执行流程                                │
└─────────────────────────────────────────────────────────┘

用户执行：webpack --config webpack.config.js
    │
    ▼
┌─────────────────────────────────────────┐
│ webpack/bin/webpack.js                  │
│ （Webpack 的入口）                       │
├─────────────────────────────────────────┤
│ 1. 检查 CLI 是否安装                     │
│ 2. 调用 webpack-cli                     │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ webpack-cli/bin/webpack-cli.js          │
│ （Webpack CLI 的入口）                   │
├─────────────────────────────────────────┤
│ require('../lib/webpack-cli').runCLI    │
└─────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────┐
│ webpack-cli/lib/webpack-cli.js          │
│ （编译后的 CLI 核心）                     │
│            ↕ Source Map 映射             │
│ webpack-cli/src/webpack-cli.ts          │
│ （TypeScript 源码）                      │
└─────────────────────────────────────────┘

6.3 两种调试配置的区别

配置一：Debug Webpack

json

{
  "name": "Debug Webpack",
  "program": "${workspaceFolder}/webpack/bin/webpack.js"
}

配置二：CLI Debug

json

{
  "name": "CLI Debug",
  "program": "${workspaceFolder}/webpack-cli/packages/webpack-cli/bin/webpack-cli.js"
}

区别对比：

配置	入口	说明
Debug Webpack	webpack/bin/webpack.js	从 Webpack 入口开始，会检查 CLI 是否安装
CLI Debug	webpack-cli/bin/webpack-cli.js	直接从 CLI 入口开始，跳过检查

实际效果：

code

Debug Webpack：
  webpack.js → 检查 CLI → 调用 webpack-cli.js → runCLI()

CLI Debug：
  webpack-cli.js → runCLI()
  （跳过了 webpack.js 的检查）

七、调试技巧总结

7.1 调试策略

code

┌─────────────────────────────────────────────────────────┐
│              TypeScript 源码调试策略                     │
└─────────────────────────────────────────────────────────┘

策略一：从入口开始
├── 1. 在 bin/webpack-cli.js 打断点
├── 2. 单步进入（F11）
├── 3. 跟随 Source Map 进入 TS 源码
└── 4. 逐层深入

策略二：直接在源码打断点
├── 1. 在 src/*.ts 文件中直接打断点
├── 2. 启动调试（F5）
└── 3. 自动停在源码位置

策略三：关键位置断点
├── 1. 找到关键函数
├── 2. 在函数入口打断点
└── 3. 快速定位核心逻辑

7.2 常用调试操作

查看变量：

code

1. 鼠标悬停在变量上
2. 在"变量"面板查看
3. 在"监视"面板添加表达式

查看调用栈：

code

1. 在"调用堆栈"面板查看
2. 点击栈帧跳转到对应代码
3. 理解函数调用关系

在控制台执行代码：

javascript

// 在调试停住时，可以在控制台执行
console.log(someVariable);

// 或直接输入变量名查看
someVariable

八、常见问题与解决方案

问题	原因	解决方案
断点停在 JS 文件而非 TS 源码	Source Map 未生成或未启用	编译时确保 `sourceMap: true`
找不到 Source Map 文件	编译未成功或路径错误	检查 lib/ 目录下是否有 .map 文件
VS Code 提示"未验证的断点"	outFiles 配置错误	添加正确的 outFiles 路径
调试时显示编译后代码	launch.json 缺少 sourceMaps 配置	添加 `"sourceMaps": true`
无法进入 TypeScript 源码	F11 进入的是其他函数	确认光标位置，使用正确的单步操作

九、完整调试流程总结

9.1 流程图

code

┌─────────────────────────────────────────────────────────┐
│         Webpack CLI TypeScript 源码调试流程             │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 1. 配置 tsconfig.json                                   │
│    "sourceMap": true                                    │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 2. 编译 TypeScript                                      │
│    tsc --build 或 yarn build                            │
│    生成 .js 和 .js.map 文件                             │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 3. 配置 VS Code 调试                                    │
│    launch.json 添加 sourceMaps 和 outFiles              │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 4. 在源码或入口打断点                                    │
│    src/*.ts 或 bin/*.js                                 │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 5. 启动调试                                             │
│    选择 CLI Debug，按 F5                                 │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 6. 单步进入源码                                         │
│    F11 进入函数，Source Map 自动映射                     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│ 7. 在 TypeScript 源码中调试                             │
│    查看变量、调用栈，分析代码逻辑                         │
└─────────────────────────────────────────────────────────┘

9.2 关键命令汇总

bash

# 编译 TypeScript（生成 Source Map）
cd webpack-cli/packages/webpack-cli
tsc --build

# 检查是否生成 Source Map
ls lib/*.map

# 应该看到：
# index.js.map
# bootstrap.js.map
# webpack-cli.js.map
# ...

十、学习要点总结

Source Map 是调试 TypeScript 的关键
生成 .map 文件后才能从 JS 映射回 TS 源码
tsconfig.json 必须配置 sourceMap: true
编译时才会生成 Source Map 文件
launch.json 需要配置 sourceMaps 和 outFiles
VS Code 才能正确找到编译产物
可以在 TS 源码中直接打断点
VS Code 会自动映射到编译后的代码
理解 Webpack 和 Webpack CLI 的入口关系
webpack.js 会调用 webpack-cli.js

十一、延伸学习资源

官方资源

十二、思考题

Source Map 的工作原理是什么？它是如何实现源码映射的？
为什么需要在 tsconfig.json 中配置 sourceMap？不配置会怎样？
在 VS Code 中调试 TypeScript 时，如何快速定位到关键代码？
Webpack 和 Webpack CLI 的入口文件有什么区别？为什么要有两个入口？
如何调试一个复杂的 TypeScript 项目？有哪些最佳实践？

笔记整理时间： 2026-03-16
参考环境： TypeScript 5.x / VS Code 1.85
下一步学习： Webpack 打包原理深入分析

二、Source Map 配置

2.1 什么是 Source Map？

2.2 配置 tsconfig.json

2.3 查看配置文件

三、编译 TypeScript 并生成 Source Map

3.1 编译命令

3.2 编译产物

3.3 Source Map 文件示例

四、VS Code 调试配置进阶

4.1 launch.json 配置

4.2 配置项说明

五、调试 TypeScript 源码实战

5.1 打断点策略

5.2 调试流程

5.3 调试演示

5.4 调试快捷键回顾

六、Webpack 与 Webpack CLI 入口关系

6.1 入口文件对比

6.2 入口关系图

6.3 两种调试配置的区别

七、调试技巧总结

7.1 调试策略

7.2 常用调试操作

八、常见问题与解决方案

九、完整调试流程总结

9.1 流程图

9.2 关键命令汇总

十、学习要点总结

十一、延伸学习资源

官方资源

相关工具

十二、思考题