S01-B01 · 开发环境全景：JDK、Maven、IDE、终端各自管什么

适用读者：第一次在电脑上配置 Java 开发环境的人；被"装了三样东西但不知道各自干嘛"困扰过的人。
前置：无。本篇是全站第一篇。
实测环境：Ubuntu 24.04.1 LTS / OpenJDK 21.0.12.1（Ubuntu 构建）/ Apache Maven 3.8.7 / Git 2.43.0。
版本基线：IDEA 2025.x（Ultimate 与 Community 差异见 §4）；JDK 首选 Temurin 17 或 21 LTS。
覆盖旧文：A-1347、A-1348、A-1349、A-1351、A-1352、A-1396、A-1397（共 640 个原文点位）。
下一篇：S01-B02 · JDK 安装与多版本共存。

1. 一句话结论

JDK 负责"能运行"，Maven 负责"能组装"，IDE 负责"能高效地写和调"，终端负责"能在没有图形界面时完成同样的事"。

这四样东西不是可选项的堆叠，而是四层职责。任何一层缺了或错位，症状都不一样——先认清职责，后面的排障才有方向。

┌─────────────────────────────────────────────────────┐
│  你写的代码 (.java)                                  │
└───────────────┬─────────────────────────────────────┘
                │  ① 谁来编译、谁来执行？
        ┌───────▼────────┐
        │      JDK       │  javac 编译 → java 运行（JVM）
        │  (含 JRE + 工具)│  ★ 决定"能不能跑"
        └───────┬────────┘
                │  ② 谁来拉依赖、打包成 jar/war？
        ┌───────▼────────┐
        │     Maven      │  pom.xml → 下载依赖 → 编译 → 打包
        │  (构建工具)     │  ★ 决定"能不能组装成产物"
        └───────┬────────┘
                │  ③ 谁来给你导航、补全、调试、重构？
        ┌───────▼────────┐
        │      IDE       │  只是个"更聪明的编辑器 + 调度器"
        │ (编辑器+前端)   │  ★ 决定"写得快不快、查得准不准"
        └───────┬────────┘
                │  ④ 谁来在服务器/容器里做同样的事？
        ┌───────▼────────┐
        │     终端        │  ssh、git、mvn、java -jar
        │  (Shell 环境)   │  ★ 决定"离了图形界面还能不能干活"
        └────────────────┘

职责分工表

层	一句话职责	装错了的典型症状	怎么验证装对了
JDK	把 `.java` 编译成字节码，用 JVM 跑起来	`javac: command not found`；`UnsupportedClassVersionError`（版本不匹配）	`java -version`、`javac -version` 两行都出得来，且版本号一致
Maven	按 `pom.xml` 拉依赖、编译、打包	`Could not resolve dependencies`、`mvn: command not found`	`mvn -v` 里能看到 Maven 版本和 Java 版本
IDE	代码导航、补全、重构、运行与调试的前端	项目红了但命令行能编译（IDE 没同步 Maven）	项目窗口右下角索引跑完，`Project SDK` 与命令行 JDK 一致
终端	在无 GUI 环境完成同样操作；所有排障的入口	在服务器上不会操作，只能依赖图形工具	`ssh` 能连、`git` 能用、`mvn` 能跑

2. 为什么要 IDE：它不是"高级记事本"

旧文里花了很大篇幅论证"为什么选 IDEA"，摘掉广告腔之后，真正有说服力的只有四点——这四点恰好对应日常最耗时的四类动作：

项目模型的理解：你给出项目类型、Java 版本、构建工具，IDE 负责把源码目录、依赖、编译输出、运行配置全部配好。不用手工摆 src/main/java、不用手写 classpath。
导航与搜索：双击 Shift 的 Search Everywhere 能同时搜文件、类、符号、动作、设置甚至 Git 历史；Ctrl+Shift+F 全项目文本搜索；Alt+F7 查一个方法被谁调用。这是 IDE 相对文本编辑器最大的效率差——改代码前先看"谁在用我"。
运行与调试一体：断点、变量观察、单步、求值都在同一个窗口，不需要 System.out.println 满天飞（调试的深水区在 S01-J04）。
重构是语义级的：改名、提取方法、移动类会连带改掉所有引用；文本编辑器的"替换全部"做不到这件事。

别被功能列表唬住。旧文照搬了官方一大堆功能名（结构化搜索、Run Targets、框架特定导航……），初学者一个都用不上。第一周你只需要：建项目、写代码、运行、看一眼报错。其余功能等遇到问题再学，这也是本系列 B04–B06 的编排理由。

IDE 不是必需品，但它是这个时代的默认值

Eclipse / MyEclipse 曾经是主流，现在企业与高校基本以 IntelliJ IDEA 为主。若你有明确偏好（比如团队统一用 VS Code，或你只写单文件脚本），VS Code + Extension Pack for Java 也能完整走完本系列的命令行部分，只是调试与重构体验弱一档。替代路径的具体差异见 §8。

3. 装之前先定三件事

装环境最常见的返工不是装错，而是没先定版本。三件事定下来，后面几乎不会返工：

决策	建议	理由
用哪个 JDK 大版本	17 或 21（都是 LTS），团队项目跟随项目 `pom.xml` 的 `maven.compiler.release`	非 LTS 版本半年就停更；跨大版本会出现 `UnsupportedClassVersionError`
用哪个发行版	Temurin（Adoptium）、Amazon Corretto、Microsoft Build of OpenJDK 任选；生产环境不建议用 Oracle JDK 做默认（授权条款不同）	各发行版字节码兼容，差异在许可、更新节奏与随附组件
装几个版本	至少准备两个（例如 17 和 21）	老项目锁 17、新项目用 21 是常态，切版本的能力比"装最新版"重要得多（B02 专门讲）

不要一上手就装最新非 LTS。你不是在追新，你是在给自己搭一个能稳定用两年的工作台。

4. 版本与授权：Ultimate 还是 Community

能力	Community（免费）	Ultimate（付费/教育授权）
Java / Kotlin / Groovy 基础开发	✅	✅
Maven / Gradle 项目	✅	✅
数据库工具（Database 面板）	❌	✅
Spring / Spring Boot 支持（Bean 导航、配置校验）	❌	✅
HTTP Client、Profiler、远程开发	❌	✅
JavaScript / TypeScript 前端支持	部分	✅

判据很简单：

只学 Java 语法、写课设、刷算法 → Community 足够。本系列 B02–B11 的所有操作在 Community 上都能完成。
要写 Spring Boot 后端（本博客主线就是这个） → Ultimate 的 Spring 支持能省下大量时间；学生可用教育邮箱申请免费授权，开源项目亦可申请。
企业内使用 → 按公司采购；不要用来源不明的"激活方式"，许可风险由使用者和公司承担。

旧文勘误：原文 A-1349 曾推荐"固定使用某老版本 + 重置试用期"的做法来规避授权。本系列不采用，也不提供相关步骤。理由不是道德说教，而是工程现实：这类版本无法获得安全更新，插件市场兼容性逐年下降，且在商业环境中属于明确的许可违约。你需要的是"能稳定用两年的环境"，不是"能永久白嫖的版本"。

5. 三平台安装：Windows / macOS / Linux

5.1 Windows（安装向导式）

下载页：https://www.jetbrains.com/idea/download/，选 Windows，.exe。历史版本在 .../download/other.html。
双击 .exe → Next。
安装路径：默认在 C:\Program Files\JetBrains\...。建议改到无空格、无中文的路径（如 D:\tools\JetBrains），可省掉一类路径解析问题。
勾选项按需：
- Create Desktop Shortcut：创建桌面快捷方式（建议勾）
- Add "bin" folder to the PATH：建议勾——之后可在终端用 idea . 从当前目录打开项目
- .java 文件关联：按需
Install → 等待 → 勾 Run IntelliJ IDEA → Finish。

5.2 macOS

按芯片选包：Apple Silicon 选 aarch64，Intel 选 x64。选错的表现是启动后明显卡顿（Rosetta 转译）。
打开 .dmg，把 IntelliJ IDEA.app 拖进 Applications。
首次启动若提示"来自互联网的应用"，在系统设置 → 隐私与安全性里允许。
建议在 IDEA 内执行 Tools → Create Command-line Launcher，之后终端可 idea . 打开当前目录。

5.3 Linux（推荐用包管理器或 tar.gz）

# 方式一：官方 tar.gz（最通用，可控安装路径）
sudo tar -xzf idea-2025.*.tar.gz -C /opt
sudo ln -s /opt/idea-IU-*/bin/idea.sh /usr/local/bin/idea

# 方式二：Snap（省事，但沙箱路径偶有权限坑）
sudo snap install intellij-idea-community --classic

验证：

idea --version    # 预期输出形如：IntelliJ IDEA 2025.1

注意：Linux 上的 idea.sh 依赖 JDK 启动，若系统无 JDK 会报 No JDK found。这不是 IDE 装坏了，是 §6 的问题。

6. 首次启动：欢迎界面的四个入口

启动后是欢迎界面（Welcome screen）。不同版本外观略有差异，但四个入口固定：

入口	用途	什么时候用
Projects	最近打开过的项目列表	日常续做
New Project	新建项目向导	第一次建项目、临时写 demo
Open	打开磁盘上已有目录	已经 clone 下来的仓库、别人的示例
Get from VCS	从版本控制拉取（Git/GitHub/GitLab…）	接手公司项目、参与开源（见 B10 / B11）

首次启动还会问一句 "是否导入旧设置"：

第一次装 → 选 Do not import settings。
换电脑/重装 → 选导入 settings.zip（B09 讲怎么导出）。

别急着改主题和字体。第一周先把项目跑起来；外观设置集中在 B04，插件在 B06。上来就折腾主题的人，通常卡在"找不到菜单在哪"。

7. 第一个项目：从新建到看见输出

7.1 新建

File → New → Project（首次也可直接点 New Project）。向导里要定六个参数：

参数	填什么	说明
Name	`HelloWorld`	项目名，同时是目录名
Location	`~/projects`（不要选桌面，不要含中文）	路径含中文/空格在某些工具链上会出问题
Language	Java	—
Build system	Maven	本系列统一 Maven；IntelliJ 原生构建不利于协作
JDK	选已装的 17 或 21	下拉里没有 → 见 §7.4
Add sample code	勾上	自动生成 `Main.java`

7.2 生成的代码

public class Main {
    public static void main(String[] args) {
        System.out.println("Hello and welcome!");
    }
}

点编辑器左侧行号旁的绿色 ▶，或 Shift+F10（macOS ⌃R）。

预期输出（Run 工具窗口）：

Hello and welcome!

Process finished with exit code 0

exit code 0 是关键：非 0 表示程序异常退出，先看异常栈，别急着怀疑环境。

7.3 索引：第一次慢是正常的

窗口右下角会出现 Indexing...。IDE 正在为项目建索引（相当于给代码建"目录"），首次较慢，之后基本秒开。索引没跑完就去搜索，搜不到是正常现象，不是装错了。

7.4 下拉里没有 JDK 怎么办

说明 IDEA 没找到 JDK。两条路：

已经有 JDK：Add SDK → JDK，指向安装目录（Linux 通常在 /usr/lib/jvm/java-21-openjdk-amd64，macOS 在 /Library/Java/JavaVirtualMachines/...）。
没有 JDK：先装（B02 完整讲），再回来选。不要用 IDE 内置下载器装"随手一个版本"——它会和你命令行的 JDK 脱钩，制造出"IDE 能跑、终端不能跑"的经典问题。

8. 对照实验：不用 IDE 也能跑

这是本篇最重要的一节。理解 IDE 在背后做了什么，才能在被它坑的时候自救。

8.1 命令行编译与运行（Ubuntu 24.04.1 实测）

mkdir -p /tmp/s01demo && cd /tmp/s01demo
cat > Hello.java <<'EOF'
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, S01-B01");
    }
}
EOF

javac Hello.java     # 编译，无输出即成功
java Hello           # 运行（注意：不带 .class 后缀）

实测输出：

$ java -version
openjdk version "21.0.12.1" 2026-08-18
OpenJDK Runtime Environment (build 21.0.12.1+1-1-24.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 21.0.12.1+1-1-24.04.4-Ubuntu, mixed mode, sharing)

$ javac Hello.java && java Hello
Hello, S01-B01

$ which java javac
/usr/bin/java
/usr/bin/javac

8.2 一个容易被忽略的事实：`JAVA_HOME` 可能根本没设

同一台机器上：

$ echo "JAVA_HOME=[${JAVA_HOME:-<未设置>}]"
JAVA_HOME=[<未设置>]

$ readlink -f $(which java)
/usr/lib/jvm/java-21-openjdk-amd64/bin/java

java 能跑，但 JAVA_HOME 是空的。 因为 java 只是 /usr/bin/java 这个符号链接到一个具体 JDK。很多工具（Maven、Gradle、Tomcat、部分 IDE 启动脚本）读的却是 JAVA_HOME，于是出现：

命令行 java -version 是 21，
mvn -v 里却是 17（甚至报找不到 JDK）。

这不是玄学，是两个不同的查找机制。B02 会把 PATH、JAVA_HOME、update-alternatives/sdkman 的关系一次讲透。

8.3 IDE 到底帮你做了什么

IDE 的点击	背后的等价命令/动作
New Project（Maven）	生成 `pom.xml` 与 `src/main/java`、`src/test/java` 目录骨架
项目工具栏里的刷新	读 `pom.xml`，解析依赖，下载到本地仓库 `~/.m2/repository`
绿色 ▶	编译（等价 `javac`/`mvn compile`）→ 用配置的 JDK 启动 JVM → 把 stdout 显示到 Run 窗口
Indexing	扫描源码建符号索引（IDE 私有数据，存在 `.idea/` 与 IDE 系统目录）
项目变红但能编译	IDE 模型与 Maven 模型不同步 → `Maven 面板 → Reload All Maven Projects`

判断法：任何"IDE 说错但命令行说对"（或相反）的情况，都先怀疑模型不同步，而不是代码错了。

9. 自检：五条命令 + 一个动作

装完按顺序执行，全部符合预期才算真的装好。

#	检查	命令/动作	预期	不符合时的含义
1	JDK 可执行	`java -version`	打印 `openjdk version "17…"` 或 `"21…"`	没装或 `PATH` 不含 JDK/bin
2	编译器存在	`javac -version`	版本号与 ① 一致	只装了 JRE（无编译器）
3	构建工具链到 Java	`mvn -v`	前三行：Maven 版本、`Maven home`、`Java version: 与 ① 一致`	`JAVA_HOME` 指向别的 JDK
4	IDE 与命令行一致	IDEA 的 `Project Structure → Project SDK`	与 ① 同一版本	IDE 用了自带 JDK
5	能跑	运行 `Main`	`Hello and welcome!` + `exit code 0`	看 Run 窗口异常栈
6	能脱离 IDE	§8.1 的 `javac` + `java`	输出 `Hello, S01-B01`	`PATH`/`JAVA_HOME` 未配

第 3 条是最容易翻车的一条。mvn -v 里的 Java version 才是 Maven 真正用的 JDK；它和 java -version 不一致时，后续会出现"命令行编译通过、mvn package 报 UnsupportedClassVersionError"的诡异现象。

10. 五个常见误区

误区	真相	怎么避
"IDE 自带 JDK，所以不用装"	IDE 内置的只是"能启动 IDE 的运行时"，版本固定，且和命令行完全脱钩	自己装 JDK，显式指定 `Project SDK`
"`java -version` 有输出，环境就好"	`JAVA_HOME` 可能为空；`javac` 可能缺失	跑 §9 的 6 条
"装最新版最省事"	非 LTS 半年停更；团队项目锁版本，你装了也用不上	装 17 或 21，两个都装
"项目建在桌面就行"	路径含中文/空格/OneDrive 同步目录，会引发编译与索引异常	统一放 `~/projects` 或 `D:\projects`
"先装一堆插件再说"	插件影响启动耗时与索引，且互相冲突	先裸奔一周，按痛点装（B06）

11. 旧文对照：本篇吸收了什么、改了什么

旧文	原始内容	本篇处理
A-1347	为什么选 IDEA（大量官方功能描述，2022 年口径）	压缩为"四点真正有效的差异"；删除功能清单罗列；补"IDE 不是必需品"的判据
A-1348	Windows 安装图文（2022.2.3）	保留五步流程；补"PATH 勾选、路径无中文"两条实践建议；版本改为基线 2025.x
A-1349	macOS 安装（推荐 2021.2.2 + 规避授权）	保留安装流程与芯片选择（新增 aarch64/Intel 区分）；删除规避授权段落并说明理由
A-1351	启动界面四入口、是否导入设置	全部保留，改为表格；补"别急着改主题"的顺序建议
A-1352	创建 Java 项目、索引说明	保留；补六个参数的逐项含义、`exit code 0` 的读法、SDK 缺失的两条路径
A-1396	工具导航清单（SSH/MySQL 客户端）	移入 S01-X01 附录；本篇仅在 §5 提一句命令行启动器
A-1397	IDEA 安装/插件/快捷键大表	安装与布局部分吸收；插件与快捷键分别下沉到 B06、B05
A-1352 附带的"JDK 安装"链接	外链教程	升级为本系列 B02 正文（不再依赖外链）

新增内容（E 点）：E-S01-007（Ultimate/Community 能力边界）、E-S01-009（VS Code 替代路径）、以及 §8 的"IDE 背后做了什么"对照实验——旧文完全没有这一层。

12. 自测

只装了 JRE 没装 JDK，java -version 和 javac -version 分别会怎样？
java -version 显示 21，mvn -v 显示 17，最小成本的修法是什么？先看哪个文件/变量？
IDE 里项目全红，但终端 mvn -q compile 成功。第一反应应该做什么？
为什么建议"不要用 IDE 内置下载器装 JDK"？
你在 Windows 上把项目建在 C:\Users\张三\Desktop\新建文件夹，可能遇到哪三类问题？

答案都在正文里能找到；第 2、3 题是 B02 与 B03 的引子，答不上来先记下来。

13. 下一篇

S01-B02 · JDK 安装与多版本共存：JAVA_HOME 到底该指向谁

本篇留了一个悬念：java 能用但 JAVA_HOME 是空的。下一篇从"一台机器装 17 和 21"开始，讲清三条常见切换路径（update-alternatives / sdkman / 手工改环境变量）的优劣，并解决"IDE、Maven、java 三处版本对齐"这个最高频的环境事故。

本篇属于系列《S01 · 开发环境与工具链》。旧文来源：A-1347 / A-1348 / A-1349 / A-1351 / A-1352 / A-1396 / A-1397；点位映射见 ../coverage.csv。