写这篇文章的起因很简单：最近帮两个同事分别配了 Scala 开发环境，一个卡在版本选择，一个卡在 IDEA 里怎么都识别不了 Scala SDK。这事看着不起眼，真踩起坑来能浪费一下午。所以我把这次的完整过程——从 scala-2.12.15 和 IDEA2021.1.3 这两个版本的搭配逻辑，到 JDK 安装、环境变量配置、IDEA 插件设置、第一个工程的创建运行，再到各种报错怎么排查——系统地整理出来。如果你也正准备搭 Scala 环境，或者已经被环境问题折磨得想放弃，这篇文章可以直接照着抄。
这套组合现在很多企业项目和课程里还在用，尤其是 Spark、Hadoop 生态的老项目几乎清一色跑在 Scala 2.12 上，IDEA 2021.1.3 本身也足够稳定。本文按实际工程习惯来写，Windows 和 macOS 的差异我会单独标出来，新手跟着做基本不会翻车。
1. 搭环境之前的版本选择，为什么是这两个数字
1.1 Scala 2.12.15 在 2.12 序列里是个什么位置
先解决一个最核心的问题：网上 Scala 版本一抓一大把，2.11、2.12、2.13、3.x，为什么偏偏挑 2.12.15？
Scala 2.12 是 Scala 2.x 时代非常成熟的一个版本线，大量企业级框架尤其是大数据生态的 Spark、Kafka、Flink 的老版本，都构建在 2.12 之上。2.12.15 是 2.12 系列后期的一个维护版本，发布于 2021 年，没有 2.12.16、2.12.17 那种后续修补版本满天飞的问题，属于这个系列里比较“稳”的收官版本之一。对于学习 Scala 语法、做课程设计、接手企业老项目来说，2.12.15 是兼容性和稳定性平衡得最好的选择。
那为什么不直接上 2.13 甚至 3.x？2.13 引入了不少集合库的破坏性变更，很多老库的二进制兼容性没跟上，你拿 2.13 写代码，一旦要用某个老版本的第三方依赖，编都编不过。3.x 就更不用说了，语法层面虽然更现代，但很多 Spark 相关的教程和框架插件还停留在 2.12 生态。所以，除非你明确知道自己要用的框架只支持更新版本，否则从 2.12.15 入手是最不容易出问题的。
1.2 IDEA 2021.1.3 的优势与兼容性
IDEA 版本也是同样的道理。2021.1.3 是 JetBrains 在 2021 年 5 月左右发布的维护版本，它对应的 Scala 插件版本与 2.12.15 磨合得已经非常成熟，不会出现“插件版本太新导致 SDK 加载失败”的闹心事。
有些同学喜欢追新，直接装最新版 IDEA，然后发现内置的 Scala 插件对新语言版本适配没问题，但对 2.12.15 这种“老版本”反而有时候会出现编译警告或者 SDK 索引异常。不是不能用，是没必要给自己添堵。IDEA 2021.1.3 对系统资源的要求也相对友好，4G 内存的笔记本跑起来依然流畅。当然，如果你已经装了更高版本的 IDEA，也完全可以照着本文配置，只是界面菜单位置可能略有区别，核心思路一样。
1.3 动手前先确认已有软件清单
在开始之前，我强烈建议你先花五分钟清点一下自己的电脑，避免配到一半发现缺东西又回头补。
需要准备的东西有这些：
- 一台能正常联网的电脑，Windows 10/11 或者 macOS 都行。
- JDK，注意是 JDK，不是 JRE。Scala 编译器本质上跑在 JVM 上，没有 JDK 连编译这一步都过不去。
- IDEA 2021.1.3 的安装包，去 JetBrains 官网或者你之前下载过的渠道找，这里不做破解方面的讨论，正常渠道获取授权即可。
- Scala 2.12.15 的安装包，建议下载 zip 包而不是 ms 安装包，原因后面我会说。
另外提醒一句，如果电脑上原本装过老版本的 JDK 或 Scala，建议先把它们的环境变量清理干净，再开始装新的。因为环境变量冲突导致“明明装好了却还是旧版本”的情况，我遇到太多次了。
2. JDK 装不对，后面全白搭
2.1 JDK 到底装哪个版本
Scala 2.12.15 官方要求 JDK 8 及以上，但我首推 JDK 8，也就是 Java 1.8。为什么？因为 Scala 2.12 系列就是和 JDK 8 同步发展起来的，大部分第三方 Scala 库在 JDK 8 上测试得最充分。Spark 3.x 官方文档里明确写的也是支持 Java 8/11，但生产环境大量跑的还是 JDK 8。
你要是装个 JDK 17，也不是完全不能用，但有可能遇到某些框架反射、动态代理相关的兼容问题，对一个刚入门的同学来说，这些报错会让你的排查成本翻倍。所以这里不要有版本洁癖，老老实实装 JDK 8 是最省心的路子。
JDK 8 的版本号也有讲究。Oracle 的 JDK 8 最后一个免费商用版本是 8u202，之后的就是要收费的商业版了。不想折腾的话，直接用开源的 Adoptium（也就是 Eclipse Temurin）JDK 8，或者是阿里、华为的 OpenJDK 发行版，都行。这些都是长期维护的免费版本，环境配置方式完全一致。如果不确定下哪个，去 Adoptium 官网下载 Eclipse Temurin JDK 8 最新版就行，网上搜索“temurin jdk 8 download”就能找到。
2.2 Windows 和 macOS 的 Java 环境变量配置
JDK 安装完成之后，最关键的一步是配置 JAVA_HOME 和 PATH。这一步要是配错了，后面 Scala 和 IDEA 全部都会出问题。
Windows 下的操作路径是这样：右键“此电脑”→“属性”→“高级系统设置”→“环境变量”。在弹出的窗口里，先在“系统变量”区域点击“新建”，变量名填JAVA_HOME，变量值填你的 JDK 安装路径。注意这里一定要填到 JDK 的根目录，不要填到 bin 目录。比如你装在C:\Program Files\Eclipse Adoptium\jdk-8.0.392.8-hotspot，JAVA_HOME 就填这个完整路径。
然后找到系统变量里的Path，双击打开，在末尾新增一行%JAVA_HOME%\bin。这里有个细节：Windows 的 Path 编辑界面，老版本是分号分隔的一整行字符串，新版本是列表形式，按行添加就行。添加完之后一路点“确定”保存。
macOS 上稍微简单一点，但要注意现在的 Mac 默认 shell 是 zsh，不是以前的 bash。打开终端，执行vim ~/.zshrc，在文件末尾加上两行：
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) export PATH=$JAVA_HOME/bin:$PATH如果你 Mac 上装了多个 JDK，这个命令会自动找到 1.8 版本的路径。保存后执行source ~/.zshrc让配置立即生效。
Linux 的话，编辑~/.bashrc或~/.zshrc，加同样的 export 内容即可。
2.3 验证 JDK 是否真的配好了
配置完环境变量，不要急着装 Scala，先验证 JDK 到底配置成功没有。打开一个全新的终端窗口，注意这里有个大坑：Win 系统里如果你之前的环境变量窗口没关，新配置是不会生效的，必须重新打开一个命令行窗口。
然后依次输入两条命令：
java -version javac -version如果看到类似下面的输出，说明 JDK 没问题：
java version "1.8.0_392" Java(TM) SE Runtime Environment (build 1.8.0_392-b01) Java HotSpot(TM) 64-Bit Server VM (build 25.392-b01, mixed mode)javac -version输出javac 1.8.0_392这种格式就对了。重点检查两点：第一，java和javac两条命令都得能跑通，只java -version能用但javac报找不到，通常是 PATH 里 JRE 和 JDK 混了；第二，版本号必须是 1.8 开头，如果你输入后看到版本是 17 或者 21，说明系统里还有其他 JDK 抢先占用了 PATH，得把旧的清理掉。
这一步虽然枯燥，但它是整个 Scala 环境的地基。地基歪了，后面装 Scala、配 IDEA，全都会出现奇奇怪怪的错误。
3. Scala 2.12.15 安装与命令行验证
3.1 下载和目录规划
JDK 就绪之后，开始装 Scala 本体。去 Scala 官网的 archive 页面下载 scala-2.12.15 的 zip 包。官网默认推荐的是当前最新版本，所以你要在页面里找到 archive 链接，进入历史版本列表，再找到 scala-2.12.15。
下载 zip 包而不是下载 exe 安装包，主要有两个原因：一是 zip 包是绿色版，解压即用，卸载的时候直接删文件夹就完事，不用跟安装向导里的系统残留作斗争；二是团队协作时，同样的解压路径可以在多台机器上复现相同配置。
解压的时候要做好目录规划，我建议统一放到一个比较好找的路径下，比如 Windows 的D:\dev\scala-2.12.15，macOS 的/Users/你的用户名/dev/scala-2.12.15。尽量避免把 Scala 解压到有空格的路径里，比如Program Files，因为后续有些工具脚本在带空格的路径下容易出幺蛾子。
3.2 配置 SCALA_HOME 与 PATH
Scala 安装完后，同样需要配置环境变量，逻辑跟 JDK 一模一样。
Windows 用户照旧打开环境变量设置面板，新建一个系统变量：
- 变量名：
SCALA_HOME - 变量值：
D:\dev\scala-2.12.15（换成你自己的路径）
然后在Path里新增一行%SCALA_HOME%\bin。
macOS 用户在~/.zshrc里追加：
export SCALA_HOME=/Users/你的用户名/dev/scala-2.12.15 export PATH=$SCALA_HOME/bin:$PATH然后执行source ~/.zshrc使之生效。这里我又要强调一遍：修改完环境变量后，务必开一个新的终端窗口再测试，而不是在旧窗口里直接敲命令。旧窗口的环境变量是启动时就快照进去的，你改了配置它并不知道。
3.3 scala -version 输出什么才算正常
配置完成后，在新终端里输入：
scala -version如果一切顺利，你会看到类似这样的输出：
Scala code runner version 2.12.15 -- Copyright 2002-2021, LAMP/EPFL and Lightbend, Inc.看到这个版本号，说明 Scala 编译器已经正确安装并加入 PATH 了。再顺手输入scala不带参数，会进入 Scala 的 REPL 交互界面，光标变成scala>提示符，你可以直接在里面写代码试试，比如输入1 + 1回车，它会返回res0: Int = 2。输完按:quit退出。
这一步是整篇文章里最让人有成就感的时刻，但千万别高兴太早。命令行能用的 Scala 和 IDEA 里能用的 Scala 是两码事，接下来才是真正容易踩坑的重头戏。
4. IDEA2021.1.3 里的 Scala 插件与 SDK 关联
4.1 IDEA 安装与 Scala 插件获取
IDEA 2021.1.3 的安装包可以从 JetBrains 官网的旧版本列表里下载，安装过程没什么特殊选项，一路 Next 就行。安装完之后第一次启动，它会问你要不要导入历史配置，这里选择不导入，避免老配置干扰。
打开 IDEA 之后，第一件事是装 Scala 插件。进入File -> Settings -> Plugins，在搜索框里输入Scala，正常情况下能看到 JetBrains 官方的 Scala 插件，点击 Install 装好，重启 IDEA。
这里有个高频问题：很多人反映插件市场一搜“Scala”就转圈圈，等半天没反应。这种情况一般是网络问题。处理办法有两条路：第一条，在 Settings 里搜索Plugins，找到 HTTP Proxy Settings，配置一个能用的代理，但这不是人人都有；第二条，直接去 JetBrains 插件商店官网下载 Scala 插件的 zip 包，然后在 IDEA 的 Plugins 界面点击齿轮图标，选择Install Plugin from Disk...，选中刚下载的 zip 包进行安装。这个方法不需要任何代理，最省事。
4.2 将 Scala SDK 关联到 IDE
插件装好后，还需要把 Scala 的 SDK 告诉 IDEA。这一步最容易被忽略，也是报错最多的环节。
进入File -> Project Structure（快捷键Ctrl+Shift+Alt+S），在左侧选择Global Libraries，点击加号，选择Scala SDK。在弹出的窗口里，默认会列出 IDEA 自动扫描到的 Scala 版本。如果你前面在命令行配置好了 SCALA_HOME，这里通常能直接看到2.12.15这个选项，选中并点击 OK 即可。
如果下拉列表里什么都没显示，说明 IDEA 没有自动找到 Scala 安装位置。这时候点击Browse...，手动导航到你的 Scala 安装目录，选中scala-2.12.15这个根文件夹，IDEA 会识别并加载它的 SDK。如果连Browse...都选不中，还有一个更底层的办法：直接选中 scala 目录下的lib\scala-library.jar文件，IDEA 也能通过这个 jar 识别出 Scala SDK。这个方法是我自己试过很多次都管用的终极大招。
4.3 多个 JDK 版本时的 SDK 选择
还有一个常见坑，就是电脑上既有 JDK 8 又有 JDK 11 甚至 JDK 17 时，IDEA 默认可能选了新版本作为项目的 Project SDK，导致 Scala 编译器报错。
在同样那个Project Structure窗口里，确保Project SDK选的是 1.8 版本，语言级别也选 8。这一点在后面的工程创建环节还会再验证一遍。
如果你发现 IDEA 里根本没有 Project SDK 选项，那多半是 IDEA 没有识别到你的 JDK。回到Project Structure -> SDKs，点击加号选择 JDK，把 JDK 安装目录添加进去。
5. 创建并运行第一个 Scala 工程
5.1 在 IDEA 里新建 Scala 工程
前面的配置全部完成后，终于到了一试身手的时候。在 IDEA 欢迎界面选择New Project，左侧选Scala，右侧选择IDEA，意思是用 IDEA 自带的方式管理工程，不借助 sbt 或 Gradle。
如果是第一次用 Scala 创建工程，IDEA 可能会弹出一个提示，让你选择 Scala SDK。下拉框里选 2.12.15，然后点击 Finish。记住，SDK 一定要选对，这是工程能否跑起来的关键。
工程创建好之后，会生成一个标准的目录结构，src目录下默认没有包和类，需要自己手动创建。在src上右键，选择New -> Scala Class，类型选Object，名字可以叫HelloWorld，然后回车。
5.2 编写第一个 Hello World 与运行原理
在生成的HelloWorld.scala文件里，输入这样一段内容：
object HelloWorld { def main(args: Array[String]): Unit = { println("Hello, Scala!") } }写完直接在代码编辑区右键，选择Run 'HelloWorld'，在 IDEA 底部的运行窗口里，只要你看到Hello, Scala!，环境就算彻底通了。
这里我想顺带解释一下背后的运行原理，因为很多新手虽然跑通了 Hello World，但不知道发生了什么。Scala 的object HelloWorld并不是传统意义上的类，它会被编译器编译成两个 class 文件：一个HelloWorld.class，一个HelloWorld$.class。Scala 的 main 方法实际上存在于伴生对象HelloWorld$中，HelloWorld.class里的 main 方法只是一个静态转发器，真正干活的逻辑在HelloWorld$.MODULE$.main()里。这也是为什么 Scala 能运行在 JVM 上、能无缝使用 Java 类库的原因——编译后的字节码本质上就是 Java 字节码。
5.3 验证 Class 文件与跨平台运行
如果你想进一步确认编译产物，可以在 IDEA 的终端面板里，或者在系统终端中进入工程的target/classes目录，执行：
scala HelloWorld会再次输出Hello, Scala!。这说明同一套 Scala 代码既可以在 IDE 里跑，也可以脱离 IDE 用命令行直接运行。以后写脚本、做批处理任务时，这条路是很有用的。
到这里，Scala 环境搭建的主流程就结束了。整个流程走通，说明 JDK、Scala SDK、IDEA 插件、编译器这几个环节已经组成了一条完整通路。
6. 常见问题速查与实战避坑
6.1 高频报错及处理方式
环境搭建过程中我遇到过不少问题，下面把最高频的几个整理成表格，方便你对号入座。
| 报错现象 | 可能原因 | 解决办法 |
|---|---|---|
命令行输入scala提示“不是内部或外部命令” | PATH 环境变量没配对，或新窗口没开 | 检查%SCALA_HOME%\bin是否在 Path 里，开新终端重试 |
scala -version显示的是旧版本号 | 系统中存在多个 Scala 残留 | 清理旧的 SCALA_HOME 和 PATH 条目 |
| IDEA 里新建工程时找不到 Scala SDK | 插件未装成功，或 IDEA 扫描失败 | 重装插件；手动 Browse 到 scala 目录；或选中 scala-library.jar |
Cannot resolve symbol Scala | 插件装了但 SDK 没关联到当前工程 | 打开 Project Structure，为 Global Libraries 添加 Scala SDK |
编译时报Unsupported class file major version | JDK 版本过高，Scala 2.12 不够兼容 | 把 Project SDK 换成 JDK 8 |
运行时报Error: Could not find or load main class | 工程的输出目录配置异常，或 SDK 未正确加载 | 清理缓存：File -> Invalidate Caches，重启后重新编译 |
| IDEA 插件市场加载一直转圈 | 网络无法正常访问插件仓库 | 手动下载 Scala 插件 zip 包，从磁盘安装 |
6.2 环境变量配置不生效的几个深坑
排障过程中，有几个问题是反复出现的，值得单独拿出来讲。
第一个是最容易被忽略的“管理员权限坑”。如果你是在 Windows 上修改环境变量，注意当前用户环境变量和系统环境变量是两回事。你把 SCALA_HOME 配到用户变量里，然后用管理员身份开的命令行窗口，理论上两个窗口都能读到用户变量。但问题往往出在有些第三方终端工具（比如某些版本的 Git Bash、PowerShell 旧窗口）不会实时刷新环境变量，导致你以为没生效。处理办法就是：配置完环境变量后，把所有终端窗口全部关闭，重新打开一个新的。
第二个是“JAVA_HOME 指向了 JRE”。打开环境变量检查一下，如果 JAVA_HOME 指向的路径是...\jre，那不对，那是 JRE 不是 JDK。JAVA_HOME 应该指向 JDK 的根目录，像C:\Program Files\Java\jdk1.8.0_202这样。判别方法很简单：看这个目录下有没有bin\javac.exe，有 javac 的才是 JDK，只有 java 没有 javac 的是 JRE。
第三个是 Scala REPL 能启动，但 IDEA 里编译失败。这种情况我先说说经验判断：多半是 IDEA 里的 Project SDK 和 Global Libraries 里 Scala SDK 的 JDK 版本不一致。比如 Project SDK 用的 JDK 17，Scala SDK 是用 JDK 8 编译的，运行时就会因为字节码版本不兼容而报错。把两个地方统一成 JDK 8 基本就能解决。
6.3 给新手的几条忠告
- 装环境最忌讳的就是“凭感觉选个最新版”。Scala 生态非常看重版本匹配，JDK、Scala、IDEA 插件三者是绑在一起工作的，任何一环版本乱跳都可能让你浪费大半天。
- 命令行里的
scala -version验证步骤不要省略，也别只测java -version。我见过有人一路配到 IDEA 才发现 scala 命令根本不可用，最后回头排查发现 SCALA_HOME 拼错了。 - 每次修改环境变量之后，把已经打开的所有 IDEA 项目也关掉重新打开。IDEA 在启动项目时会缓存环境变量，不会自动感知系统配置的变化。
- 如果照着步骤做还是有问题，先冷静看一下报错信息，大部分环境类报错都会直接告诉你是哪一步脱节了。别一上来就重装 IDEA，重装是所有方案里效率最低的一个。
关于 Scala 环境搭建，我个人最深的体会是：版本匹配比安装动作本身更重要。JDK 选 1.8、Scala 选 2.12.15、IDEA 选 2021.1.x，这三者组合起来会顺畅得像个稳定的老搭档。这套环境配好之后，后面无论是学 Spark 还是上手写 Scala 业务代码，都算是有了一个可靠的起点。最后再分享一个小经验：建议把 JAVA_HOME、SCALA_HOME 的路径写在一个本地备忘里，将来换电脑、换系统时，照着备忘十分钟就能恢复一套一模一样的开发环境。
