Local Tomcat Launcher

在 VSCode 中一键启动 / 停止 / 重启 / 刷新本机 Tomcat，内置 Tomcat 9，支持 JPDA 远程调试、Maven 构建与文件级热加载。

功能特性

• 一键启动 — 内置 Tomcat 9，无需额外安装 Tomcat 即可运行
• 即时停止 — 按 CATALINA_BASE 精准定位并强制终止本实例进程树
• 重启 — 停止后重新启动（加载已经更改的类）
• 刷新 — 停止 + 执行 Maven 打包（mvn package）+ 启动，等同于"重新部署"
• JPDA 调试 — 以 jpda run 模式启动，开放 Debug 端口供 redhat.java 调试器附加
• 热加载 — 基于 JDT.LS 扩展（war-exploded-class-sync）监听构建事件，自动增量同步 .class 到部署目录；资源 / webapp 文件变更由 VSCode 扩展监听并同步
• 资源同步 — src/main/resources / src/main/webapp 文件变更后自动同步到部署目录
• 日志输出 — Tomcat 启动 / 运行 / 停止日志（stdout / stderr）实时输出到 VSCode 输出通道
• JDK 自动识别 — 自动使用 redhat.java 配置的 JDK 版本启动 Tomcat
• 灵活配置 — 支持自定义端口、contextPath、VM 参数、指定外部 Tomcat
• 启动成功精确判定 — 通过注入 Tomcat 的 StartupSignalListener 写信号文件判定，不依赖日志文本匹配

建议

开启 java.autobuild，由 JDT 自动编译

插件依赖 redhat.java 的自动构建（autobuild）来编译 Java 源文件：保存 .java 后 JDT 自动写盘到 target/classes。war-exploded-class-sync JDT.LS 扩展在每次构建完成后将变更的 .class 增量同步到部署目录。请确保 VSCode 设置中 java.autobuild.enabled 为开启（默认开启），否则 .class 不会更新、热加载失效。

前置条件

快速开始

1. 在 VSCode 中打开一个 Maven Web 项目（包含 pom.xml）。
2. 编辑器右上角出现四个紧密排列的按钮：启动（▶）、停止（■）、重启（↻）、刷新（⟳）。
3. 首次使用前，请确保项目已构建（即 target/{finalName} 目录存在）。可点击 刷新 按钮，它会自动执行 mvn package 后再启动；或自行在终端执行 mvn package。
4. 点击 启动，输出通道立即弹出，等待部署完成（状态栏变为「运行中」）。
5. 浏览器访问 http://localhost:{port}/{contextPath} 查看项目，例如 http://localhost:8080/dev。
6. 修改 src/main/java、src/main/resources、src/main/webapp 下的文件并保存后，变更会自动热加载（无需重启）。

配置项

在 VSCode 设置中搜索 support.tomcat：

所有配置项为工作区级别（scope: workspace），修改后立即对下一次启动生效。

使用指南

启动（Start）

点击启动按钮时，插件会依次执行：

1. 防连点保护与状态检查（运行中 / 启动中则提示并返回）。
2. 端口检测：检查 HTTP 端口与 Debug 端口是否被占用，占用则报错并返回。
3. 准备 CATALINA_BASE：在插件存储目录（storageUri/tomcat）下重建隔离目录（conf、logs、temp、work、lib），并复制内置 / 外部 Tomcat 的 conf 配置。
4. 复制 startup-signal-listener.jar 到 CATALINA_BASE/lib（供 server.xml 的 <Listener> 加载）。
5. 修改 server.xml：替换 HTTP 连接器端口与 shutdown 端口（设为 -1），注入 StartupSignalListener（signalDir 指向信号目录）。
6. 修改 logging.properties：让 localhost 日志同时输出到控制台。
7. 写入部署描述符 conf/Catalina/localhost/{contextPath}.xml，docBase 指向 target/{finalName}（该 finalName 通过 mvn help:evaluate 取得），reloadable="false"。
8. 注入环境变量（合并进程环境后启动）：
   • CATALINA_HOME — Tomcat 安装目录
   • CATALINA_BASE — 隔离实例目录
   • JPDA_ADDRESS / JPDA_TRANSPORT — Debug 端口与 dt_socket
   • JRE_HOME — 自动识别的 JDK 路径（见下文「JDK 版本」）
   • CATALINA_OPTS — 用户配置的 VM 参数（仅 start / run 生效，stop 不使用）
9. 通过 PowerShell 调用 catalina.bat jpda run 启动，日志实时输出到通道。

启动成功判定：通过信号文件机制判定，不依赖日志文本匹配。StartupSignalListener 在 Tomcat Server AFTER_START 事件时遍历所有 webapp context：

• 全部 context 状态为 STARTED → 写 success.tomcat（权威成功信号）
• 存在 context 非 STARTED（FAILED / STOPPED 等）→ 写 fail.tomcat（含失败 context 列表），扩展收到后杀掉半启动的 Tomcat 进程并报错

VSCode 扩展通过 FileSystemWatcher 监听信号目录（storageUri/signal/*.tomcat），收到 success.tomcat 判定成功，收到 fail.tomcat 判定失败。默认超时 300 秒，超时则判定失败并清理进程。

注意：启动流程不会自动执行 Maven 构建。请确保在启动前 target/{finalName} 已存在（使用「刷新」按钮或先 mvn package）。

JDK 版本

Tomcat 启动时自动使用 redhat.java 扩展识别的 JDK，查找优先级：

1. java.configuration.runtimes 中 default: true 的路径
2. java.configuration.runtimes 中第一个有 path 的运行时
3. java.jdt.ls.java.home
4. 系统环境变量 JAVA_HOME
5. 系统环境变量 JRE_HOME

若均不可用，输出警告并回退到系统默认 JRE_HOME / JAVA_HOME。

停止（Stop）

点击停止按钮（仅运行中 / 启动中允许）：

1. 标记「本次启动为主动取消」，避免启动过程中的进程退出被误报为「启动失败」。
2. 通过 WMI 查询 Win32_Process（name LIKE 'java%' AND commandLine LIKE '%CATALINA_BASE%'，路径中的反斜杠已做 WQL 转义）定位本实例的 java 进程，Stop-Process -Force 结束。
3. 状态栏回到「已停止」。

重启（Restart）

点击重启按钮：若当前运行中 / 启动中，先执行停止，再执行启动。重启会重建 CATALINA_BASE 配置，但不会重新执行 Maven 打包（若需重新打包请使用「刷新」）。

刷新（Refresh）

点击刷新按钮：若当前运行中 / 启动中，先执行停止，随后执行 mvn clean package -DskipTests -T 1C 重新打包，再执行启动。等价于「重新构建并部署」。

热加载（Hot Reload）

热加载由两个机制协同完成，无需重启 Tomcat：

机制一：JDT.LS 扩展自动同步 .class（war-exploded-class-sync）

通过 package.json 的 contributes.javaExtensions 将 war-exploded-class-sync.jar 加载进 JDT.LS（redhat.java）进程，作为 OSGi bundle 运行：

• bundle 激活后注册 workspace 级 POST_BUILD 资源监听器，在每次 JDT 构建完成后收集 target/classes 下变更的 .class（新增 / 修改 / 删除）
• 异步 Job 将变更 .class 增量同步（复制 / 删除）到 target/{finalName}/WEB-INF/classes（即 war:exploded 解压目录）
• 仅处理带 org.eclipse.m2e.core.maven2Nature 且 packaging=war 的工程
• WarTarget 缓存：解析后的 Maven finalName 和目标路径会缓存，避免每次构建都重新加载 Maven 模型（减少 m2e 锁竞争）
• 去抖合并：连续保存触发的多次 autobuild 在 300ms 窗口内合并为一次同步 Job，减少 CPU / 磁盘争用
• pom.xml 变更时自动使缓存失效，确保 finalName 更新后重新解析

前提：需开启 redhat.java 的 java.autobuild.enabled（默认开启）。保存 .java 后 JDT 自动编译写盘，bundle 在构建完成后同步到部署目录。

机制二：src/main/** 文件监听（防抖 1 秒）+ pom.xml 监听（防抖 5 秒）

VSCode 扩展通过 FileSystemWatcher 监听源码变更，按类型分组处理：

文件 / 文件夹删除时，部署目录中对应的文件或文件夹会被同步删除。Git 原子写入产生的临时文件（.git 后缀 / .git/ 目录）会被自动过滤。

防抖与去重机制

• src/main 变更：1 秒内多次变更批量处理，同一文件仅保留最新操作（create / change / delete）。
• pom.xml 变更：5 秒内多次变更只处理一次。

.java 源文件变更不需要扩展处理——JDT autobuild 编译写盘后，war-exploded-class-sync bundle 自动同步 .class 到部署目录 + JPDA HotSwap（方法体修改）使变更生效。

部署目录说明

部署目录为工作区下的 target/{finalName}，与 writeContextXml 写入的 docBase 一致，即 Tomcat 实际服务的目录：

• target/{finalName}/WEB-INF/classes — 编译产物与 resources 同步目标
• target/{finalName}/WEB-INF/lib — 依赖（pom.xml 变更后复制）
• target/{finalName}/... — webapp 资源同步目标

finalName 通过 mvn help:evaluate -Dexpression=project.build.finalName 取得；它必须与 docBase 一致，否则热加载会同步到错误目录。

输出通道

插件创建名为 Tomcat 的输出通道，实时显示：

• Tomcat 启动 / 运行 / 停止日志（stdout / stderr）
• 信号文件判定结果（[信号] 收到 success.tomcat / [信号] 收到 fail.tomcat）
• 热加载操作日志
• JDK 路径回退警告

调试（JPDA）

Tomcat 以 jpda run 启动，开放 support.tomcat.debugPort（默认 5005，JDWP，dt_socket）。在 VSCode 中创建 Remote JVM Debug 配置指向该端口，即可断点调试；方法体内的修改可通过 HotSwap 直接生效，无需重启。

内置组件

插件包含两个 Java 组件，打包为 jar 随扩展分发：

常见问题

Q: 插件不出现按钮？ A: 检查是否满足激活条件：Windows 环境、已安装 redhat.java、当前工作区包含 pom.xml、为单模块 Maven Web 项目。

Q: 端口被占用？ A: 更改 support.tomcat.port 或 support.tomcat.debugPort 配置项，或点击重启 / 停止释放端口后重试。

Q: 启动后访问报 404？ A: 多半是 target/{finalName} 不存在或内容过旧。请先 mvn package（或点击「刷新」按钮），再启动。

Q: HotSwap 不生效？ A: 仅方法体修改支持 HotSwap；新增 / 删除方法、字段等结构性变更需点击「刷新」重新构建并部署。

Q: 能否使用外部 Tomcat？ A: 配置 support.tomcat.home 指向已安装的 Tomcat 目录即可（留空使用内置 Tomcat 9）。

Q: Tomcat 用的 JDK 不对？ A: 插件读取 java.configuration.runtimes 中 default: true 的 JDK 路径。在 VSCode 设置中配置该项即可指定 JDK 版本。

Q: 启动提示 webapp 部署失败？ A: StartupSignalListener 检测到某个 webapp context 未成功启动（状态非 STARTED），输出通道会显示失败 context 列表。检查 web.xml、监听器 / 过滤器类是否缺失、依赖 jar 是否完整。

Q: .class 没有同步到部署目录？ A: 确认 java.autobuild.enabled 已开启；确认项目带有 m2e nature 且 packaging=war。可在 java.jdt.ls.vmargs 中加 -Dccd.debug=true 查看 war-exploded-class-sync bundle 的诊断日志（CCD: 前缀）。

许可证

MIT