VSCode Java 扩展在 macOS 10.15 及更早版本上的启动失败问题分析

问题背景

近期，VSCode 的 Java 语言支持扩展（v1.27.0）在 macOS 10.15（Catalina）及更早版本的 x64 架构设备上出现了严重的启动失败问题。用户反馈在打开包含 Java 代码的项目时，会收到"Language Support for Java (Syntax Server) client: couldn't create connection to server"的错误提示，导致 Java 功能完全无法使用。

问题表现

当用户在 macOS 10.15 系统上使用 VSCode 打开 Java 项目时，控制台会不断输出以下错误信息：

objc[53522]: CLASS: class 'KeyWindow' 0x113dea680 small method list 0x113de4c68 is not in immutable memory
[Info  - 08:21:50] Connection to server got closed. Server will restart.
false
[Error - 08:21:50] Language Support for Java (Syntax Server) client: couldn't create connection to server.
  Message: write EPIPE
  Code: -32099 

根本原因分析

经过开发团队的深入调查，发现问题源于以下两个关键组件的变更：

1. Equinox Launcher 版本升级：从 v1.2.800 升级到了 v1.2.900，新版本中的 .so 库文件被编译为针对 macOS SDK 11（Big Sur）及以上版本，导致与 macOS 10.15 系统不兼容。

2. JDK 版本变更：从 17.0.9 升级到 17.0.10，虽然这不是主要原因，但也可能影响部分用户的运行环境。

技术细节

Equinox Launcher 是 Eclipse 框架的核心组件之一，负责启动 Java 语言服务器运行时的环境。在 macOS 系统上，它通过特定架构的本地库（.so 文件）与操作系统交互。新版本的 launcher 使用了仅支持 macOS 11+ 的 API，导致在旧系统上出现兼容性问题。

解决方案

开发团队提供了多种临时解决方案：

1. 手动降级 Equinox Launcher：

   • 找到 VSCode 扩展目录中的 org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.2.900.v20240129-1338.jar 文件
   • 将其替换为 v1.26 扩展中的旧版本（1.2.800）
   • 清理 Java 语言服务器工作区（通过命令面板执行"Java: Clean Java Language Server Workspace"）

2. 完全移除问题组件：

   • 删除有问题的 org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.2.900.v20240129-1338.jar 文件
   • 同时删除相关的缓存文件：

     $HOME/Library/Application Support/Code/User/globalStorage/redhat.java/1.27.0/config_mac/org.eclipse.equinox.launcher/org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.2.900.v20240129-1338/eclipse_11900.so
     $HOME/Library/Application Support/Code/User/globalStorage/redhat.java/1.27.0/config_ss_mac/org.eclipse.equinox.launcher/org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.2.900.v20240129-1338/eclipse_11900.so
     

3. 升级到修复版本： 开发团队已经发布了 v1.28.0 修复版本，用户可以直接安装此版本解决问题。

预防措施

对于需要在旧版 macOS 系统上开发 Java 项目的用户，建议：

1. 定期检查扩展更新说明，了解兼容性变化
2. 考虑使用较新的 macOS 系统版本，以获得更好的开发体验
3. 对于关键项目，可以暂时固定使用已知稳定的扩展版本（如 v1.26.0）

总结

这次事件展示了开发工具链中组件兼容性的重要性，特别是当底层依赖项针对新系统版本进行优化时，可能会无意中影响旧系统用户。VSCode Java 扩展团队迅速响应并提供了多种解决方案，体现了对用户体验的重视。

对于开发者而言，这也提醒我们在升级开发环境时需要关注系统兼容性要求，并在发现问题时及时与维护团队沟通，共同完善开源项目。