简介：Scala-升级版.docx 是一份面向 Scala 入门者及 Spark 开发者的升级版学习笔记，立足于 Spark 1.6 依赖 Scala 2.10、Spark 2.0 以后升级到 Scala 2.11 的实际背景，系统讲解多范式特性、类型推测、高阶函数、模式匹配、特质与 Java 互操作等六大特征，并强调学习 Scala 对理解和开发 Spark 应用的重要性。文档从零梳理安装与开发环境搭建，覆盖 Windows/Linux 下 JDK 1.8、Scala 2.11.8 的安装与环境变量配置，其中 Windows 下可通过 msi 安装并配置 SCALA_HOME，Linux 下直接解压二进制包即可；同时说明 Eclipse、Scala IDE、IntelliJ IDEA 中 Scala 插件的安装和 SDK 设置，方便读者快速跑通开发环境、避免常见环境问题。语法部分包含基本数据类型、var/val 变量与常量、if 表达式、类与单例对象、伴生类与伴生对象、apply 方法等常用知识点，配有 Person、Lesson_Class 等可运行示例，适合边读边动手练习。资源为单个 docx 文档，压缩包约 2.04MB，已有 2060 人学习下载，可作为快速入门 Scala、理解 Spark 开发基础的简明参考资料。
1. 先别急着打开 docx：Scala-升级版 到底在升什么
拿到一份命名为 Scala-升级版.docx 的交付文档，先别急着双击打开，多数情况下它不是一个学习笔记，而是一份已经拍板要执行的升级方案。所谓升级版，不是说某个框架发布了新版，而是项目里的 Scala 主版本要往前挪，常见的路径是从 2.13 迁到 3.x。这个动作背后牵扯三件事——构建配置怎么改、依赖闭包怎么收敛、存量代码怎么批量迁移。文档只是把结论写下来，真正干活的人要自己把每一步跑通。这篇文章按我处理同类任务的顺序展开，先从版本和依赖里把现状捞出来，再搭一个可复现的构建，然后处理代码差异，最后把最容易翻车的地方和验证方式讲透。适合正在接手 Scala 跨版本迁移的开发者，也适合准备给团队排期的技术负责人。
2. 从 Scala-升级版 提取交付边界：先确认起点再谈终点
这类升级文档最常见的通病是只写目标版本，不写现状版本；如果不先对齐起点，后面所有依赖分析都是空转。我自己接手的第一个动作不是读文档，而是把项目根目录的构建信息捞出来。先看编译器和 sbt 版本，再看子模块之间的差异，最后才拿文档里的“改动清单”去对号入座。原因是 Scala 的跨主版本升级不像换一个接口那样轻松，编译器和标准库的版本一旦错位，报错信息会把你引向完全错误的方向。
2.1 版本起点不是看文档封面，而是看编译器与构建文件
先跑一组命令确认现状。下面这段在项目根目录执行，前两个命令只做粗判断，第三个命令才是真正生效的编译版本。
# 看看当前命令行默认的 scala 编译器版本 scalac -version # 检查 sbt 版本，太旧的话连 Scala 3 的构建都加载不了 cat project/build.properties # 查看项目实际的 Scala 编译版本，多模块仓库要看每一个子项目 sbt "show scalaVersion"这里有个容易踩的细节：scalac -version显示的是 PATH 上的编译器，不一定等于项目里 sbt 正在用的编译器。比如你 shell 里装的是 2.13.10，但项目里的project/build.properties已经把 sbt 指到了另一个目录，最后编译用的版本以sbt "show scalaVersion"为准。project/build.properties里的sbt.version也不能只看格式，它决定了 sbt 能不能加载依赖解析相关的插件；老版本 sbt 在 Scala 3 的构建模式下会出一些很奇怪的错误，报错信息往往和真正的代码问题无关。
确认版本之后，还要把目标版本定住。我的习惯是优先选 LTS 线，比如 Scala 3.3.x，而不是追最新的大版本。对存量项目来说，“别人用了两年”比“多了几个新特性”重要得多。迁移期最怕的是目标版本本身还在剧烈演进，今天调通的参数，过两周又变了。文档封面如果只写“升级版”三个字，那你第一步要做的就是把这句话翻译成具体的版本号组合。
| 检查点 | 命令 | 用途 |
|---|---|---|
| 默认编译器 | scalac -version | 只看 PATH 上的编译器 |
| sbt 版本 | cat project/build.properties | 判断 sbt 是否支持 Scala 3 |
| 实际编译版本 | sbt "show scalaVersion" | 项目真正用的版本 |
| 交叉编译范围 | sbt "show crossScalaVersions" | 判断是否有双版本编译配置 |
crossScalaVersions是最容易被忽略的一行。如果 build.sbt 里已经写了Seq("2.13.10", "3.3.4")，说明之前的维护者已经在做双版本兼容，升级压力会小很多；如果只有"2.13.10"，那就老老实实当它从零开始。文档里如果写了“保持向下兼容”，建议先在本地跑一遍sbt ++2.13.10 compile和sbt ++3.3.4 compile，看看两个版本能不能同时通过。这一步能帮你判断后续是“顺水推舟”还是“推倒重来”。
2.2 从 docx 里的改动项映射到三张清单
方案文档里一般会有一堆背景描述，但真正能指导落地的是改动项。我会把 docx 里的每条改动需求先映射到三张清单上，不然后面改代码时会被无关信息干扰。第一张是构建清单，包含 sbt 版本、scalaVersion、crossScalaVersions、scalacOptions 以及打包方式；第二张是依赖清单，列出所有%%坐标、scope 和发布状态；第三张是代码清单，重点标记隐式转换、宏、反射、序列化和编译器插件。这三张清单不是写给文档看的，是写给接下来的编译日志看的。
# 把全量编译的错误和警告落盘，待办清单就从这里生成 sbt clean compile > compile.log 2>&1 grep -nE "\[error\]|\[warn\]" compile.log | head -200这里有一个常见的误区：拿compile.log去数错误条数，然后认为错误少就好做。实际上一处上游 API 变化可能引发下游几十个类型错误，正确的做法是按“源文件”聚合，而不是按“错误行”聚合。先看哪些文件报错最多，再从依赖关系最底层的模块开始改，错误会成片消失，而不是越改越多。依赖清单的核查动作用sbt evicted最直接，它会列出所有被降级或冲突的依赖，其中跟 scala-library 相关的冲突优先级最高。
跨主版本升级时，一个库如果只有_2.13构件而没有_3构件，sbt 不一定报错，它可能选择另一个版本默默顶上，但运行时会冒出奇奇怪怪的 ClassNotFound。所以sbt evicted之后，凡是无法确认来源的冲突项，都要去依赖坐标里逐条看。这时候不要轻信文档里写的“该库已支持 Scala 3”，因为“支持”在 sbt 的坐标体系里意味着存在_3或经过交叉编译验证的_2.13构件，这两者的行为差异只有运行测试才能暴露。
# 冲突列表和完整 classpath，是评估升级工作量的第二张底牌 sbt evicted sbt "show fullClasspath"show fullClasspath输出的内容很长，建议输出到文件里再按scala-library、scala3-library等关键字过滤。升级边界不需要一开始就定义到每个类，但至少要能回答一个问题：项目里到底有没有依赖闭包外的“裸 class 文件”。如果有，那升级文档里必须先给这类资源单独安排兼容方案，而不是直接假设编译器能解决。
提示：本地的编译错误会随着迁移进度变化，建议每次改动前重新生成 compile.log，不要拿昨天的错误清单指导今天的修改。
3. 搭可复现的升级构建：build.sbt 与 scalac 参数迁移
构建配置是整个升级的骨架，如果骨架是歪的，代码改得再干净也会在 CI 上翻车。我在迁移第一天就会把 build.sbt 拆成“迁移期配置”和“目标配置”两部分，而不是一次性切成 Scala 3 的干净形态。这样做的原因是：迁移期间要频繁在两个版本之间切换，配置的可逆性比美观重要。
3.1 用最小 build.sbt 先跑通“新编译器读旧代码”
迁移期的 build.sbt 不需要一次写全所有参数，反而应该尽量精简。保留最基础的编译信息、依赖坐标，以及关键 scalac 参数就够了。下面这份是我常用的骨架，只多不少。
// build.sbt —— 迁移期骨架 ThisBuild / scalaVersion := "3.3.4" ThisBuild / organization := "org.example" ThisBuild / version := "1.0.0" ThisBuild / scalacOptions ++= Seq( "-deprecation", "-feature", "-unchecked", "-source:3.0-migration" ) libraryDependencies ++= Seq( "org.example" %% "common-utils" % "1.4.2", "org.example" %% "data-model" % "2.1.0" )%%在这里非常关键。它表示“按当前 Scala 二进制版本选择构件”，在 Scala 2.13 下解析common-utils_2.13，在 Scala 3 下解析common-utils_3。如果某个依赖只有_2.13构件，又没有源码，%%会让解析直接失败；此时要么换一个维护中的库，要么改用%显式指定旧构件，但后者运行时风险很高，只能在迁移期临时过渡。%写法会让你在 Scala 3 的 classpath 里混入 2.13 编译的字节码，短时间能跑通，长期维护时它会变成一颗定时炸弹。
-source:3.0-migration是我在迁移期必开的一个参数。它让编译器在遇到旧语法时给出更明确的迁移提示，而不是只丢一句“expected ... but found ...”。它的作用是降低排查成本，不是自动改代码。真正能自动改的是迁移插件，但前提是依赖能被新编译器顺利解析，所以在配置阶段先不要引入太多重量级插件，把主干跑通再谈自动化。project/build.properties里的 sbt 版本和 scalaVersion 是两套东西，不要混为一谈。前者决定 sbt 本身，后者决定编译器。我在同样情况下会优先使用 1.9.x 的 sbt，因为这个区间的版本对 Scala 3 的交互命令支持比较完整，而且很多旧插件在改名时出现过兼容断层。
# project/build.properties sbt.version=1.9.9配置写完先跑一次sbt "show scalaVersion"确认新编译器真的生效。这一步看似多余，但能避免一种非常隐蔽的情况：某个子模块的 .sbt 文件里有一行旧的scalaVersion覆盖了根目录配置，导致你以为在用 Scala 3，实际还在 2.13 下面编译。多模块项目尤其容易出现这种问题，因为根目录的ThisBuild / scalaVersion不会自动覆盖子项目里显式写的scalaVersion。遇到这种情况，优先把子模块里的显式 scalaVersion 改成继承根配置，而不是在迁移期间维护多套编译器版本。
3.2 scalac 参数翻译对照表：别让旧参数把错误掩盖
很多从 2.13 直接搬过来的 scalac 参数，在 Scala 3 里要么失效，要么改名。最典型的是未使用 import 的告警参数，写法从-Ywarn-unused:imports变成了-Wunused:imports。如果你把旧的-Ywarn-unused原样贴过去，编译器不会报错，但它根本不生效，等你后期打开 fatal warnings 时才会发现大量垃圾代码早就被当成了合法代码。
| 目标 | Scala 2.13 写法 | Scala 3 写法 | 说明 |
|---|---|---|---|
| 废弃 API 警告 | -deprecation | -deprecation | 两个版本通用 |
| 语言特性警告 | -feature | -feature | 两个版本通用 |
| 未使用 import | -Ywarn-unused:imports | -Wunused:imports | 参数名变更 |
| 未使用参数 | -Ywarn-unused:params | -Wunused:params | 参数名变更 |
| 致命警告 | -Xfatal-warnings | -Xfatal-warnings | 两个版本通用 |
| 迁移提示 | 无 | -source:3.0-migration | Scala 3 新增 |
这张表不要求一次全部打开。我的习惯是先只开-deprecation -feature -unchecked和-source:3.0-migration，把编译错误收敛干净后再开-Wunused。-Xfatal-warnings在迁移期一律不开，否则一个未使用 import 就能把整个构建卡死，你会分不清它到底是错误还是警告。等 CI 连续跑一周后，再把它加进去做守门员，那时才是它真正发挥作用的时间点。
验证 scalacOptions 是否生效，不要靠记忆，用命令直接看。sbt 里可以单独查某个子项目的最终参数，如下所示。
# 查看某个模块最终生效的编译参数，判断是否被旧配置覆盖 sbt "show core / scalacOptions"如果core子项目里自己写了一组旧的 scalacOptions，根目录的ThisBuild / scalacOptions不会覆盖它，而是两者按顺序拼接。最常见的翻车是子项目里留着-Ywarn-unused:imports，根目录加了-Wunused:imports，最后查出来的参数里既有旧写法又有新写法，警告却没被真正控制住。排查这种问题，show core / scalacOptions比人肉读 build.sbt 可靠得多，因为你永远不知道某个不起眼的 .sbt 文件里藏着什么覆盖。
依赖参数同样值得提前对齐。Scala 3 项目里org.scala-lang:scala-library实际走的是 2.13 基线，不要再想着用scalaVersion去统一所有 scala-library；这个前提不理解，后面遇到sbt evicted时会花很多冤枉时间。判断一个依赖是否真的兼容 Scala 3，最靠谱的方式是在目标版本下编译并运行测试，而不是看它的坐标里有没有_3后缀，因为带_3后缀的构件也可能只提供源码级别的兼容，运行时行为仍然分叉。
4. 代码迁移三件套：清单、自动改写、手工兜底
构建跑通之后，真正的体力活才刚开始。代码迁移不能靠“全局搜索替换”，也不能靠人肉盯着屏幕一整天。我用的是一个固定流程：先生成错误清单，再让自动化工具处理模式化改写，最后手工处理那些工具改不动的边界。这个流程听起来普通，但能保证每走一步都有可回滚的检查点。
4.1 用编译日志生成待改清单，而不是人肉翻源码
我见过有同学直接在 IDE 里打开所有带红线的文件，从上往下一个个改。这种做法的问题不在于改得慢，而在于改的过程中新错误会被不断触发，等改到一半时已经搞不清哪些是存量问题、哪些是这次改出来的问题。
# 全量编一次，把错误和警告分别落盘 sbt clean compile > compile.log 2>&1 # 按错误和警告分流，方便后续按文件聚合 grep -E "\[error\]" compile.log | sort -u > errors.txt grep -E "\[warn\]" compile.log | sort -u > warnings.txt # 统计数量，决定下一步的优先级 wc -l errors.txt warnings.txtsort -u会把相邻重复的错误合并，但 Scala 编译器经常在同一文件上打印多条不同位置但同根源的错误。所以拿到errors.txt之后，我还会按文件路径聚合，从报错数量最多的文件开始处理。下面的命令把错误日志里的路径提取出来，按出现次数排个序。
# 按源文件聚合成“改动成本排行” grep -E "\[error\]" compile.log \ | sed -E 's/^\[error\] ?//' \ | sed -E 's/:[0-9]+:[0-9]+:.*//' \ | sort | uniq -c | sort -rn | head -30这个聚合逻辑不需要很精致，能看出“哪些文件是重灾区”就够了。迁移期最常见的心理陷阱是把小 errors 先修完，留下难啃的大文件；但真正值得先动的是被最多代码依赖的底层模块。底层文件一旦迁移通过，它子树上的错误会大幅减少，顶层文件反而简单。拿到这份排行后，把它和依赖方向对齐：先改被依赖方，再改调用方，这是所有跨版本迁移都要遵守的顺序。
迁移插件的价值在这个阶段才会体现出来。常见做法是在 build.sbt 里临时引入一个用于 Scala 3 迁移的插件，然后让它对指定模块生成改写补丁。插件能做的是把大部分implicit改写成given/using、把旧式 extension 方法改成 Scala 3 的extension语法。注意，插件生成的是“建议补丁”，不是“正确结果”，每个补丁都要过一遍编译和单测。补丁不能全盘接受，尤其是涉及隐式优先级和反射的地方，机器只能改语法，改不了语义。
4.2 隐式、扩展方法、宏：改动量最大的三类差异
Scala 3 最明显的语法变化集中在隐式体系和扩展机制上。这两块能自动改写大部分，但自动改写之后经常出现语义不完全等价的情况，所以要知道每一处改动背后的原因，而不是机械地跟着补丁走。
先看隐式参数。2.13 里常见的模式是implicit val加上implicit参数，Scala 3 用given和using表达同样的意图。下面的对照是迁移中最常见的一处。
// Scala 2.13 写法 implicit val defaultCtx: Ctx = Ctx("local") def connect(name: String)(implicit ctx: Ctx): Unit = ??? // Scala 3 写法 given defaultCtx: Ctx = Ctx("local") def connect(name: String)(using ctx: Ctx): Unit = ???这里有一点值得留意：调用点通常不用改，因为 using 参数和 implicit 参数一样都是自动补参，但作用域的搜索规则并不完全相同。Scala 3 对 given 实例的查找更强调当前作用域和类型，存在多个候选项时容易从“隐式找到了唯一一个”变成“ambiguous”。迁移后如果冒出大量 ambiguous，不要急着到处加类型标注，先看看是不是有两个库都发布了 Scala 3 版本，导致同一类型的 given 出现了两次。
扩展方法也是高频差异。2.13 里用implicit class做扩展，Scala 3 推荐直接用extension。改写本身很简单，但要注意扩展方法的作用域从“隐式导入”变成了“显式导入或定义在同一个包”。如果原来依赖隐式作用域到处可用，改成 extension 后会有一批编译错误，那是正常的，把 import 补上就好。
// Scala 2.13 的隐式类 implicit class RichString(val s: String) { def isBlank2: Boolean = s.trim.isEmpty } // Scala 3 的扩展方法 extension (s: String) def isBlank2: Boolean = s.trim.isEmpty宏是三类差异里最麻烦的。2.13 的黑匣子式宏在 Scala 3 里基本不可用，编译器插件也一样。如果项目里有自己维护的宏，迁移成本不是几小时能估完的，因为 Scala 3 的宏基于 Quotes 和 Expr，API 和 2.13 完全不同。如果宏来自第三方库，先别急着找替代品，去确认它有没有 Scala 3 版本；没有的话，我一般会先把宏调用改成普通方法，数据结果可能略有不同，但至少不会挡升级。宏依赖的评估应该在排期阶段就完成，而不是等到改代码时才发现整个模块的编译期能力被连根拔起。
模式匹配和枚举的变化也会影响一些边界。Scala 3 的enum比 2.13 里的sealed trait + case object更简洁，但对于已经在线上序列化过的数据，不要因为“好看”就把 ADT 结构彻底换掉，否则历史数据反序列化会直接翻车。这一点在下一章专门展开。
5. Scala 升级避坑：编译、依赖、运行时的 5 个高频问题
这一章写给正在迁移路上挣扎的人。下面 5 个问题是同类升级里最高频的，每个都按现象、原因、解决三步写，方便直接对照。
5.1 现象：sbt evicted 一片红，运行时报 NoClassDefFoundError
明明编译通过了，sbt run却抛NoClassDefFoundError，类名指向scala.collection或scala.xml之类的内部结构。原因多半不是代码问题，而是 classpath 里有多个 scala-library 来源，最典型的场景是把一个只有_2.13的旧构件用%硬塞了进来，运行时 sbt 选择的 Scala 3 版本和编译时不一致。解决方法是回退到%%，并让依赖尽量跟随编译器基线；项目里真正需要单独锁版本的库，应该是业务库，而不是 scala-library。
5.2 现象：implicit 改完 given/using 后，调用点却报 ambiguous
迁移插件会把implicit val改成given，把implicit参数改成using，但作用域搜索规则没有自动对齐。表现是同一个方法在迁移前能找到唯一隐式，迁移后报 ambiguous。常见原因有两个：一是两个库都定义了相同类型的 given，二是旧代码里把隐式定义在伴生对象中，Scala 3 的搜索顺序和 2.13 不同。先打开-source:3.0-migration看提示定位，再把不必要的 given 移到更局部作用域，通常能解决。如果实在找不到来源，用sbt "show core / fullClasspath"把参与编译的 jar 列表拉出来，对比两个 jar 里是不是都带同一个类型定义。
5.3 现象：sealed trait 序列化结构变了，线上数据读不回来
这个坑最容易在切换enum时出现。2.13 里把case object序列化成 JSON，字段名或类型标记依赖类名；改成 Scala 3enum后，编译器生成的类名和方法签名都变了，历史数据按旧字段找不到对应值。原因不是 Scala 3 的 enum 有问题，而是序列化结构升级了。解决方法是迁移期不要改 ADT 的物理结构，保留原来的sealed trait + case object，等线上数据全部能正常读回之后，再讨论是否切到 enum。数据读不回来是没有后悔药的，所以先做一条“旧数据反序列化”的单测再动手。
5.4 现象：第三方宏库或编译器插件直接报 incompatible
现象很直白：升级到 Scala 3 之后，某个依赖里带macro字样的类在编译期抛出 “no macro paradise” 或 “unsupported flavor”。原因是 Scala 2 的宏体系已经被 Scala 3 的 Quotes/Expr 取代，旧宏不可能直接兼容。解决路径有三条：找维护者发布的 Scala 3 版本；把宏替换成普通函数调用；实在绕不开就暂时保留一个 2.13 独立模块，只让跨模块边界传普通对象。第三招是过渡方案，不能当长期架构，否则升级完成后你还是要回来还这笔技术债。
5.5 现象：本地编译通过，CI 里却因为 warning 变成 error
本地明明没报错，CI 一到-Xfatal-warnings就挂。原因是迁移期有人在子模块里留了旧 scalacOptions，把-Ywarn-unused:imports和-Xfatal-warnings同时打开了，而未使用 import 在 Scala 3 下被当成了 error。解决方法是先查show scalacOptions，统一成新参数，再把-Xfatal-warnings推迟到迁移完成后打开。这个坑看起来小，但非常消耗信心，因为它会让每次提交都红。
6. 固化验证：用双版本编译和模块标记文件，把升级变成日常动作
升级文档写完不算完，真正的交付物是一套能反复跑的验证流程。我的做法是在 CI 里同时保留 2.13 和 3.3 两条编译线，让每次提交都自动回答一个问题：新代码有没有把旧兼容性破坏掉。这个做法成本不高，但对迁移期特别有效。
# CI 双版本编译：2.13 保证兼容，3.3 验证迁移进度 steps: - name: Scala 2.13 compatibility run: sbt ++2.13.10 compile - name: Scala 3.3 migration run: sbt ++3.3.4 compile++会让 sbt 临时切换 scalaVersion，先编 2.13 再编 3.3，这样你不用手动改 build.sbt 就能完成双版本验证。这条配置在迁移合入主分支后也能长期保留，只要两个版本都绿，后续迭代就不会悄悄把代码推回旧语法。
本地做分块迁移时，我会用模块标记文件控制顺序。下面这段脚本按依赖顺序编译模块，编译通过的模块留下标记，之后的失败只看当前模块，不会把上一模块的几百个错误重新翻出来。
#!/usr/bin/env bash set -euo pipefail # 依赖顺序：被依赖最多的基础模块先切 for module in core service api; do marker="modules/$module/.scala3-ok" if [ -f "$marker" ]; then echo "skip $module" continue fi echo "compile $module under Scala 3" sbt "project $module" clean compile touch "$marker" done这套标记脚本只适合本地排查，不适合当作 CI 的正式状态。因为 CI 每次从干净目录跑，标记不存在，所有模块都会编译，这反而是好事。我自己的习惯是本地用标记文件快速定位，CI 用双版本编译守门，两者配合而不是互相替代。
迁移快结束的时候，有一件容易被忽略的事：把临时写的dependencyOverrides、旧版scalacOptions和过渡用的%依赖全部清理掉。升级的价值不在于“代码能在 Scala 3 下编过”，而在于团队以后不用再记两套写法。我上次接类似任务，最大错误是想一口吃成胖子，把全部模块一次性切过去，日志几千行，根本没法定点。后来改成按依赖顺序一个模块一个模块切，再配合双编译和标记文件，反而几天就清完了。从那以后我养成了一个习惯：任何 Scala 升级，先保证两条路能同时跑通，再谈清理。希望帮到你。
本文还有配套的精品资源，点击获取
