JetBrains IDE 怎样按项目固定 SDK 版本

JetBrains IDE 要按项目使用指定 SDK，应在项目设置中选择明确的 SDK 条目，确认模块没有另外指向其他 SDK，并单独检查构建工具的运行环境。本文以 IntelliJ IDEA 的 Java/Gradle 项目为例：项目 SDK、模块 SDK 和 Gradle JVM 是不同层次，不要只改一个下拉框就认定所有构建环境都已锁定。

官方地址：https://www.jetbrains.com/help/idea/sdk.html

这里的“固定”首先指当前项目在 IDE 内选择明确环境，不是禁止日后修改，也不是把本机 JDK 自动分发给团队。其他 JetBrains 产品的解释器或工具链入口可能不同，不能直接套用 Java SDK 页面。

准备项目约定的 JDK 与现有构建文件

先取得项目约定的 JDK 版本要求，并准备已经安装且满足要求的 JDK。以下用教学名称 Team JDK 21 表示目标条目；21 只是本例约定，不是对所有项目的升级建议。操作前保存现有设置值，确认当前打开的是需要调整的项目，并保留构建文件原内容。

建议做一张映射备忘录：项目名称、目标 JDK 发行版与完整版本、本机 SDK 条目名、模块是否存在例外、Gradle 项目是否有自己的 JVM 约定。不要只记录一个容易随意重命名的条目名称，更不要把个人绝对路径作为所有成员通用的安装要求。

步骤1：把项目 SDK 映射到指定 JDK

入口：打开 File → Project Structure → Project Settings → Project。在 SDK 列表中选择已登记的目标 JDK。名称可能随版本略有变化，应核对条目对应的真实 JDK 信息，而不是只看“21”这个显示名。

动作：将当前项目选择为 Team JDK 21，应用更改。若列表里没有已安装 JDK，使用添加本地 JDK 的入口，指向 JDK 主目录；不要为了让名称一致去改写或删除其他项目共用的全局 SDK 条目。

继续前确认：重新查看项目页，SDK 仍是目标条目，没有未解析 SDK 提示。SDK 注册信息可以被多个项目共享，但每个项目的选择并不需要相同。改项目选择与改全局 SDK 本身不是同一动作。

步骤2：确认模块继承项目 SDK

入口：仍在 Project Structure 中进入 Project Settings → Modules，选择目标模块，打开 Dependencies。

动作：查看 Module SDK。若该模块没有经过确认的独立 JDK 要求，选择 Project SDK，使其继承项目选择。多模块项目逐个阅读现有值；有意设计的特殊模块先记录，不一键抹掉例外。

继续前确认：普通模块显示继承项目 SDK，例外模块则有明确记录。不要以项目页选对了为由跳过这里：模块可以单独指定 SDK。对于由 Gradle 导入管理的模块，后续导入可能重新生成模型，因此还需要处理构建工具一层，不能把手动页面值当成唯一配置来源。

步骤3：为导入与任务确认 Gradle JVM

入口：打开 IDE 的 Settings，进入 Build, Execution, Deployment → Build Tools → Gradle；某些版本的导航直接在该层级列出 Gradle。先选中正确的关联 Gradle 项目，再看 JVM 字段。

动作：对于显示 Gradle JVM 的项目，在该字段选择符合构建要求的 JDK，例如本例的 Team JDK 21，应用保存。若项目启用了 Gradle Daemon JVM criteria，页面会出现对应的版本与供应商条件，应遵守项目已有条件，不把它强改为旧式的选择方式。

继续前确认：页面选中的是目标 Gradle 项目，JVM 或 criteria 与项目约定一致。这里设置的是 IDE 导入和执行 Gradle 任务时所用的 JVM，不等同于 Java 编译目标或所有任务的工具链。JDK 还必须与项目使用的 Gradle 版本兼容；若不兼容，应根据团队约定处理，不能仅因下拉框能选中就判定可构建。

“打开既有项目时自动找到了哪个 JVM”与“现在明确选择什么”也应区分。JetBrains 文档列出了 org.gradle.java.home、JAVA_HOME 等自动解析来源；不要同时修改多处再猜谁生效。需要精确复现时，应把实际使用方式和项目构建约定一起记录。

保留配置记录，核对固定范围

应用后再次查看三处值，把结果与操作前备忘录对照。此时完成的是 IDE 配置选择，不代表项目测试已经通过。后续由读者在自己的受控环境执行原有导入或构建流程；出现错误时保留错误文本，再判断是 SDK 路径、Gradle 兼容性、依赖还是项目配置，避免先清空缓存或重装 IDE。

如果团队要求精确到补丁版本，需要记录发行版和完整版本，并通过团队已有的环境供应与构建配置落实；“主版本为 21”不是完整版本锁定。不要提交只适用于自己电脑的私有路径或把本机 SDK 目录打包到仓库。

修改项目 SDK 会更换 IDE 自己的运行环境吗？

不要把这两个目标混在一起。项目开发 SDK 与启动 IDE 所用运行时是不同用途，本教程不调整 IDE 运行时。

切到目标 SDK 后，命令行和 CI 就固定了吗？

不能据此推出。外部执行入口仍要遵循自身环境和项目构建规则，应该分别确认，而不是靠 IDE 下拉框作证。

重新导入后值变化怎么办？

先核对项目构建声明和导入所用 JVM 的来源，保留修改前后信息；不要不断在模块页面覆写一个由构建模型管理的值。

参考：IntelliJ IDEA SDK 配置、Gradle JVM 选择、Gradle 设置字段。