Eclipse IDE 与 Spring Tools
很多团队把 Eclipse 的使用问题归结为“换个 workspace”或“清一下缓存”。这种经验偶尔能止血，却没有回答最重要的问题：插件从哪里来、项目配置由谁保存、运行入口是否共享、换一台机器能不能重建。
可以先把 Eclipse 看成四层工程对象：安装产品提供 IDE 和插件，workspace 保存本机工作状态，项目文件保存应该随代码流转的模型，外部构建工具决定项目脱离 IDE 后能否构建。Spring Tools 是安装在这套体系上的 Spring 专用工具，不是 Spring 项目真实构建模型的替代品。把这四层混成一个目录，才会出现“老员工机器正常，新人复制完仍然全红”的局面。
先建立一条不依赖 IDE 的基线
拿一个能够在终端独立构建的仓库开始。Maven 项目应提交 mvnw、.mvn/ 和 pom.xml，Gradle 项目应提交 gradlew、gradle/wrapper/ 和构建脚本。先在项目根执行仓库约定的验证命令；只有 CLI 成功后，IDE 导入失败才值得归因给 Eclipse。
还要确认三类运行时不是一回事：启动 Eclipse 的 Java、Spring Tools 语言服务器使用的 Java、项目编译和运行使用的 JRE/JDK。它们可以是同一个安装，也可以按兼容边界分开。不要为了让旧项目编译，把整个 IDE 强行降到旧 JDK。
企业网络下还要先拿到代理、根证书和允许访问的更新站点清单。p2 会下载并执行插件代码；“能连上更新站点”不是“该站点已获准进入研发环境”。这条基线把网络、供应链和项目模型分开，后续每一次失败才有可比较的起点。
先理解 workspace 为什么不能当项目模板
Eclipse 启动时选择的 workspace 是资源容器和本机状态目录。其 .metadata 保存视图布局、索引、工作集、插件状态、历史与大量机器相关信息。把整个 workspace 放进 Git，会把绝对路径、缓存和个人操作痕迹一起带给别人，也无法得到稳定复现。
真正应该跟项目走的是项目根中的声明式文件：
.project 描述 Eclipse 项目名称、nature 和 builder。.classpath 描述 Java 源目录、输出目录和 classpath 容器；由 Maven/Gradle 管理时不要手工维护依赖条目。.settings/ 保存项目级编译器、格式化、资源编码和特定插件设置。
pom.xml、build.gradle(.kts) 与 Wrapper 才是构建依赖的权威。可共享的 .launch 文件可以保存团队运行入口，但必须移除绝对路径、账号、token 和真实服务地址。
因此，新人入场的目标不是复制老员工的 .metadata，而是让一个空 workspace 通过仓库文件、受控插件源和少量自动化任务恢复到可构建、可运行、可调试的状态。
选择安装入口：package、Installer 还是 Spring Tools 发行包
Eclipse 官方同时提供预组装 package 和 Eclipse Installer。package 是按 Java、Enterprise Java、C/C++ 等用途组合好的压缩包，适合离线归档、并行保留多个版本和精确回退；Installer 由 Oomph 驱动，适合选择产品版本、安装目录、JVM、代理和后续项目 setup。
下载时先匹配操作系统与 CPU 架构，再校验发布来源。Windows 上不要把压缩包直接放在受写保护目录后继续安装插件；macOS 遇到隔离属性或签名拦截时，应重新确认下载来源，而不是关闭系统安全机制；Linux 需要确认桌面依赖与目录写权限。
只做普通 Java 开发时，从 Eclipse IDE for Java Developers 起步即可。需要 Web/JPA 等工具再选择 Enterprise Java package，不要用“大包一定省事”的思路把无 owner 的插件全装进基线。Eclipse Foundation 发布内容通常按 EPL 2.0 提供，但具体 package 还包含不同许可证的第三方组件，企业分发时要以安装中的 About、feature 与 plug-in 法律文件为准。
Spring 开发有两个稳定入口：
从 Spring Tools 官网 下载现成的 Eclipse 发行包，解压后直接启动。它适合希望开箱即用、让 Spring Tools 与 Eclipse 基座作为一个组合测试的团队。
在受支持的现有 Eclipse 中，通过 Marketplace 或 Help -> Install New Software 安装 Spring Tools。Spring Tools 安装页给出的 release p2 地址是 https://cdn.spring.io/spring-tools/release/update/latest/，使用较旧 Eclipse 基座时应选择该页列出的专用更新站点，而不是把 latest 硬装进不兼容基座。
第二种方式更灵活，却会扩大兼容矩阵：Eclipse 基座、JDK、Spring Tools、m2e/Buildship 和其他插件都可能互相约束。团队应记录“产品版本 + 安装方式 + 插件版本 + 更新源”，不能只写“装最新版 STS”。Eclipse 基座采用 EPL 2.0；发行包与插件还会带入其他许可证组件，企业再分发时应从 About -> Installation Details 追到 feature、plug-in 和法律文件，而不是拿基座许可证覆盖整套产品。
安装后从 Help -> About Eclipse IDE -> Installation Details 记录产品版本、configuration 与已安装软件。若要观察启动期错误，可从安装目录使用下面的诊断启动方式：
eclipse -consoleLog预期结果是 IDE 正常打开，启动日志同时输出到控制台。-clean 会重建 OSGi 缓存，只应作为有证据的诊断动作，不应写进日常启动脚本。
第一次启动：用显式 workspace 建立可审计入口
不要长期接受随机默认目录。首次启动时选择一个专门的 workspace，例如 workspaces/sample-java；也可以用启动参数把 workspace 显式化：
eclipse -data <workspace-directory>-data 后面是 workspace，不是 Git 仓库根。一个 workspace 可以包含多个项目；同一个 Git 仓库也可能导入多个 Eclipse 项目。若团队有多个互不兼容的插件栈或客户项目，拆分 workspace 可以降低索引和配置污染，但不要为每个分支复制一套安装产品。
进入 IDE 后依次确认：
Preferences -> Java -> Installed JREs 中存在项目需要的 JDK，并给团队约定的 Execution Environment 做映射。Preferences -> General -> Workspace 的文本编码符合仓库约定，优先由项目 .settings 固化而非依赖个人默认值。Maven/Gradle 工具使用项目 Wrapper，避免 IDE 内嵌版本与 CI 漂移。
自动构建、保存动作和格式化策略与仓库门禁一致，避免首次导入就制造大面积无关 diff。
p2 安装不是点“信任”就结束
p2 是 Eclipse 的软件供应与更新系统。安装流程会解析 installable units、下载 artifacts、校验签名并写入产品 profile。p2 信任机制说明：由 Java 运行时信任库中的 X.509 根签名的 artifact 默认受信；未知证书、PGP key 或未签名内容会进入 Trust Artifacts 对话框；未签名内容始终应视为不受信。
安装 Spring Tools 或其他插件时按下面的顺序操作：
从产品官网复制 HTTPS p2 地址，不从搜索结果或聊天记录接收临时镜像。在 Available Software Sites 中保留必要源，关闭废弃、快照和重复源。在安装计划页核对 feature 名称、版本、提供者和许可证。
Trust Artifacts 出现时查看每个 signer。企业基线不应启用“允许所有 unsigned artifacts”。重启后到 Installation Details 复核版本，并执行项目最小验证。
如果代理做了 TLS 检查，常见现象是仓库可在浏览器打开，p2 却报 PKIX 或证书链错误。判断时先区分网络不可达、代理认证失败、JVM trust store 缺企业根证书和 artifact 自身未签名。正确修复是让运行 Eclipse 的 JVM 信任受控企业 CA，并由安全团队核验更新源；不要改成 HTTP，也不要无条件信任所有 signer。
更新失败后可以在 Help -> About -> Installation Details -> Installation History 查看先前 configuration 并尝试 revert。回退前先备份项目未提交修改；revert 回的是安装 profile，不会替你回滚项目代码和 workspace 中的所有状态。
用 Oomph 把“口口相传”变成 setup
Oomph 不只是 Eclipse Installer 的界面。它把产品安装与 workspace 准备建模为 setup tasks：选择产品和版本、安装 p2 feature、设置偏好、克隆 Git、导入项目、配置工作集、执行资源创建或启动任务。Oomph scope 模型把任务放入 product、project、stream、installation、workspace、user 等层级；最终执行计划是这些 scope 的组合，不是一份简单偏好导出。
团队的 Oomph 基线应把可共享事实写进受版本控制的 .setup：
固定 Eclipse 产品流和允许的 p2 仓库。声明必须插件的 installable unit，而不是录制整个个人插件列表。克隆占位仓库 URI，并把用户身份、分支或目录做成变量。
导入需要的项目，建立 working set，并设置必要的项目无关偏好。给代理、凭证和机器路径留本地输入，不把值写进 setup。
第一次使用时可在 Installer 的 Advanced Mode 添加项目 setup，或在已安装 Eclipse 中通过 File -> Import -> Oomph -> Projects into Workspace 选择项目流。确认页应检查将要执行的 p2、Git、Preference 和导入任务；执行后查看 Oomph progress，而不是只看最终 IDE 是否打开。
Oomph 的优势是可重复执行，风险也来自可执行能力。一个 setup 可以下载插件、克隆仓库和改偏好，所以它与脚本一样需要代码审查、owner、版本和回滚。个人快捷键可以放 user scope；项目必须插件和项目导入放 project scope；机器代理与证书不应提交。
导入真实项目：先让模型一致，再等待索引
对于 Maven 项目，选择 File -> Import -> Maven -> Existing Maven Projects，定位包含聚合 pom.xml 的根目录，确认模块列表后完成。对于 Gradle，使用 File -> Import -> Gradle -> Existing Gradle Project 或 Buildship 对应入口，优先选择 Gradle Wrapper。已有 .project 的普通项目可用 General -> Existing Projects into Workspace。
导入不是复制源码。除非明确需要，不勾选“Copy projects into workspace”。项目仍留在 Git 工作树，workspace 只持有资源映射和索引状态。
导入完成后不要立刻修改红线。先等待右下角构建与索引结束，再检查 Problems、Error Log 和构建工具控制台。Maven 项目可执行 Maven -> Update Project，Gradle 项目可执行 Gradle -> Refresh Gradle Project；这两步是重新同步模型，不是通用清缓存按钮。
最小验证应同时走 CLI 与 IDE：
./mvnw test
# 或
./gradlew testWindows 仓库通常使用 mvnw.cmd test 或 gradlew.bat test。预期是 Wrapper 下载或命中受控依赖、测试成功，并且 Eclipse Problems 中没有由 JDK、classpath 或生成源码目录造成的新增错误。若 CLI 失败，先修仓库或网络；若 CLI 成功而 IDE 失败，再比较 IDE 使用的 JDK、Wrapper、profile 和代理。
Spring Tools 的运行链路与最小验证
Spring Tools 的主要编辑能力由独立 Java language server 进程提供，它通过 LSP 与 Eclipse 集成。Spring Tools 安装说明列出了语言服务器查找 Java 的顺序：专用 *.ls.java.home 设置、JAVA_HOME，再到 PATH。语言服务器 JRE、Eclipse 运行 JRE 和项目 JRE 可以分离；因此“项目使用旧 Java 编译”不等于“Spring Tools 也必须由旧 Java 启动”。
这条进程边界能解释一个典型反例：Wrapper 测试和普通 Java 补全都成功，只有 Spring 配置提示、bean 导航与 Boot Dashboard 消失。此时先打开 Error Log，定位 Spring language server 启动记录，再从操作系统进程列表确认独立 Java 进程使用的可执行文件。若日志出现不支持的 class file version，修正的是语言服务器 JRE；若 Maven/Gradle 编译仍报 source level 错误，修正的才是项目 JRE 或 toolchain。把整个 workspace 删除，只会丢掉证据。
导入一个已有 Spring Boot 项目后，先确认 Spring Boot Dashboard 能识别应用，再用项目本身的 Wrapper 完成测试。随后创建或选择 Spring Boot Launch，启动应用，观察 Console 中的实际 profile、监听端口与启动完成日志。用项目公开的健康入口验证，例如：
curl --fail --max-time 5 http://127.0.0.1:8080/actuator/health这里的 8080 和 /actuator/health 只是无凭证示例，项目若未暴露 Actuator，应使用仓库定义的本地验证入口。预期是 HTTP 成功且应用日志没有绑定失败。不要为了让 Boot Dashboard 显示更多运行时信息，就在共享环境开放敏感 actuator endpoint。
在一个可控方法设置断点，用 Debug As 启动，触发请求并确认线程停在当前源码行。若运行成功但断点不命中，检查启动的是否为同一 module、class 文件是否由当前 workspace 构建、源码与字节码是否一致，而不是先删除整个 workspace。
Launch Configuration 如何共享又不泄密
Eclipse 默认把 Launch Configuration 保存在 workspace 本地。需要团队共享时，在 Run Configurations 的 Common 页把它保存为 Shared file，让 .launch 落入项目目录并进入评审。
共享 .launch 只保存稳定事实：项目名、main class、构建任务、相对 working directory 和无敏感默认参数。数据库密码、云凭证、个人目录、内网域名、生产 profile 和真实 token 不应写入 Arguments、Environment 或 String Substitution。凭证由本地环境、受控 secret 工具或无密钥开发身份注入。
团队至少维护三个入口：快速单测、应用本地启动、最小调试。复杂任务图不要堆在 .launch 中，应复用 Maven/Gradle/Task 脚本，使终端、IDE 与 CI 调用同一个权威命令。
用新 workspace 证明环境可重建
旧 workspace 可以因为多年缓存“看起来正常”。真正有区分度的实验必须从空目录开始：
提交或暂存当前代码，记录旧 workspace 路径和安装产品版本。退出 Eclipse，使用 eclipse -data <new-empty-workspace> 启动。通过 Oomph、Team Project Set 或受控手工步骤重新导入仓库。
等待 p2、构建模型和索引完成，执行 Wrapper 测试。从共享 .launch 启动并调试应用。比较 Problems、JDK、插件列表和 Git 工作树；重建过程不应产生业务文件 diff。
预期结果是新 workspace 不复制 .metadata 也能恢复。若只有旧 workspace 成功，差异就是待治理资产：可能是未提交 .settings、本地 JRE 映射、隐藏的 Maven profile、未记录插件、生成源码配置或个人环境变量。
再做一次反向实验：不要复制 .metadata，只在新 workspace 中故意省略一个必需 p2 feature 或切换到错误 JRE，然后重复导入。记录 Error Log、Problems、Wrapper 输出和 Spring language server 进程。修复缺失项后，同一工作区应恢复且 Git 工作树保持干净。这个实验验证的是“声明能驱动状态恢复”，不是“清缓存碰巧治好一次”。
确认新 workspace 可用后，旧 workspace 先改名保留一个短回退窗口，再删除。不要在 Eclipse 运行时直接删除 .metadata；也不要把 workspace 清理与 Git clean 混成一条命令。
清理、卸载与回滚
卸载插件优先通过 Installation Details -> Installed Software -> Uninstall，完成后重启并复测。手工删除 plugins/ 或 features/ 目录会破坏 p2 profile 与磁盘内容的一致性。
移除一个 workspace 时先确认源码没有存放在 workspace 内且所有修改已提交，再删除 workspace 目录。移除安装产品时，可删除独立解压目录；Installer/Oomph 用户还应检查对应 installation、bundle pool 与缓存是否仍被其他产品使用。bundle pool 能让多个安装共享 artifact，不能因为一个 IDE 退役就盲删公共池。
回滚顺序应从小到大：撤回项目设置变更、revert p2 installation history、切回并行保留的旧产品、最后才回到旧 workspace。代码、安装产品和 workspace 是三套状态，回滚时必须分别记录。
故障排查：从现象走到根因
导入后项目全红，但 CLI 能构建
先判断 Eclipse 使用的 JDK、Execution Environment、Maven/Gradle Wrapper 与 active profile。常见原因是 IDE model 尚未同步、生成源码目录未识别、项目 .settings 缺失，或 Eclipse 使用了另一套 Maven settings。修复后重新 update/refresh project，并用 Problems 数量与 Wrapper 测试再验证。
p2 报 PKIX、签名未知或 unsigned content
PKIX 更像 TLS 信任链问题；未知 signer 是 artifact 身份尚未获信；unsigned 则表示 artifact 没有可验证签名。三者不能用同一个“点信任”处理。收集更新源 URL、Eclipse 运行 JVM、证书链和 Trust Artifacts 列表，修复企业 CA 或更换官方签名源后重试，并确认没有开启全局允许 unsigned artifacts。
Spring Tools 没有补全，Boot Dashboard 也不识别项目
先看 Error Log、Spring language server 日志和 Java 进程，再确认项目是受支持的 Maven/Gradle Java 项目、构建模型已完成、语言服务器 JRE 可启动。若升级后出现，核对 Spring Tools 与 Eclipse 基座专用 p2 站点，不要把 workspace 重建当成插件二进制不兼容的修复。
Eclipse 启动卡住或不断崩溃
用 -consoleLog 收集启动错误，检查工作区锁、磁盘空间、JVM 崩溃日志和最近插件变更。只有日志指向 OSGi 缓存时才临时尝试 -clean。若新 workspace 同样失败，问题更可能在安装产品、JVM 或原生库；若只有旧 workspace 失败，再缩小到 workspace 状态。
新 workspace 无法复现旧环境
比较的重点不是窗口布局，而是 JDK 映射、插件 feature、项目 .settings、共享 .launch、Oomph task 与外部凭证入口。补齐声明式基线后再次从空 workspace 验证，直到不需要复制 .metadata。
架构选型与边界
Eclipse package 适合把产品压缩包做成受控制品并并行回退；Installer/Oomph 适合规模化安装和项目物化；Spring Tools 发行包适合减少 Spring 工具与基座组合测试；向已有 Eclipse 加插件适合已有统一 Eclipse 平台的组织。选择标准不是个人喜好，而是团队能维护多少兼容组合、是否需要离线仓库、是否能执行新 workspace 重建。
Eclipse 没有一个可以替代团队配置治理的账号云同步层。个人 Preferences 导出文件只适合少量偏好迁移，Team Project Set 主要描述仓库与项目恢复，Oomph 才能承载更完整的产品与 workspace setup。它们职责不同，不能拿一个 .epf 冒充团队环境即代码。
权限、凭证与敏感信息
p2 插件与 IDE 同进程或以子进程运行，可以读源码、访问网络和启动程序。插件准入要检查来源、签名、许可证、更新通道和数据外发边界。Spring Tools 的运行时信息能力可能访问本地或远端 Actuator；应使用最小权限 endpoint，不保存生产凭证。
提交前扫描 .settings、.launch、Oomph .setup、Maven/Gradle settings 引用和日志。特别检查绝对路径、代理账号、Git 用户名、内网主机、数据库 URL、token、密钥路径与环境变量实值。示例应使用占位值，真实凭证只存在于批准的本地或团队 secret 入口。
团队治理与长期维护
团队应给 Eclipse 基线指定 owner，并维护一份可机器读取或可审查的产品清单：Eclipse release、JVM、Spring Tools/p2 feature、允许更新源、Wrapper 规则、项目 .settings、共享 .launch 与 Oomph setup 版本。每次升级先在样板项目和全新 workspace 上验证，再进入小范围试用。
发布基线至少证明四件事：CLI 构建通过，空 workspace 导入后无新增错误，共享 Launch 能运行和调试，插件回退与旧产品并行启动可用。季度清理重点看废弃 p2 源、无 owner 插件、膨胀 workspace、过期 JDK、遗留 installation 和不再使用的 bundle pool；清理前先做引用盘点。
团队自检
安装来源、CPU 架构、Eclipse/JVM/Spring Tools 版本有记录。p2 只保留批准的 HTTPS 源，未知 signer 和 unsigned artifact 没有被全局放行。项目可由 Wrapper 独立构建，.settings 和共享 .launch 不含机器路径与凭证。
Oomph setup 有 owner、评审、变量边界和回滚版本。已用空 workspace 完成导入、构建、运行、调试和无意外 diff 验证。旧产品、旧 workspace 和 bundle pool 的清理范围经过引用确认。