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

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

警告

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

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

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

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

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

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

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

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

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

1. 点击 VS Code 左侧的“运行和调试”图标 (🐞)。

2. 点击 “创建 launch.json 文件” 链接。

   

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

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

   

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

2️⃣ 启动并配置 HMR

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

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

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

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

调试技巧与工具

调试工具栏

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

断点类型

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

调试侧边栏窗口

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

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

---

上一篇：使用 HMR 实现代码热更新

下一篇：深入理解：两种构建模式的区别