三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

VSCode搭建Spring Boot开发环境：从零配置到高效调试

发布时间：2026/8/8 22:54:21 三亩地 编程学习日记
VSCode搭建Spring Boot开发环境：从零配置到高效调试

1. 项目概述：为什么选择VsCode来搞Spring Boot？

如果你是一名Java开发者，尤其是刚入行不久的朋友，可能一提到Spring Boot开发，脑子里蹦出来的第一个工具就是IntelliJ IDEA。它功能强大，开箱即用，但同时也伴随着启动慢、内存占用高、社区版功能受限等问题。今天，我想和你聊聊另一个选择：用Visual Studio Code（简称VsCode）来搭建、创建、运行和调试Spring Boot项目。

这听起来可能有点“非主流”，但实际体验下来，你会发现VsCode在轻量、快速和高度可定制化方面有着独特的优势。特别是对于内存不那么充裕的机器，或者你同时需要处理前端、Python、文档等多种任务时，一个VsCode全搞定，远比在多个重型IDE间切换要舒服得多。Spring Boot本身对开发工具并没有强绑定，只要配置好Java环境、构建工具和必要的插件，在任何编辑器里都能玩得转。VsCode凭借其海量的插件生态，完全有能力提供一套流畅的Spring Boot开发体验。

接下来，我将带你从零开始，完成在VsCode中搭建Spring Boot开发环境、创建新项目、运行应用，并进行断点调试的全过程。过程中，我会穿插我踩过的坑和总结的技巧，让你能更平滑地上手。

2. 环境准备与核心插件配置

工欲善其事，必先利其器。在VsCode里玩转Spring Boot，核心不在于VsCode本身，而在于我们为它安装的“扩展程序”。这些插件将把VsCode从一个文本编辑器，武装成一个功能齐备的Java IDE。

2.1 基础环境检查

在安装任何插件之前，请确保你的系统已经准备好了以下三样东西：

  1. Java Development Kit (JDK)：Spring Boot 3.x 需要 JDK 17 或更高版本；Spring Boot 2.x 通常需要 JDK 8 或 11。我建议直接安装JDK 17，它是一个长期支持版本，兼容性最好。在终端输入java -version来验证。
  2. Apache Maven 或 Gradle：这是项目的构建和依赖管理工具。Spring Initializr生成的项目默认提供这两种选择。在终端输入mvn -v或gradle -v来验证。
  3. Visual Studio Code：从官网下载并安装最新稳定版即可。

注意：很多朋友遇到的“vscode运行java报错乱码”问题，其根源往往不是VsCode本身，而是系统命令行终端的编码问题。在Windows上，可以尝试在VsCode的集成终端里执行chcp 65001将活动代码页设置为UTF-8，或者直接修改VsCode终端配置，将默认的PowerShell或CMD改为使用Git Bash等更友好的终端。

2.2 必须安装的VsCode插件

打开VsCode的扩展市场（Ctrl+Shift+X），搜索并安装以下插件，这是整套工作流的基石：

  • Extension Pack for Java：这是微软官方出品的Java扩展包，一个顶多个。它包含了：

    • Language Support for Java(TM) by Red Hat：提供代码补全、重构、导航等核心语言功能。
    • Debugger for Java：Java调试器，支持断点、变量查看、调用栈等。
    • Java Test Runner：运行和调试JUnit/TestNG测试。
    • Maven for Java：提供Maven项目支持，可以运行Maven命令、查看依赖树。
    • Project Manager for Java：管理Java项目。 一键安装这个扩展包，能省去大量配置时间。

  • Spring Boot Extension Pack：这是Pivotal（Spring母公司）官方提供的Spring Boot扩展包。它包含了：

    • Spring Boot Tools：为application.properties/application.yml提供智能提示、补全和校验，支持从配置文件直接跳转到对应的@ConfigurationProperties类。
    • Spring Initializr Java Support：让你可以直接在VsCode里通过图形界面创建Spring Boot项目，无需打开浏览器访问 start.spring.io。
    • Spring Boot Dashboard：在侧边栏提供一个仪表盘，可以快速启动、停止、重启你的Spring Boot应用，非常方便。 这个包是提升Spring Boot开发体验的关键，特别是配置文件的智能提示，能极大减少拼写错误。

  • Gradle for Java：如果你的项目使用Gradle构建，那么这个插件可以提供任务运行、依赖管理等功能。如果是Maven项目，则可以不装。

安装完插件后，建议重启一下VsCode，让所有插件完全生效。

3. 创建你的第一个Spring Boot项目

有了插件，创建项目就变得异常简单。这里我介绍两种最常用的方法。

3.1 方法一：使用Spring Initializr插件（推荐）

这是最直观、最像IDEA的方式。

  1. 按下Ctrl+Shift+P打开命令面板。
  2. 输入Spring Initializr并选择Spring Initializr: Create a Maven Project（或Gradle Project）。
  3. 选择Spring Boot版本：插件会联网获取可用的版本列表。建议选择最新的稳定版（非SNAPSHOT和RC版）。
  4. 输入项目信息：
    • Group Id：通常为公司域名倒写，如com.example。
    • Artifact Id：你的项目名，如myfirstboot。
    • Java版本：这里务必选择你本地安装的JDK版本，如17。
  5. 选择依赖：这是最关键的一步。你可以通过输入关键字来搜索和添加依赖，例如输入web添加Spring Web，输入data jpa添加Spring Data JPA，输入lombok添加Lombok。插件会实时更新pom.xml的预览。对于初学者，一个Spring Web依赖就足够创建一个REST API项目了。
  6. 选择项目路径：指定项目生成的文件夹。
  7. 打开项目：生成完成后，插件会问你是否要打开。选择“Open”，VsCode就会在新窗口中加载这个全新的Spring Boot项目。

3.2 方法二：使用官方网站生成后导入

如果你更喜欢在浏览器里慢慢挑选配置，或者网络环境导致插件连接Initializr较慢，可以用这个传统方法。

  1. 打开浏览器，访问https://start.spring.io。
  2. 在网页上手动选择项目类型（Maven/Gradle）、语言、Spring Boot版本，填写项目元数据，勾选你需要的依赖（如Web, JPA, Lombok等）。
  3. 点击“GENERATE”按钮，下载一个ZIP压缩包。
  4. 在本地解压ZIP包，然后用VsCode的“文件” -> “打开文件夹”菜单，打开这个解压后的项目目录。

无论用哪种方法，项目打开后，VsCode右下角通常会弹出提示，询问你是否要信任该文件夹的作者以及是否要导入项目。点击“是”或“信任”。Java扩展会自动识别这是一个Maven/Gradle项目，并开始在后台下载依赖（你可以在底部状态栏看到进度）。这个过程可能会持续几分钟，取决于你的网速和依赖数量。

4. 项目运行与基础调试

项目创建好，依赖下载完毕，我们就可以让它跑起来了。

4.1 多种运行方式

方式A：使用Spring Boot Dashboard（最方便）安装完Spring Boot扩展包后，VsCode活动栏（最左边那竖排图标）会多出一个带有“叶子”图标的按钮，这就是Spring Boot Dashboard。点击它，你会在侧边栏看到当前工作区里识别出的所有Spring Boot项目。项目旁边会有绿色的三角形“启动”按钮，点击它即可运行。运行后，按钮会变成红色的方形“停止”按钮。这里还可以同时运行多个Boot应用，管理起来一目了然。

方式B：使用VsCode的“运行和调试”视图

  1. 点击活动栏的“运行和调试”图标（或按Ctrl+Shift+D）。
  2. 点击“运行和调试”按钮旁边的下拉菜单，你会看到插件已经为我们生成了几个启动配置，通常包括“Java: Launch Current File”和“Spring Boot Dashboard”。
  3. 直接按F5键，VsCode会尝试使用默认配置启动调试。但更推荐你先进行配置。

方式C：通过终端命令运行打开VsCode内置终端（Ctrl+`），在项目根目录下执行：

  • Maven项目：./mvnw spring-boot:run(使用项目自带的Maven Wrapper) 或mvn spring-boot:run
  • Gradle项目：./gradlew bootRun或gradle bootRun

这种方式最“原生”，你能在终端里直接看到Spring Boot标志性的启动日志。当你需要传递特定参数（如激活某个Profile）时，这种方式很灵活。

4.2 配置启动参数与调试

默认配置可能不满足所有需求，比如我们想指定运行端口、激活某个配置文件，或者传递JVM参数。

  1. 在项目根目录下创建.vscode文件夹（如果不存在）。
  2. 在.vscode文件夹内创建launch.json文件。当你第一次点击“运行和调试”视图的“创建launch.json文件”时，VsCode可能会自动生成一个。
  3. 一个典型的用于Spring Boot调试的launch.json配置如下：
{ "version": "0.2.0", "configurations": [ { "type": "java", "name": "Debug MySpringBootApp", "request": "launch", "mainClass": "com.example.myfirstboot.MyFirstBootApplication", // 替换为你的主类全限定名 "projectName": "myfirstboot", // 替换为你的项目名（Maven的artifactId） "args": "--server.port=8081 --spring.profiles.active=dev", // 自定义程序参数 "vmArgs": "-Xmx512m -Dmy.custom.flag=true" // 自定义JVM参数 } ] }

配置好后，在“运行和调试”视图的下拉菜单中选择“Debug MySpringBootApp”，然后按F5，应用就会以调试模式启动，并应用你指定的参数。

进行调试： 在代码行号左侧点击设置断点，然后启动调试。程序运行到断点处会暂停，此时你可以：

  • 查看变量：在“变量”面板查看当前作用域内的所有变量值。
  • 逐步执行：使用调试工具栏的“单步跳过”(F10)、“单步进入”(F11)、“单步跳出”(Shift+F11)来逐行跟踪代码。
  • 计算表达式：在“调试控制台”中输入变量名或表达式，实时查看结果。
  • 条件断点：右键点击断点，可以设置条件，只有满足条件时才会暂停，这在循环调试中非常有用。

实操心得：调试时，如果修改了代码，需要重启应用才能生效。Spring Boot DevTools可以实现热重启，但在VsCode的调试模式下，直接重启调试会话（停止再按F5）是最可靠的方式。对于简单的配置变更，DevTools的热重启是有效的，可以节省时间。

5. 核心开发体验优化与问题排查

让VsCode用起来顺手，还需要一些额外的配置和问题解决技巧。

5.1 配置文件智能提示与Lombok支持

配置文件提示：安装了Spring Boot Tools插件后，在application.properties或application.yml里输入server.，你会立刻得到port、servlet、context-path等属性的提示。这是开发效率的巨大提升。如果提示不生效，检查插件是否已正确安装并启用。

Lombok支持：Lombok可以通过注解自动生成Getter、Setter、构造函数等代码，但它在编译期工作。为了让VsCode的Java插件能正确识别这些生成的方法，需要进行配置：

  1. 在VsCode的设置中（Ctrl+,），搜索java.compile。
  2. 找到Java > Compiler > Annotation Processing下的设置。
  3. 确保Enabled是勾选状态。
  4. 在User或Workspace设置中，可以添加以下配置来为当前项目指定注解处理器路径（如果自动检测失败）：
    "java.compile.annotationProcessorPaths": [ "org.projectlombok:lombok:你的lombok版本号" ]
    通常，插件能自动处理，如果代码中Lombok注解报错（如找不到getXxx()方法），可以尝试在命令面板运行Java: Clean Java Language Server Workspace命令，然后重启VsCode。

5.2 常见问题与解决方案实录

即使配置得当，开发中还是会遇到一些“坑”。这里记录几个我高频遇到的问题和解决方法。

问题1：启动时报“无法找到主类”或“主清单属性”错误。

  • 排查思路：
    1. 检查launch.json中的mainClass路径是否正确。最保险的方法是打开主类文件（有@SpringBootApplication注解的类），然后复制资源管理器地址栏中显示的全限定名。
    2. 对于Maven项目，运行mvn clean compile确保编译成功。
    3. 检查项目是否被正确识别为Java项目。查看VsCode底部状态栏，应该显示类似“Java 17”和“Maven”的图标。如果没有，可以尝试在命令面板运行Java: Import Projects或Maven: Update All Projects。

问题2：依赖下载失败或报红。

  • 排查思路：
    1. 检查网络，特别是Maven中央仓库的访问。可以尝试在终端执行mvn dependency:resolve看具体报错。
    2. 检查pom.xml或build.gradle文件语法是否正确。
    3. 清理本地Maven仓库缓存。到~/.m2/repository（用户目录下）删除相关依赖的文件夹，然后重新下载。
    4. 在VsCode中，打开Maven视图（活动栏的M图标），右键点击项目，选择“Update All Snapshots”或“Reimport”。

问题3：调试时断点不生效（显示为灰色空心圆）。

  • 排查思路：
    1. 确保是以调试模式启动（按F5），而不是直接运行。
    2. 断点打在正确的行上，确保那是可执行代码行（不是空行或注释）。
    3. 检查源代码是否与运行的类文件版本一致。确保你没有在编辑一个未被编译的旧文件。
    4. 尝试在命令面板运行Java: Clean Java Language Server Workspace，然后重启调试。

问题4：终端输出中文乱码。

  • 解决方案（针对Windows）：
    1. 修改VsCode终端默认Shell。按Ctrl+Shift+P，输入Terminal: Select Default Profile，选择Git Bash或Windows PowerShell（如果系统是Win11+）。
    2. 在VsCode设置中搜索terminal.integrated.profiles.windows和terminal.integrated.defaultProfile.windows，进行配置。
    3. 或者在当前终端会话中临时执行chcp 65001。
    4. 对于Maven输出的乱码，可以尝试在~/.m2/settings.xml中为Maven指定UTF-8编码。

5.3 提升效率的VsCode技巧

  1. 多项目工作区：如果你同时开发前端和后端，可以将前端项目文件夹和后端Spring Boot项目文件夹放在同一个VsCode工作区中。这样可以在一个窗口内管理所有代码，并使用统一的终端。
  2. 任务配置：你可以将常用的Maven命令（如clean package）配置为VsCode任务。在.vscode/tasks.json中定义后，可以通过Ctrl+Shift+P运行“任务”，避免在终端重复输入长命令。
  3. 代码片段：对于经常编写的代码结构（如Controller、Service层模板），可以创建自定义代码片段。通过“文件”->“首选项”->“配置用户代码片段”，选择Java，即可添加。
  4. 集成Git：VsCode的源代码管理视图提供了优秀的Git支持。你可以完成提交、拉取、推送、解决冲突等大部分操作，无需离开编辑器。

从最初的怀疑到现在的熟练使用，我个人体会是，VsCode对于Spring Boot开发来说，已经完全够用，甚至在响应速度和资源占用上更有优势。它的核心优势在于“按需装配”——你只需要安装必要的插件，就能获得一个高度定制化的开发环境，而不是被一个庞大IDE的所有功能所包围。对于全栈开发者，或者喜欢轻量级工具的开发者，这无疑是一个极具吸引力的选择。当然，IDEA在深度代码分析、重构和框架集成方面依然有它的优势，但对于大多数常规的Spring Boot开发任务，VsCode已经能提供95分以上的体验。最后一个小建议是，定期更新你的Java扩展和Spring Boot扩展包，开发团队一直在持续改进，新版本往往会带来更好的性能和更少的问题。

编程学习 学习日记 实战经验
← 返回列表