IntelliJ IDEA
绿色运行按钮为什么不能证明项目可构建
一个 Java 服务在开发者电脑上点击 Run 正常，换到干净检出后却连 ./gradlew test 都无法通过。排查发现，IDEA module 手工添加了一个本机 JAR，Run configuration 又选择了另一套 JDK；这些状态既不在 Gradle 模型里，也没有进入版本控制。绿色按钮证明的只是当前 IDE 项目模型能够组出一次进程，不代表仓库、CLI 和 CI 共享同一套事实。
IntelliJ IDEA 的价值在于把 project、module、SDK、依赖模型、项目分析和运行配置组织成可推理的工程模型。导入正确时，导航、重构、构建和调试互相印证；导入错误时，代码仍能打开，却会出现依赖全红、语言级别错误、运行配置漂移和 IDE / CLI 结果不一致。WebStorm、PyCharm、GoLand、Rider 和 CLion 应按 JetBrains IDE 家族选型 重新评估项目模型与许可；共享运行配置和 JDWP 的复杂边界可继续阅读 任务、运行与调试配置。
下面从干净 Java 程序建立 CLI 事实源，再观察 IDEA 如何导入 SDK、module、索引和运行配置。完成这条链路后，Maven / Gradle reload、Safe Mode、插件、订阅和企业下发就不再是零散菜单，而是分别改变模型来源、代码执行边界和组织成本的工程选择。
先确认 JDK 与开发机容量
开发机需要满足 IntelliJ IDEA 安装要求，并为 IDE、插件、JDK、依赖缓存和项目分析数据预留磁盘。最小 Java 实验使用 JDK 17 或更高版本；真实项目仍以仓库声明的 toolchain、Maven Wrapper 或 Gradle Wrapper 为准。
先在系统终端检查：
java -version
javac -version两条命令都应成功，且主版本与项目要求一致。只有 java 没有 javac，通常意味着拿到的是运行时而不是完整 JDK。再用 java -XshowSettings:properties -version 核对 java.home 与架构；后续 IDEA 中的 Project SDK 和 Build Tool JVM 应能解释为团队允许的 JDK，而不是碰巧从个人目录中找到的另一套安装。
选择安装与更新模型
Toolbox App：团队开发机的默认入口
JetBrains 安装文档 推荐 Toolbox App 管理 IntelliJ IDEA。它适合维护多个 IDE、同一 IDE 的多个版本、Release / EAP 通道、更新与回滚；登录 JetBrains Account 后，还能为已安装实例领取可用许可证。
从 JetBrains 官方页面下载与 CPU 架构匹配的 Toolbox 安装包，安装后在 Toolbox 中选择 IntelliJ IDEA。生产开发基线选择 Release；EAP 只用于兼容验证和缺陷复现。安装完成后从 Toolbox 的实例设置查看实际安装目录，不要根据旧版 IntelliJ IDEA Ultimate 路径硬编码脚本。
验证产品信息：
Help | About
Help | Manage SubscriptionsAbout 应显示产品版本、构建号、运行 IDE 的 JetBrains Runtime 和操作系统。Manage Subscriptions 应显示当前处于免费功能集、试用还是 Ultimate 订阅。不要用界面中是否出现某个菜单反推整个组织的许可证状态。
Standalone：需要显式实例控制时使用
Standalone 安装适合离线镜像、受控软件分发或不允许 Toolbox 常驻的环境。更新文档 说明，实例默认自行检查更新；有 patch 时覆盖当前安装，没有 patch 时可能要求下载新版本或作为独立实例安装。Release、Beta / Preview 与 EAP 是不同风险通道，生产基线不应跟随 EAP。
团队采用 Standalone 时必须额外解决安装包校验、版本发现、设置迁移、旧实例保留和回退。离线环境无法访问更新服务，应由软件分发平台提供经验证的安装包，不能让成员从未知镜像下载。
Snap：自动更新不是零治理
Linux Snap 使用 classic confinement，意味着 IDE 需要类似传统安装的广泛系统访问。Snap 会随系统后台自动刷新，官方文档同时列出若干性能和调试问题，并建议遇到问题时考虑 Toolbox App。
若团队仍选择 Snap，要记录 channel、刷新窗口和 hold 策略：
snap info intellij-idea
sudo snap list intellij-idea
sudo snap refresh --hold intellij-idea执行前先确认组织是否允许 sudo 改变刷新策略。snap info 应展示可用 channel，snap list 应展示当前安装版本；若命令或输出与资产清单不一致，停止更新并核对包名与软件源。hold 只应作为短期升级窗口控制，不是永久冻结安全更新的方法。
理解 2025.3 版本后的产品与订阅
JetBrains 的 单一发行版说明 明确，从 2025.3 版本起不再让新成员在 Community 与 Ultimate 两个安装包之间选择。所有人安装 IntelliJ IDEA；未激活订阅时使用当前免费功能集，激活 Ultimate 订阅后解锁高级功能。原 Community 用户通过正常更新进入单一发行版，原 Ultimate 用户看到的产品名去掉 Ultimate 后缀。
注册与订阅文档 说明，试用或订阅结束后 IDE 会回落到免费功能集，而不是禁止打开项目。连续年度订阅的 perpetual fallback license 仍用于符合 fallback 日期的旧版本；它不是“永远使用最新 Ultimate”。架构上应同时准备两条连续性路径：最新版本的免费功能集，以及许可证允许的旧版 Ultimate。旧版本也必须接受安全和兼容风险评估。
个人可通过 JetBrains Account 或激活码；组织应优先评估 License Vault。JetBrains 的 Floating License Server 退出公告 已结束旧 FLS 服务，不能因为 IDE 激活对话框或环境变量仍出现“license server”字样，就把它理解为旧 FLS 仍受支持。安装包、免费功能集、Ultimate 订阅、第三方插件和 IDE Services 始终是不同治理对象。
分清 IDE Runtime 与项目 JDK
IntelliJ IDEA 自带 JetBrains Runtime，用来运行 IDE 本身。它不会自动成为项目编译所需 JDK，也不应为了修项目编译问题随意更换 IDE Runtime。
项目至少可能同时出现四个 Java 版本入口：
IDE Runtime -> 启动 IntelliJ IDEA
Project SDK -> 项目的默认 SDK
Module SDK -> module 可继承或覆盖 Project SDK
Build Tool JVM -> 运行 Maven / Gradle 导入与任务
Java toolchain -> 构建脚本声明的编译 / 测试工具链按照 SDK 配置文档，进入 File | Project Structure | Platform Settings | SDKs 添加本机 JDK，或使用 Download JDK 选择供应商、版本和安装位置。再到 Project Settings | Project 设置 Project SDK，让普通 module 继承它。真实 Gradle / Maven 项目还要检查各自 Settings 中的 Gradle JVM 或 Maven runner/importer JDK。
团队不要只写“统一 JDK 17”。还应明确供应商、架构、更新策略、toolchain 声明和 IDE 导入 JVM。官方文档提醒 Oracle Java 许可可能带来合规要求；没有特定供应商约束时可采用经过组织批准的 OpenJDK 构建，但最终选择应由安全与法务基线决定。
用最小 Java 工程验证基础链路
创建目录：
idea-project-lab/
src/
Main.javasrc/Main.java 内容：
public class Main {
public static void main(String[] args) {
String message = "idea-model-ok";
System.out.println(message);
}
}先用 CLI 证明 JDK 与源码无关地成立：
javac -d out src/Main.java
java -cp out Main预期输出：
idea-model-ok如果 javac 失败，先修 JDK 或源码，不要让 IDE 自动下载依赖、改语言级别或生成项目文件来隐藏问题。
在 Welcome Screen 选择 Open，打开 idea-project-lab。对于这个无构建工具的简单源码目录，可以通过 File | Project Structure 设置 Project SDK，并把 src 标记为 Sources Root。此时 IDEA 才能把文件从“普通文本目录”提升为可编译 module 内容。
项目模型如何形成
IntelliJ IDEA 中，project 是顶层工作范围，包含一个或多个 module；module 拥有 content root、source / test / resource root、SDK 与依赖。library 是 module 依赖的一种，SDK 则提供平台类库和开发工具。
对于 Maven 或 Gradle 仓库，pom.xml、settings.gradle(.kts)、build.gradle(.kts) 才是权威模型。打开项目时选择对应构建工具配置，IDE 会执行导入、解析依赖并创建 module。手工在 Project Structure 中添加依赖只能改变 IDE 模型，下一次 reload 可能被构建模型覆盖，也无法让 CI 获得该依赖。
项目导入不是只读扫描。Gradle、Maven、sbt 构建脚本和插件可以执行代码、访问网络和读取环境。陌生仓库必须先进入 Safe Mode 审查，不能为了让依赖“快点下载”立即点击 Trust Project。
在 Safe Mode 中审查陌生项目
第一次打开未知来源项目，按照 项目安全文档 选择 Preview in Safe Mode。此时可以浏览文件，但 Maven / Gradle / sbt 导入、依赖解析、启动任务、VCS、GDSL 和 File Watcher 会受限。
优先审查：
pom.xml、settings.xml 引用和 Maven Wrapper
settings.gradle(.kts)、build.gradle(.kts)、Gradle Wrapper
构建插件、init script、included build
.idea、*.iml、.run 中的可执行路径和环境变量
启动脚本、File Watcher、外部工具
插件建议与项目级配置确认来源、提交、wrapper 分发地址、插件仓库和脚本后，再信任准确项目目录。不要把整个用户主目录设为 Trusted Location；这会让下载、临时 clone 和未知仓库绕过询问。官方还说明 headless 命令行启动默认以 trusted mode 打开项目，因此自动化环境必须通过容器、最小权限账号和网络隔离补足边界。
完成最小运行与调试
在 Main.main 左侧点击运行图标，选择 Run。IDEA 会创建临时 Application run configuration。预期 Run 窗口输出 idea-model-ok 并以退出码 0 结束。
然后在赋值行设置断点，点击 Debug。预期程序停在断点，Variables 中 message 为 idea-model-ok；继续后输出文本并退出。若需要长期共享参数，打开 Run | Edit Configurations，把临时配置保存为永久配置并命名为 Main - local verification。
Run configuration 是“执行什么、用哪个 module/JDK、在哪个工作目录、传哪些参数和环境变量、启动前做什么”的合同。临时配置适合一次性运行，永久配置适合稳定入口。团队共享时应使用项目相对路径和占位环境变量，禁止提交个人目录与真实密码。
最小验证应同时保留 CLI 与 IDE 两条证据：CLI 证明源码和 JDK 可工作，IDE 证明项目模型、SDK、编译器和调试器接线正确。只有 IDE 能运行而 CLI 失败，通常意味着项目依赖了个人 IDE 状态。
索引是派生状态，不是项目事实源
IDEA 在项目导入后分析源码、依赖和 SDK，以支持导航、引用查找、重构和检查。官方 Project analysis 说明，旧版本称这一阶段为 indexing；因此排障日志中的“索引”和新界面中的“项目分析”指向同一类派生状态。分析结果来自项目模型；当 JDK、依赖或 source root 错误时，重建同一个错误模型不会解决根因。
判断索引健康可以做三个小测试：跳转到 String 定义、查找 Main 用法、修改类名并查看重构预览。若 SDK 类也无法解析，先检查 Project SDK；若只有依赖类全红，先检查构建工具 reload 和依赖解析；若 CLI 与构建模型正确但单文件导航异常，再使用 File | Cache Recovery | Repair IDE 对当前项目逐步修复。
Invalidate Caches 是后置措施。先按 Repair IDE 对当前项目逐步修复；Invalidate Caches 会清理当前 IDE 版本处理过的所有项目缓存，重启后全部重建，可选项还可能清理 Local History、VCS Log 或 JCEF 数据。点击前要看清选项，并记录问题是否能在 Repair IDE 某一步恢复，否则“清缓存后暂时正常”没有诊断价值。
接入 Maven 与 Gradle 真实项目
真实项目先从干净 clone 在终端运行 wrapper：
./mvnw -version
./mvnw test
./gradlew --version
./gradlew testWindows 对应 mvnw.cmd 和 gradlew.bat。只运行项目实际使用的一组命令。预期版本信息中的 Java 与团队 toolchain 相符，测试成功；若 CLI 已失败，先保留构建日志，IDE 导入不能作为修复替代。
在 IDEA 中打开仓库根并选择 Maven 或 Gradle 模型。导入完成后核对：module 数量与构建子模块一致，source/test roots 正确，外部依赖已解析，Gradle JVM 或 Maven importer 使用允许的 JDK，生成目录没有被误当源码。
然后从 Maven / Gradle 工具窗口运行与 CLI 等价的 test 任务。IDE 原生 Build 与构建工具任务可能走不同编译链；团队必须明确日常快捷构建、发布构建和 CI 的权威入口。发布制品永远以仓库构建合同为准，而不是“IDE Build 成功”。
设置同步与项目配置的边界
当前 IDEA 使用 bundled 的 Backup and Sync plugin，通过 JetBrains Account 同步主题、键位、代码样式、插件状态和部分系统设置。旧 Settings Repository plugin 已弃用且不再内置，不应为新团队建立基于它的流程。
启用前进入 Settings | Backup and Sync 选择类别，并决定只在 IntelliJ IDEA 间同步还是跨 JetBrains IDE 同步。首次合并要判断本机设置还是账号设置为权威。同步范围包含 Server Certificates、数据库工具、调试器等类别时，可能涉及内部地址、证书和账号痕迹，受限团队应缩小类别。
Backup and Sync 是个人连续性工具。项目 code style、inspection profile、共享 run configuration 和字典等团队配置，应通过受审查的项目文件或 IDE Provisioner 下发。个人账号同步不能提供强制、审批、版本评审和离职回收。
清理、卸载与回滚
最小实验先删除编译产物 out/，再从 Welcome Screen 移除 recent project 记录；删除项目目录前确认没有未提交源码。IDE 自动创建的 .idea 与 *.iml 是否保留，要按团队版本控制策略处理，不能一刀切全部提交或全部忽略。
Toolbox 安装通过对应实例菜单卸载，并可保留已验证的前一版本用于回滚。Standalone 通过操作系统卸载或删除应用目录；Snap 使用原包管理器。JetBrains 官方 卸载文档 指出配置、system、plugins 和 logs 目录默认可能保留，完整重置必须另行删除；这会影响所有项目、Local History 和诊断证据，操作前需备份。
升级故障优先切回 Toolbox 中保留的旧实例，并用同一个干净 clone、同一 JDK 和同一 wrapper 复验。不要让新旧 IDE 同时写同一个项目的不可兼容配置。插件升级故障先禁用插件并用 Safe Mode / 默认配置复现，插件治理转交独立专题。
订阅回滚与版本回滚不同：订阅到期后可继续用最新版本免费功能集；perpetual fallback license 允许的旧版 Ultimate 由 fallback 日期决定。团队应事先验证关键项目在免费功能集和批准旧版中的最低可维护路径。
常用提效路径
IDEA 的高价值提效来自项目模型：双击 Shift 的 Search Everywhere 查动作、文件和符号；Navigate 与 Find Usages 基于索引理解引用；重构先给预览，再由构建与测试验证；Maven / Gradle 工具窗口用于观察模型和运行权威任务。
减少索引成本应从项目边界入手：不要把 monorepo 之外的大目录加入 content root；正确标记 generated、excluded、test 和 resource 目录；避免让构建输出反复进入索引。大型团队可评估 Shared Indexes，但索引与 IDE 版本兼容，生成、发布和访问控制本身会带来维护成本，不能把它当通用加速开关。
建立固定烟雾测试：CLI test、IDE reload、核心类跳转、一次重构预览、一次 Run、一次断点。升级 IDE、JDK、wrapper 或核心插件后都跑同一组测试，才能知道变化发生在哪一层。
从现象回到原因
IDE 能启动，但项目没有 JDK
Project SDK is not defined，Java 类和 java.lang 全红。 对比 Help | About 的 Runtime 与 Project Structure 的 SDK；运行 javac -version。 把 bundled JetBrains Runtime 当成项目 JDK，或项目 SDK 指向已删除目录。 添加经批准的独立 JDK，设置 Project SDK，并让 module 继承。 CLI 编译成功，IDE 可跳转到 String，Run 输出 idea-model-ok。
Maven / Gradle 项目导入后依赖全红
源码可见但外部依赖无法解析，工具窗口显示同步失败。 先运行 wrapper，再查看导入日志、构建工具 JVM、代理和证书。 CLI 本身失败、IDE 使用另一 JDK、私服不可达、Safe Mode 禁止导入，或错误地按普通源码项目打开。 恢复 CLI 成功，选择正确构建模型和 JVM，再 reload。 module 与依赖树一致，IDE 与 wrapper 执行相同测试均成功。
项目打开后一直分析或磁盘暴涨
索引长时间运行，CPU / 磁盘高，system 目录持续增长。 检查 content root、生成目录、构建输出、日志和当前索引阶段。 打开了仓库父目录、生成文件反复变化、插件扫描额外目录，或短期项目缓存累积。 修正项目模型与 excluded roots，停止产生循环输出；必要时先 Repair IDE。 重新导入后索引能收敛，导航和测试正常，磁盘不再持续增长。
Invalidate Caches 后短暂恢复又复发
清缓存后代码不红，下一次同步又失败。 比较同步前后的 SDK、module、依赖和 source root。 错误来自构建模型或插件，缓存只是派生结果。 修正 pom.xml / Gradle 配置、JDK 或插件，再从干净模型 reload。 不清缓存也能连续重启、reload 和运行测试。
Run 成功，CLI 失败
绿色运行图标可启动，wrapper 或 java 命令失败。 查看 run configuration 的 module、JDK、classpath、工作目录、环境变量和 Before launch。 IDE 注入了个人依赖、使用另一 JDK，或原生 builder 与权威构建链不同。 让配置调用仓库合同，移除个人绝对路径和隐式环境。 干净 clone 在 CLI、IDE 和 CI 使用同一版本与测试入口。
Safe Mode 中“什么都不能用”
构建工具不导入、VCS 消失、运行配置不可用。 查看项目是否仍处于 Safe Mode。 这是官方设计的预览限制，不是索引损坏。 审查构建脚本和项目配置；来源可信后再 Trust Project。 导入、VCS、Run 恢复，同时 Trusted Locations 没有扩大到宽泛父目录。
Ultimate 功能突然不可用
项目仍能打开，但部分框架或高级工具消失。 打开 Manage Subscriptions，核对账号、许可来源、到期时间和 License Vault 分配。 试用或订阅到期、账号切换、组织许可池耗尽，或统一发行版升级后未自动领取 Ultimate。 按授权流程重新激活；无许可时使用免费功能集，不要下载旧 Community 安装包。 订阅状态和所需功能恢复，组织后台能对应到正确用户和设备。
架构选型与边界
IntelliJ IDEA 适合 JVM 项目模型复杂、重构和静态分析深度要求高、希望减少插件拼装的团队。其代价是更重的索引与缓存、更复杂的 JDK / 构建模型关系，以及 Ultimate 订阅和企业治理成本。
轻量多语言编辑、按需组合工具和简单文件夹工作区可选择 VS Code；其他 JetBrains 语言 IDE 应按项目模型和许可差异单独评估；Visual Studio 面向其原生工作负载。不要以“大家习惯哪个”结束选型，至少比较构建事实源一致性、调试深度、索引成本、插件边界、远程模式、许可连续性和企业下发能力。
IDE 原生 builder 可以提高本地反馈速度，但 Maven / Gradle 项目的发布事实源仍是构建脚本与 wrapper。IDE 项目模型是构建模型在开发机上的投影，不是第二套可随意修改的真相。
权限、账号与敏感信息
Toolbox 与 IDEA 登录 JetBrains Account 后可获取许可证和同步设置。个人账号、组织账号、激活码和 License Vault 分配应有明确边界；禁止共用账号，也不要把激活码、授权 token 或 IDE Services URL 写入仓库和截图。
Backup and Sync 可能同步插件、Server Certificates、数据库工具、调试器和系统设置。导出设置 ZIP、诊断包、日志、.idea、.run 与 run configuration 可能包含用户名、绝对路径、内网地址、代理、证书和环境变量。提交或发送前必须扫描脱敏。
JetBrains 插件与 IDE 在同一权限边界运行，能读取项目、访问网络和启动进程。Required Plugins 只能表达项目需要哪些插件，不是审批或沙箱。需要组织级插件允许、版本分发、设置和 VM Options 下发时，应使用 IDE Services / IDE Provisioner 等受控能力，并在独立插件治理文章中设计准入与回滚。
构建导入会执行仓库代码并访问依赖源。Fork、外部贡献和未知仓库不应获得发布凭证、生产网络或高权限私服 token。Safe Mode 之后仍需要最小权限账号、隔离缓存和受控网络。
团队治理
团队基线至少记录：允许的 IDEA Release 版本、Toolbox / Standalone / Snap 渠道、Ultimate 所需角色、License Vault 规则、批准的 JDK 供应商与版本、wrapper 校验、项目模型 owner、共享 run configuration 规则、插件准入和升级回退窗口。
2025.3 版本迁移时应清理“装 Community 还是 Ultimate”的旧文档和部署规则。IDE Services 统一发行版迁移说明 指出，原先只针对 Community 或 Ultimate 的规则在统一发行版上可能有不同继承结果；免费功能组与付费功能组应通过用户、组和 profile 重新验证，不能仅靠旧产品名匹配。
组织升级采用代表性项目矩阵：至少包含单 module、多 module、Maven、Gradle、注解处理或代码生成项目。每次升级验证 CLI、导入、索引、重构、测试、Run / Debug、插件和许可领取；记录构建号、JDK、wrapper、插件版本与结果。
故障处置遵循从事实源到派生状态的顺序：先 CLI，再 JDK，再构建模型，再 IDEA project/module，再索引，最后插件与缓存。这样可以把“清缓存碰巧好了”变成可复现的工程判断，也让 IDEA 真正成为团队项目模型的高效投影，而不是每个人机器上无法解释的第二套构建系统。
团队自检
检查应在干净检出和代表性项目上执行。只看 IDE 能启动或代码不再飘红，无法证明项目模型、许可与构建合同一致。
IntelliJ IDEA 的安装渠道、Release / EAP 通道、构建号和回退实例可追溯。免费功能集与 Ultimate 角色已经按真实项目验证，License Vault 分配和离职回收有责任人。IDE Runtime、Project SDK、Module SDK、Build Tool JVM 与 Java toolchain 能分别解释，没有依赖个人目录中的偶然 JDK。
Maven 或 Gradle wrapper 在 CLI 先通过，IDE reload 后的 module、source root、依赖和生成目录与构建模型一致。最小 Run / Debug 能命中断点，但发布与 CI 仍调用仓库构建合同。陌生项目先在 Safe Mode 审查 wrapper、构建插件、启动任务、File Watcher 和共享运行配置。
项目分析异常先修 SDK 与模型，再用 Repair IDE；清缓存不是默认排障步骤。插件、设置同步、诊断包和共享 .idea / .run 文件已检查许可、网络、绝对路径与敏感信息。IDE、JDK、wrapper 或核心插件升级后，代表性项目矩阵完成 CLI、导入、分析、重构、测试和调试烟雾测试。