【VS Code】 Spring Boot `main` 方法不显示 Run

VS Code Spring Boot `main` 方法不显示 Run | Debug 经验总结

适用场景 ：内网隔离环境（无法访问 repo.maven.apache.org），通过内部 Nexus/Maven 私服拉取依赖。

背景条件

本文假设以下前置条件已满足：

VS Code 已安装 Extension Pack for Java （包含 Language Support for Java (Red Hat)、Debugger for Java、Maven for Java、Project Manager for Java、Test Runner for Java）
VS Code 已安装 Spring Boot Extension Pack （包含 Spring Boot Tools、Spring Initializr、Spring Boot Dashboard）
以上扩展均已启用且版本正常，无需重新安装或排查扩展问题
JDK 已正确配置，JAVA_HOME 指向有效路径
Maven 已正确安装，命令行 mvn --version 可正常执行

术语解释

术语	全称	含义
JDT LS	Java Development Tools Language Server	Eclipse 基金会维护的 Java 语言服务器，VS Code 的 `Language Support for Java (Red Hat)` 扩展在底层运行它，负责代码补全、编译诊断、项目构建等所有 Java 语言功能。它运行在独立进程中，和命令行 `mvn` 是两个完全不同的进程
M2E	Maven to Eclipse	Eclipse 生态的 Maven 集成组件，JDT LS 通过它来读取 `pom.xml`、解析模块结构和下载依赖。它有自己的 Maven 依赖解析逻辑
CodeLens	---	VS Code 在代码行上方显示的嵌入式快捷操作，如 `main` 方法上的 `Run

关键文件路径速查

排查过程中涉及的所有文件及其在 Windows 上的绝对路径（%USERPROFILE% 即 C:\Users\<当前用户名>）：

文件	路径	用途
项目根 `pom.xml`	`<项目根目录>\pom.xml`	Maven 项目描述文件
用户级 Maven 配置	`%USERPROFILE%\.m2\settings.xml`	命令行 `mvn` 读取的用户配置（可能不存在，需手动创建）
全局 Maven 配置	`<Maven安装目录>\conf\settings.xml`	Maven 安装时自带的全局配置
本地 Maven 仓库	`%USERPROFILE%\.m2\repository`	所有 Maven 依赖的本地缓存目录
VS Code 用户设置	`%APPDATA%\Code\User\settings.json`	VS Code 全局用户设置
VS Code 工作区设置	`<项目根目录>\.vscode\settings.json`	项目级 VS Code 设置（可能不存在）
JDT LS 工作区缓存	`%APPDATA%\Code\User\workspaceStorage\<hash>\redhat.java`	JDT LS 项目模型缓存，损坏时需删除

现象

主要现象 ：@SpringBootApplication 类的 main 方法上方不显示 Run | Debug CodeLens。

常见伴随现象（可能同时出现若干个）：

伴随现象	说明
所有或部分 `pom.xml` 报红波浪线	表示 JDT LS 无法解析 Maven 依赖
Java 源文件 import 语句报红	如 `import org.springframework...` 被标记为 "The import cannot be resolved"
状态栏长时间显示 `Importing Maven project(s)` 或 `Building workspace`	项目导入卡住或异常缓慢
`Spring Boot Dashboard` 中不显示当前项目	项目未被识别为 Spring Boot 项目
`JAVA PROJECTS` 面板中项目为空或无内容	JDT LS 未建立项目模型
输入代码时无自动补全或跳转	语言服务功能全面失效
`Ctrl+Shift+P` → `Java: List All Java Source Paths` 为空	项目源码路径未被正确识别

关键判断依据 ：如果命令行 mvn compile 能成功但 VS Code 内报错，说明 JDT LS 和 Maven CLI 之间存在隔离，问题在 JDT LS 一侧。

根因分析

根据社区大量案例和实际排障经验，此类问题通常由以下几个原因引发（按概率排序）：

原因 1（内网特化）：JDT LS 未读取 settings.xml mirror → 直连 Maven Central 失败 → 缓存阻断（占比最高）

复制代码

内网无法访问 Maven Central
  → JDT LS 解析 POM 时直连 repo.maven.apache.org 失败
    → 在本地仓库写入 .lastUpdated 缓存阻断文件
      → 即使 POM 文件存在，也标记为 "present, but unavailable"
        → 项目模型损坏（"<module> does not exist"）
          → CodeLens 消失

本质：JDT LS 内嵌的 Maven 解析器（M2E）默认不读取 Maven settings.xml。修复方式是通过 VS Code 的 java.import.maven.userSettings 配置项显式指定 settings.xml 路径，让 JDT LS 读取其中的 <mirror> 配置。一旦正确配置并清除旧缓存，JDT LS 即可通过内网 mirror 正常解析依赖，不需要修改 pom.xml。

原因 2（通用）：VS Code 打开的不是正确的项目根目录

VS Code 要求将包含根 pom.xml 的目录作为工作区根目录打开。常见错误：

打开的是父目录（如打开了整个 workspace 文件夹而非 workspace/<project>/）
在多模块项目中打开了子模块目录而非根目录
使用 File → Open File 打开了单个 Java 文件，而非 Open Folder

原因 3（通用）：Maven 多模块项目中子模块未被正确识别

典型场景：根 pom.xml 的 <modules> 中声明了子模块，但子模块目录不存在或名称不匹配，导致整个 reactor 构建失败，JDT LS 无法建立项目模型。

原因 4（通用）：`java.configuration.runtimes` 中 JDK 版本与 `pom.xml` 中 `<java.version>` 不匹配或 JDK 路径失效

%APPDATA%\Code\User\settings.json 中配置的 java.configuration.runtimes 与实际使用的 JDK 不一致时，会导致编译错误进而影响项目导入。

原因 5（通用）：JDT LS 工作区缓存损坏

中途关闭 VS Code、磁盘空间不足、或 Maven 导入过程被异常中断，可能导致 %APPDATA%\Code\User\workspaceStorage\<hash>\redhat.java 中的缓存不一致。

原因 6（偶发）：CodeLens 开关关闭

%APPDATA%\Code\User\settings.json 中：

json 复制代码

"java.debug.settings.enableRunDebugCodeLens": true

常见错误示例

错误 1：parent POM "present, but unavailable"（内网典型错误）

全量错误信息（VS Code 输出 面板 → Language Support for Java）：

text 复制代码

Project build error: Non-resolvable parent POM for <groupId>:<artifactId>:<version>:
The following artifacts could not be resolved:
org.springframework.boot:spring-boot-starter-parent:pom:X.X.X (present, but unavailable):
failed to transfer from https://repo.maven.apache.org/maven2 during a previous attempt.
This failure was cached in the local repository and resolution is not reattempted
until the update interval of central has elapsed or updates are forced.
Original error: 这是在主机名解析时通常出现的暂时错误 (repo.maven.apache.org)

关键词 ：present, but unavailable、failed to transfer、cached in the local repository

排查路径：

打开 %USERPROFILE%\.m2\repository\org\springframework\boot\spring-boot-starter-parent\<版本号>
若存在 *.lastUpdated 文件，说明 JDT LS 上次解析失败并写入了阻断标记
即使该目录下 *.pom 正常存在，.lastUpdated 也会导致 JDT LS 将其视为不可用

错误 2：JDT LS 项目模型损坏

全量日志（VS Code 输出 面板 → Language Support for Java）：

复制代码

Error: <module-name> does not exist
Java Model Exception: Error in Java Model (code 969): <module-name> does not exist

排查路径：

此错误发生在 JDT LS 尝试获取模块的 main class 列表时
根因是上一步 POM 解析失败，导致 JDT LS 工作区缓存中存储的项目模型不完整
查看当前工作区对应的 hash：打开 %APPDATA%\Code\User\workspaceStorage，依次检查各子目录下的 workspace.json，找到包含当前项目路径的那个

解决方案

方案 A（内网特化，对应原因 1）：让 JDT LS 读取 settings.xml mirror 配置

适用条件 ：命令行 mvn 能正常编译，但 VS Code 内 pom.xml 报红、错误日志中出现 failed to transfer from https://repo.maven.apache.org。

关键点 ：JDT LS 能够读取 settings.xml，但需要（1）通过 java.import.maven.userSettings 明确指定路径，（2）工作区缓存未被上次失败污染。问题根源在于 JDT LS 的默认行为是不读取 settings.xml，但通过配置可以让它读取。修复后不需要在 pom.xml 中加任何仓库声明。

Step 1 --- 创建或确认用户级 Maven 配置：

操作文件：%USERPROFILE%\.m2\settings.xml

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0
                              https://maven.apache.org/xsd/settings-1.2.0.xsd">
    <mirrors>
        <mirror>
            <id>nexus-internal</id>
            <name>内网 Maven Mirror</name>
            <url>http://<内网Nexus地址:端口>/repository/maven-public/</url>
            <mirrorOf>*</mirrorOf>
        </mirror>
    </mirrors>
</settings>

如果公司已有全局 conf/settings.xml 且中有内网 mirror，也可直接把该文件复制到此路径。

Step 2 --- 在 VS Code 中指定 settings.xml 路径：

操作文件：%APPDATA%\Code\User\settings.json

json 复制代码

"java.import.maven.userSettings": "%USERPROFILE%\\.m2\\settings.xml"

注意：如果配置后仍无效，说明 JDT LS 工作区缓存中残留了上次失败的项目模型，必须执行 Step 3 清除缓存。

Step 3 --- 清除阻断缓存 + JDT LS 缓存，然后重建（详见方案 E）：

删除 %USERPROFILE%\.m2\repository 中相关 .lastUpdated 文件
执行 Java: Clean Java Language Server Workspace 或手动删除 %APPDATA%\Code\User\workspaceStorage\<hash>\redhat.java
完全退出 VS Code ，重新启动后用 File → Open Folder 打开项目根目录

备选方案 （不推荐）：如果上述配置始终不生效，可在 <项目根目录>\pom.xml 中直接追加 <repositories> 和 <pluginRepositories> 声明内网地址。此做法的缺点是侵入项目文件、影响团队协作，仅建议作为最后手段。

方案 B（通用，对应原因 2）：确认工作区根目录正确

关闭 VS Code 中当前打开的所有文件夹
用 File → Open Folder 重新打开包含根 pom.xml 的目录
不要打开父目录或子模块目录
如果项目包含多个独立子工程，考虑使用 .code-workspace 多根工作区文件

方案 C（通用，对应原因 3）：验证 Maven 多模块结构完整

命令行执行 mvn validate，确认 reactor 中所有模块都 BUILD SUCCESS
确认根 pom.xml 的 <modules> 中列出的目录全部存在且包含子 pom.xml
如果有多余的模块声明或已删除的模块残留，从 <modules> 中移除

方案 D（通用，对应原因 4）：验证 JDK 配置

检查 %APPDATA%\Code\User\settings.json 中 java.configuration.runtimes 配置：

json 复制代码

"java.configuration.runtimes": [
    {
        "name": "JavaSE-17",
        "path": "<JDK 17 安装路径>",
        "default": true
    }
]

同时检查 <项目根目录>\pom.xml 中 <java.version> 与 JDK 版本匹配。运行 mvn -version 确认输出中的 JDK 版本与配置一致。

方案 E（通用，对应原因 5/6）：执行缓存清理 + 重建

Step 1 --- 清除 .lastUpdated 阻断缓存：

powershell 复制代码

# 替换版本号为实际值
Remove-Item -Recurse -Force `
    "$env:USERPROFILE\.m2\repository\org\springframework\boot\spring-boot-starter-parent\<版本号>"
Set-Location <项目根目录>
mvn dependency:resolve -U

Step 2 --- 清除 JDT LS 工作区缓存（二选一）：

方式一（VS Code 命令，推荐）：

Ctrl+Shift+P → Java: Clean Java Language Server Workspace → 选择 Reload and delete

方式二（手动）：

powershell 复制代码

$wsDir = "$env:APPDATA\Code\User\workspaceStorage"
foreach ($d in Get-ChildItem $wsDir -Directory) {
    $json = Join-Path $d.FullName "workspace.json"
    if ((Get-Content $json -Raw) -like "*<项目文件夹名>*") {
        Remove-Item -Recurse -Force (Join-Path $d.FullName "redhat.java")
    }
}

Step 3 --- 重启 VS Code：

完全退出 VS Code （不光是 Developer: Reload Window）
重新启动，用 File → Open Folder 打开项目根目录
等待状态栏 Importing Maven project(s) → Building workspace 全部完成
打开 *Application.java，main 上方应出现 Run | Debug

综合排查流程

复制代码

1. 确认 VS Code 扩展已装
       ↓ 已装
2. mvn compile 是否成功？
    ┌─ 否 → 修 Maven / JDK / 网络 / 仓库配置
    │
    └─ 是 → 3. pom.xml 是否报红？
               ├─ 是（内网） → 方案 A：配 settings.xml + userSettings → 清缓存
               │
               └─ 否 → 4. 方案 B：检查工作区根目录是否正确
                          ↓
                       5. 方案 C：检查多模块结构
                          ↓
                       6. 方案 D：检查 JDK 配置
                          ↓
                       7. 方案 E：清缓存 → 重启 → 验证

【VS Code】 Spring Boot `main` 方法不显示 Run | Debug 经验总结