抛弃沉重的 IDEA：VS Code 配置 Quarkus 极速开发环境全记录

抛弃沉重的 IDEA：VS Code 配置 Quarkus 极速开发环境全记录（保姆级避坑指南）

很多习惯了 IntelliJ IDEA 的 Java 开发者，在初次尝试使用 VS Code 开发 Java（特别是 Quarkus / Spring Boot 等微服务框架）时，往往会被一堆红波浪线、莫名其妙的环境报错和找不到的 Debug 按钮折磨得满地找牙。

VS Code 确实轻量级、速度快，但它本身只是个编辑器。要想把它调教成顺手的 Java IDE，里面的水非常深。今天我记录了从零开始在一台干净的 NixOS（Linux）系统上配置 VS Code + Quarkus 开发环境的完整填坑过程，包教包会。

一、基础插件：不能多，也不能少

打开 VS Code，直接在插件市场搜索并安装以下两个核心包：

1. Extension Pack for Java (Microsoft)：这是底座，包含了代码提示、Maven 支持、Debug 引擎和测试管理器。不装它，Java 代码就是纯文本。
2. Quarkus Tools (Red Hat)：Quarkus 专属的魔法提示，比如application.properties的自动补全，纯属锦上添花。

二、环境踩坑：JDK 与 Maven 的爱恨情仇

1. SDKMAN 与 Maven 的挂载

现在大家基本都在用 SDKMAN 来管理 JDK 和 Maven 版本。通过sdk install java 21.0.11-tem和sdk install maven 3.9.6安装完毕后，由于 VS Code 有时无法自动嗅探到外部的 Maven 路径，我们需要手动在全局的settings.json中给它指路：

"maven.executable.path":"/home/gateman/.sdkman/candidates/maven/current/bin/mvn"

如果你接手的 Quarkus 项目里刚好没有生成mvnw（Maven Wrapper）脚本，VS Code 左侧的 Maven 插件面板就会罢工报错。加上这行配置，或者直接在项目根目录跑一句mvn wrapper:wrapper生成mvnw，烦人的弹窗就会消失。

2. JDK Runtime 与 Compiler 版本的撕裂

在开发中你可能会遇到一个诡异的现象：明明在 VS Code 的Java: Configure Java Runtime界面里选了 JDK 21，点击 Apply 之后，它又奇迹般地跳回了 JDK 17。然后代码里所有的 Java 21 新语法（比如Map.of()）全都爆红。

填坑指南：
在 VS Code 的逻辑里，pom.xml才是绝对的权威，UI 只是个摆设。
如果你遇到了版本跳回的问题，直接打开你的pom.xml，修改 Maven Compiler 插件的版本：

<properties><maven.compiler.release>21</maven.compiler.release></properties>

然后按Ctrl + Shift + P，输入Java: Clean Java Language Server Workspace，选择 Restart and delete。等它重新读取完pom.xml，你的工程级别就老老实实锁定在 JDK 21 了。

(避坑补充：记得检查你的src/main/docker/Dockerfile.jvm，如果第一行写的还是FROM eclipse-temurin:17-jre-alpine，一定要同步改成21，否则将来打包镜像时容器启动会直接报错。)

三、性能调优：别让 VS Code 把内存干爆

1. Language Server 的 OOM 陷阱

写着写着代码，右下角突然弹出一个报错：Java 插件内存不足。如果你点击它提示的Increase Memory...蓝色按钮，恭喜你，你掉坑里了。

VS Code 会“贪心”地在项目的.vscode/settings.json里写入一个极其夸张的参数（比如-Xmx16G，直接吃掉你全部的物理内存），导致 Java 插件在后台直接崩溃闪退。

正确解法：
打开全局settings.json，手动给 Java 语言服务器分配一个合理的堆内存（比如 2G 足矣），并加上 GC 优化参数：

"java.jdt.ls.vmargs":"-XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xmx2G -Xms1G -Xlog:disable"

重启窗口后，代码提示会变得极度丝滑。

2. 代码格式化缺失

第一次保存代码时，可能会弹出是否下载 Formatter 的提示。直接点 Yes，它会在项目下生成一个.vscode/eclipse-formatter.xml。VS Code 底层使用的是 Eclipse 的格式化引擎，有了这个文件，你再也不用纠结团队缩进打架的问题，直接Shift + Alt + F一键排版。

四、测试与 Debug：找回丢失的按钮与日志

1. JUnit 测试没法运行？

如果你新建了一个测试类，却发现满屏红波浪线，根本认不出@Test。别怀疑，你的脚手架里大概率漏了测试包。在pom.xml里补上它并重载项目：

<dependency><groupId>io.quarkus</groupId><artifactId>quarkus-junit5</artifactId><scope>test</scope></dependency>

2. 我的 “Run / Debug” 悬浮按钮去哪了？

从 IDEA 转过来的朋友习惯在@Test上方看到灰色的 Run/Debug 快捷字样。但在新版 VS Code 插件里，它被默认关闭了。
可以通过修改settings.json强行召唤回来：

"editor.codeLens":true,"java.test.editor.enableShortcuts":true

或者直接点击行号旁边的绿色小按钮，又或者打开左侧长得像“化学烧瓶 🧪”的 Test Explorer 界面，那里可以精确到具体方法的单步调试。

3. Quarkus 特有的 LogManager 报错

当你满心欢喜地点击 Debug 跑单测时，可能会在控制台开头看到一行红色的刺眼报错：
The LogManager accessed before the "java.util.logging.manager" system property was set...

原因及解决：
Quarkus 底层接管了日志，而普通的 JUnit 启动流程会抢先打印，导致冲突。我们需要在.vscode/settings.json里为测试配置加上专属参数，强制指定日志管理器：

"java.test.config":[{"name":"quarkus-test","vmargs":["-Djava.util.logging.manager=org.jboss.logmanager.LogManager"]}]

同时，为了在测试期间能在DEBUG CONSOLE里看到org.jboss.logging.Logger打印的业务日志，别忘了在src/main/resources/application.properties里加上：

quarkus.log.console.enable=true quarkus.log.level=INFO

(注：一定要在 Debug Console 或 Terminal 里看日志，默认的 Test Results 面板只显示测试通信协议的无用输出)

五、终极实战：Quarkus API 远程断点调试

在 VS Code 里调试 Quarkus 接口，最优雅的方式不是直接用插件点运行，而是利用 Quarkus 的连续测试（Continuous Testing）加远程挂载（Remote Attach）。

1. 终端启动服务
   在 VS Code 终端里直接敲：

mvn quarkus:dev

服务会在 8080 端口启动，并同时在 5005 端口开启调试监听（你会看到Listening for transport dt_socket at address: 5005）。同时，终端会被 Quarkus 接管，按r可以随时无缝跑单测。

2. 配置挂载 Debug
   在项目的.vscode/launch.json里写入以下配置：

{"version":"0.2.0","configurations":[{"type":"java","name":"Debug Quarkus (Attach to 5005)","request":"attach","hostName":"localhost","port":5005}]}

3. 见证奇迹
   在 VS Code 左侧进入 Debug 面板，选择Debug Quarkus并点击绿色的播放键。此时 VS Code 会瞬间 Attach 到正在运行的微服务上。
   你在 Controller 里打下一个红色的断点，然后打开另一个终端敲一句curl http://localhost:8080/svc1。
   VS Code 会瞬间闪烁切回前台，死死地卡在断点处，左侧变量一览无余！而且你改完代码直接保存，热更新瞬间生效，断点依然工作。

六、一点 Git 规范补充

如果你的项目是一个 Monorepo（大仓库下的子文件夹），最好在子模块（比如apps/quarkus-svc/）下建立自己专属的.gitignore。

# Maven target/ .mvn/wrapper/maven-wrapper.jar # IDEs .idea/ .settings/ .vscode/ # Others *.log .DS_Store

如果之前误提了，记得先跑一句git rm -r --cached target/把它们从 Git 的索引里踢出去。

总结

VS Code 写 Java 就像玩乐高，初期需要你花费一两个小时去拼装和填坑（配环境、改内存、修配置）。但当你把这一套调教完毕后，那秒开的轻量级体验、Quarkus 飞一样的热部署速度，绝对会让你觉得这几十分钟的折腾是完全值得的。

Happy Coding！