# 深入调试：VS Code 断点调试指南

`console.log()` 是快速检查的利器，但面对复杂逻辑，你需要更专业的武器：**断点调试 (Debugger)**。它能让代码在任意位置“暂停”，让你像侦探一样审查当时的每一个细节。

:::warning
**⚠️ 注意**：目前暂不支持直接对神岛的内置 API (如 `world.createEntity()`) 进行断点。
:::

## 调试前的核心概念：编译模式

在启动调试前，你需要选择一种代码编译模式。这决定了你的代码如何被打包，以及调试的便捷程度。

| 编译模式     | 特点                                                          | 推荐程度                   |
| ------------ | ------------------------------------------------------------- | -------------------------- |
| **HMR 编译** | 自动监听文件变化并增量编译。**支持直接在 `.ts` 文件上断点**。 | ⭐⭐⭐⭐⭐<br>**强烈推荐** |
| **完整编译** | 每次都重新打包所有代码。只能在编译后的 `.js` 文件上断点。     | ⭐⭐<br>**备用选择**       |

**结论：进行断点调试时，请始终使用 HMR 编译模式。**

## TypeScript 断点调试工作流 (HMR 模式)

这是最常用、最高效的调试流程。

### 1️⃣ 创建调试配置文件 (`launch.json`)

如果你是第一次在项目中进行调试，需要先生成一个 `launch.json` 文件来告诉 VS Code 如何启动。

1.  点击 VS Code 左侧的“运行和调试”图标 (🐞)。
2.  点击 **“创建 launch.json 文件”** 链接。

    ![创建 launch.json 文件](/QQ20241101-111306.png)

3.  在弹出的列表中，选择一个调试类型。

    - **`ArenaPro Server Debugger`**：调试服务端代码 (`server/`)
    - **`ArenaPro Client Debugger`**：调试客户端代码 (`client/`)

    ![选择调试配置](/QQ20241101-111542.png)

    选择后，VS Code 会自动在 `.vscode/launch.json` 中为你生成配置。你可以通过右下角的“添加配置”按钮来新增更多调试类型。

### 2️⃣ 启动并配置 HMR

1.  点击 VS Code 左下角的 **`HMR 编译`** 按钮，启动 HMR 服务。
2.  **(推荐)** 为了避免干扰，点击 HMR 旁边的“齿轮”图标，**关闭“编译后自动上传”**。
    ![关闭上传功能](/QQ20241101-112658.png)
3.  **(推荐)** 点击“齿轮”图标，**开启“调试器(debugger)模式”**。
    ![开启 debugger 模式](/QQ20241101-142736.png)

### 3️⃣ 设置断点并启动调试

1.  打开任意一个你想调试的 **`.ts`** 文件 (例如 `server/App.ts`)。
2.  在代码行号的左侧**单击**，设置一个**红点**断点。
3.  按下 **`F5`** 键 (或点击“运行和调试”侧边栏的绿色启动按钮)，开始调试！

![调试过程](/QQ20241101-125949.png)

当游戏逻辑执行到你的断点处，代码就会暂停，你可以在 VS Code 中查看所有变量的实时状态。

## 调试技巧与工具

### 调试工具栏

| 图标 | 名称         | 快捷键        | 功能说明                                       |
| :--: | ------------ | ------------- | ---------------------------------------------- |
|  ▶️  | **继续**     | `F5`          | 继续执行，直到下一个断点或程序结束。           |
|  ↪️  | **单步跳过** | `F10`         | 执行当前行，若为函数则直接执行完，不进入内部。 |
|  ⤵️  | **单步调试** | `F11`         | 执行当前行，若为函数则进入其内部。             |
|  ⤴️  | **单步跳出** | `Shift+F11`   | 执行完当前函数，并跳出到调用它的地方。         |
|  🔄  | **重启**     | `Ctrl+Shift+` | 重新启动当前的调试会话。                       |
|  ⏹️  | **停止**     | `Shift+F5`    | 结束本次调试。                                 |

### 断点类型

| 断点类型 | 使用场景                 | 设置方法                         |
| -------- | ------------------------ | -------------------------------- |
| 普通断点 | 在特定代码行暂停执行     | 点击代码行号左侧                 |
| 条件断点 | 仅在满足条件时暂停       | 右键点击断点 → `编辑条件...`     |
| 日志点   | 不暂停，而是输出日志信息 | 右键点击断点 → `添加日志消息...` |

### 调试侧边栏窗口

| 窗口         | 功能说明                               |
| ------------ | -------------------------------------- |
| **变量**     | 查看和修改当前作用域中的变量值。       |
| **监视**     | 添加自定义表达式，持续监控其值的变化。 |
| **调用堆栈** | 显示当前代码是如何被一层层调用至今的。 |
| **断点**     | 集中管理项目中设置的所有断点。         |

通过本教程，你已经掌握了在 ArenaPro 项目中使用 VS Code 进行断点调试的核心技巧。这将是你解决复杂问题、提升代码质量的强大武器。
