Eclipse IDE 工程手册
换 workspace 只能判断问题在哪，不能替团队修好环境
Eclipse 出现红线、索引异常或启动卡住时，“换一个 workspace”确实是一项有用实验。新工作区正常，说明故障更接近旧工作区状态；新工作区也失败，问题更可能在安装产品、JVM、插件或项目本身。可惜很多团队把这个诊断动作写成最终方案：旧目录被随手删除，真正缺失的项目设置和插件基线也一起消失，下次换电脑仍会重演。
要把 Eclipse 变成可支持的开发工具，先把四类对象拆开。安装产品包含 Eclipse Platform 与插件；workspace 的 .metadata 保存本机资源映射、索引、视图和历史；仓库里的 .project、.classpath、.settings/ 与构建文件描述项目；Maven、Gradle、JDK 和外部命令才决定项目离开 IDE 后是否成立。四者可以协作，不能互相冒充。
Spring Tools 不再塞进这篇正文。它是建立在 Eclipse 和独立语言服务器之上的另一款产品，安装、JRE 与运行验证见 Spring Tools 工程手册。
先定安装产品，再定 workspace
Eclipse Installer 与预组装 package 都是官方入口。Installer 适合通过 Oomph 选择产品、安装目录、JVM 和后续 setup；ZIP/package 更适合企业归档、离线分发、多版本并存和快速回退。不要因为 Enterprise Java package 组件更多，就把它作为所有开发者的默认。基线应从实际项目需要的 Java、C/C++、Web 或建模能力出发，每个额外 feature 都会扩大更新、许可证和供应链维护面。
下载时核对操作系统、CPU 架构、镜像来源和校验信息。Windows 解压目录要允许当前用户写入，否则 p2 更新可能只完成一半；macOS 遇到签名或隔离提示时重新检查来源，不关闭系统保护；Linux 还要确认桌面依赖和 JDK。安装后从 Help -> About Eclipse IDE -> Installation Details 记录产品、configuration、feature 与 plug-in，而不是只记一个桌面快捷方式名称。
启动 Eclipse 的 Java 与项目使用的 Java不是同一个概念。用 eclipse.ini 或产品实际启动记录确认 IDE JVM，再到 Preferences -> Java -> Installed JREs 配置项目 JDK 和 Execution Environment 映射。旧项目需要旧语言级别，不意味着 Eclipse 本身也应该跑在已经停止支持的 JRE 上。
workspace 使用显式目录，并通过启动参数留下可审计入口：
eclipse -data <workspace-directory>这里的目录是 workspace，不是 Git 仓库根。一个仓库可以导入多个 Eclipse project，一个 workspace 也可以容纳多个仓库。只有当插件栈、客户隔离或索引规模确实冲突时才拆 workspace；不要为每条 Git 分支复制一套安装产品。
.metadata 不是团队模板
workspace 中的 .metadata 会记录机器路径、索引、工作集、视图状态、插件数据和 Local History。把它复制给新人，表面上省掉几次导入，实际是把一个未知本机快照当成配置管理。它不适合进入 Git，也不应成为恢复环境的唯一备份。
可共享的 Eclipse 项目事实通常在仓库内。.project 记录 project 名称、nature 和 builder；.classpath 记录源目录、输出目录与 classpath container，由 Maven 或 Gradle 管理的依赖不要人工展开成绝对 jar 路径。.settings/ 可保存项目级编译器、编码、formatter 与插件设置，但每个文件都应说明 owner。共享 .launch 可提供测试或启动入口，只保留相对工作目录和无秘密参数。pom.xml、build.gradle(.kts) 与 Wrapper 仍是构建权威输入。
.settings 也不是越多越好。一次导入后先看 Git diff，分清项目合同与个人 UI 状态；不能解释的自动生成文件不要批量提交。团队允许 Eclipse 参与生成项目配置，但必须能说清它对应哪个 builder、哪个插件和哪项验证。
p2 是软件供应链，不是下载按钮
Eclipse 使用 p2 管理 feature、plug-in 与 installation profile。它会解析依赖、下载 artifact、验证签名并修改产品配置，因此手工删除 plugins/ 目录并不是可靠卸载。p2 信任文档明确区分由 Java trust store 锚定的 X.509 签名、需要人工信任的证书或 PGP key，以及未签名内容。允许安装不等于来源已经安全。
添加软件前从产品或项目官网复制 HTTPS update site，停用过期、nightly 和重复源。安装计划页要检查 installable unit、版本、提供者和许可证；Trust Artifacts 对话框出现时记录 signer，不开启全局“允许所有 unsigned artifacts”。重启后回到 Installation Details 复核，再运行代表项目。
浏览器能打开 update site，而 p2 报 PKIX，通常是运行 Eclipse 的 JVM 不信任企业代理证书；artifact signer 未知则是代码身份问题；unsigned content 又是另一类风险。这三种现象不能都用“点信任”处理。正确证据包括更新源、IDE JVM、TLS 证书链、signer 与安装计划，修复后再安装，不改 HTTP，也不关闭证书校验。
更新造成回归时，Installation History 可以尝试回退 installation profile。它不会回滚项目代码，也不会恢复所有 workspace 状态，所以升级前应并行保留旧产品或可重新安装的归档，并分别记录产品、workspace 和仓库版本。
Oomph 用于恢复环境，不用于复制个人机器
Oomph 能自动化产品安装和 workspace provisioning。官方 scope 模型把 setup task 分布在 product、project、stream、installation、workspace 与 user 等范围。团队真正需要的是把受控 p2 feature、仓库克隆、项目导入、working set 和少量稳定偏好写进可评审的 project setup，而不是导出某位开发者的全部偏好。
一份 setup 可以下载插件、执行 Git 操作并改变配置，它就是代码执行入口。仓库 URI 使用公开占位或无凭证地址；代理、证书、用户名、工作目录和 token 通过本地变量或企业工具注入。项目必需 feature 放 project scope，个人主题和快捷键留在 user scope。变更 setup 时像审查脚本一样检查下载源、执行任务和回滚。
Oomph bundle pool 可让多个安装共享 artifact，能节省磁盘，也意味着清理责任更复杂。退役某个 Eclipse 产品时先确认共享 pool 是否仍被其他 installation 引用，不要把“删除一个版本”扩成“清空所有缓存”。
导入项目时，先让构建模型说话
拿一个终端可以独立构建的仓库做验证。Maven 项目先运行 mvnw，Gradle 项目先运行 Wrapper；CLI 失败时先修依赖源、JDK 或仓库，不让 Eclipse 为坏基线兜底。
Maven 使用 File -> Import -> Maven -> Existing Maven Projects，定位聚合 pom.xml；Gradle 通过 Buildship 导入并选项目 Wrapper；已有 .project 的普通项目使用 Existing Projects into Workspace。导入通常只创建资源映射，不需要把源码复制进 workspace。完成后等待后台构建，再看 Problems、Error Log 和 Maven/Gradle 控制台。
同一项目至少完成三步：终端测试成功；Eclipse 使用相同 JDK、Wrapper 和 profile 后测试成功；设置一个真实断点，用共享或可解释的 Launch Configuration 启动并命中。停止调试后确认目标进程和监听端口已经退出。仅有编辑器补全不能证明运行链成立。若项目包含 annotation processor 或代码生成，还要比较生成目录、触发时机与 CI，防止 Eclipse builder 生成了命令行不存在的源码，或反过来把 target、build 中的旧文件误判为当前结果。
需要共享 Launch 时，在 Common 页保存为项目文件。main class、项目名、构建任务和相对 working directory 可以提交，真实数据库密码、云凭证、内网域名、生产 profile、用户目录与 token 不可以。复杂任务仍应调用仓库脚本，避免终端、IDE 和 CI 各藏一套命令。
用一个故意错误的 JDK 保留反证
干净 workspace 导入并通过测试后，临时把项目映射到不支持目标语言级别的 JDK，或移除一个必需 project nature。预期结果不是“IDE 自己修好”，而是 Problems、build console 或启动退出码稳定暴露错误。记录错误后恢复正确映射并 refresh/build；同一 workspace 应重新通过，Git 工作树不产生无关变更。
这个反例能区分项目声明是否真正控制 IDE。若只有旧 workspace 能通过，而新 workspace 依赖人工点击或某个未知插件，缺失项就是待治理资产。不要先复制 .metadata，否则差异会被重新埋回缓存。
完整重建实验从空目录开始：保存代码修改，记录安装产品；用 -data 指向空 workspace；通过 Oomph 或受控步骤导入；运行 Wrapper、IDE 测试和 Debug；核对 Git diff、Problems、JDK 与插件。新环境成立后，旧 workspace 可先改名保留短期回滚窗口，再明确删除。
故障现场按产品、工作区和项目三层切
项目全红但 CLI 成功，先比较 JDK、Execution Environment、Wrapper、active profile、生成源码和 .settings，再 update/refresh project。直接删 workspace 会丢掉是哪一项分叉的证据。
Eclipse 启动卡住或崩溃，用 eclipse -consoleLog 收集启动错误，查看 workspace lock、磁盘、JVM crash log 与最近插件变更。只有证据指向 OSGi cache 时才临时使用 -clean。新 workspace 同样失败，就回到安装产品与 JVM；只有旧 workspace 失败，才继续缩小本机状态。
p2 更新失败时保留 update site、安装计划、证书链与 Error Log。插件命令消失则比较 installation profile，而不是重新导入项目。磁盘异常增长要分别看 workspace metadata、bundle pool、Maven/Gradle cache 与项目产物，它们的 owner 和清理代价不同。
卸载插件走 Installed Software，重启并复测；卸载独立 ZIP 产品前确认 workspace 与 Git 工作树位置；清理 workspace 前确认源码没有存放其中。所有删除都先保留可恢复路径，不能把 workspace 清理和 git clean 拼成一个脚本。
团队基线的边界
Eclipse 适合需要成熟 Java、插件平台、建模或存量 RCP 工具链的团队。它的架构优势是可组合，长期成本也来自可组合：p2 源、JDK、package、feature 与 workspace 都要有 owner。只维护少量轻型项目且没有 Eclipse 专属插件时，另一款 IDE 可能更省维护；这不是功能高低，而是工程对象数量的差异。
团队基线应登记安装渠道、支持的产品流、IDE JVM、项目 JDK、批准 update site、feature 清单、setup owner、升级窗口和回滚版本。插件以 IDE 进程权限读取源码、环境和网络，供应链审查不能省略。账号、代理密码、证书私钥与仓库凭证留在受控身份系统，不进 .settings、.launch、setup 或截图。
可以支持的最终状态很朴素：一台没有旧 workspace 的机器，从批准的 Eclipse 产品、仓库文件和受控 setup 出发，能够构建、运行、调试、停止并清理项目；产品退出后，仓库仍可用命令行构建。做到这里，“换 workspace”才回到它应有的位置——诊断手段，而不是团队知识的替代品。