martial-master/.vscode/DEBUG_GUIDE.md

VS Code 调试指南

前置要求

确保已安装以下 VS Code 扩展：

1. Extension Pack for Java (Microsoft)
   • 包含：Language Support for Java, Debugger for Java, Maven for Java 等
2. Spring Boot Extension Pack (VMware)
   • 包含：Spring Boot Tools, Spring Initializr 等

安装方式：

• 按 Ctrl+Shift+X 打开扩展面板
• 搜索 "Extension Pack for Java" 并安装
• 搜索 "Spring Boot Extension Pack" 并安装

一、Debug 运行（推荐）

方法 1：使用侧边栏（最简单）

1. 打开运行和调试面板：

   • 快捷键：Ctrl+Shift+D (Windows/Linux) 或 Cmd+Shift+D (Mac)
   • 或点击左侧活动栏的「运行和调试」图标

2. 选择配置：

   • 在顶部下拉框选择：Debug Spring Boot App (Dev)

3. 开始调试：

   • 点击绿色的「启动调试」按钮（三角形）
   • 或按 F5

4. 设置断点：

   • 在代码行号左侧点击，出现红点即为断点
   • 例如在 Controller 方法中打断点

5. 调试操作：

   • F5 - 继续执行
   • F10 - 单步跳过
   • F11 - 单步进入
   • Shift+F11 - 单步跳出
   • Shift+F5 - 停止调试

方法 2：右键快速启动

1. 打开主类：

   • 打开 src/main/java/org/springblade/Application.java

2. 右键运行：

   • 在编辑器中右键
   • 选择 Run Java 或 Debug Java

方法 3：使用命令面板

1. 按 Ctrl+Shift+P (或 Cmd+Shift+P)
2. 输入 Java: Run
3. 选择 Debug Spring Boot App (Dev)

二、普通运行（无调试）

使用终端运行

# 在 VS Code 集成终端中（Ctrl+`）
cd /remote_dev/martial/martial-master

# 加载 Java 环境
source ~/.sdkman/bin/sdkman-init.sh

# 运行应用
mvn spring-boot:run

使用 Maven 侧边栏

1. 点击左侧 Maven 图标（M）
2. 展开 blade-api → Plugins → spring-boot
3. 右键 spring-boot:run → Run Maven Goal

三、构建任务

按 Ctrl+Shift+B 可以快速访问构建任务：

• Maven: Clean - 清理 target 目录
• Maven: Compile - 编译项目
• Maven: Package (Skip Tests) - 打包（默认任务）
• Maven: Install BladeX Framework - 编译 BladeX 框架依赖
• Spring Boot: Run Dev - 后台运行开发环境
• Kill Java Process on Port 8123 - 停止占用 8123 端口的进程

四、端口转发设置

自动转发（推荐）

VS Code Remote SSH 会自动检测端口 8123，只需：

1. 应用启动后，底部会出现提示
2. 点击「在浏览器中打开」即可

手动添加端口

1. 打开端口面板：

   • 按 Ctrl+Shift+P
   • 输入 Forward a Port
   • 输入 8123

2. 或使用端口视图：

   • 点击底部状态栏的「端口」标签
   • 点击「+」添加端口
   • 输入 8123

3. 访问应用：

   • 浏览器访问：http://localhost:8123/doc.html
   • Knife4j API 文档自动打开

批量转发（开发常用端口）

在端口面板添加：

• 8123 - Spring Boot 应用
• 33066 - MySQL
• 63379 - Redis

五、调试配置说明

已配置的调试选项：

1. Debug Spring Boot App (Dev)

• 用途：开发环境调试
• 配置文件：application-dev.yml
• 快捷键：F5 启动

2. Debug Spring Boot App (Test)

• 用途：测试环境调试
• 配置文件：application-test.yml

3. Debug Current Java File

• 用途：调试单个 Java 文件（有 main 方法）
• 使用：打开文件后按 F5

4. Attach to Remote JVM

• 用途：连接到远程 JVM 进程
• 端口：5005
• 使用场景：当应用已在运行时附加调试器

六、常见问题

问题 1：找不到主类

解决方案：

# 清理并重新编译
mvn clean compile

# 或在 VS Code 中
Ctrl+Shift+P -> Java: Clean Java Language Server Workspace

问题 2：端口 8123 已被占用

解决方案：

# 查找占用端口的进程
lsof -i:8123

# 或使用配置的任务
Ctrl+Shift+P -> Tasks: Run Task -> Kill Java Process on Port 8123

问题 3：Maven 依赖未找到

解决方案：

# 先编译 BladeX 框架
cd /remote_dev/martial/martial-tool
mvn clean install -DskipTests

# 或使用任务
Ctrl+Shift+P -> Tasks: Run Task -> Maven: Install BladeX Framework

问题 4：断点不生效

原因：代码未重新编译

解决方案：

• 停止调试 (Shift+F5)
• 重新编译 (Ctrl+Shift+B)
• 再次启动调试 (F5)

问题 5：MySQL/Redis 连接失败

检查服务：

# MySQL
docker ps --filter "name=dev-mysql"

# Redis
docker ps --filter "name=dev-redis"

# 如未运行，启动它们
docker start dev-mysql dev-redis

七、调试技巧

1. 条件断点

• 在断点上右键 → Edit Breakpoint
• 输入条件，例如：userId == 1

2. 日志断点

• 右键断点 → Edit Breakpoint
• 勾选 Log Message
• 输入消息，例如：User ID: {userId}

3. 异常断点

• 调试面板 → BREAKPOINTS → 点击 +
• 选择 Java Exception Breakpoints
• 输入异常类名，如：NullPointerException

4. 查看变量

• 鼠标悬停在变量上查看值
• 或在左侧 VARIABLES 面板查看所有变量
• 右键变量 → Copy Value 复制值

5. 表达式求值

• 调试时，点击 DEBUG CONSOLE
• 输入表达式并执行，例如：

  user.getName()
  list.size()
  

6. 热重载（Spring Boot DevTools）

• 修改代码后自动重启应用
• 已在 pom.xml 中配置（如果需要）

八、快捷键速查表

操作	Windows/Linux	Mac
开始调试	F5	F5
停止调试	Shift+F5	Shift+F5
单步跳过	F10	F10
单步进入	F11	F11
单步跳出	Shift+F11	Shift+F11
继续执行	F5	F5
切换断点	F9	F9
打开调试面板	Ctrl+Shift+D	Cmd+Shift+D
打开终端	Ctrl+`	Ctrl+`
命令面板	Ctrl+Shift+P	Cmd+Shift+P
构建任务	Ctrl+Shift+B	Cmd+Shift+B

九、开发工作流

典型开发流程：

1. 启动服务：

   # 确保 MySQL 和 Redis 运行
   docker ps
   

2. 开始调试：

   • 按 F5 启动应用
   • 等待应用启动（看底部终端日志）

3. 转发端口：

   • VS Code 自动转发 8123
   • 或手动添加

4. 访问应用：

   • 浏览器：http://localhost:8123/doc.html

5. 设置断点：

   • 在 Controller 或 Service 方法中打断点

6. 测试 API：

   • 在 Knife4j 界面发起请求
   • VS Code 会在断点处暂停

7. 修改代码：

   • 停止调试 (Shift+F5)
   • 修改代码
   • 重新启动调试 (F5)

8. 查看日志：

   • 集成终端显示应用日志
   • 或查看 application.log 文件

十、推荐扩展

除了必需的扩展，还推荐：

• REST Client - 直接在 VS Code 测试 API
• Database Client - 连接 MySQL 查看数据
• GitLens - Git 增强工具
• Error Lens - 内联显示错误
• Better Comments - 增强注释高亮
• Material Icon Theme - 美化文件图标

---

快速开始：按 F5 即可开始调试！