1. 先把“跑不起来”的根源找准1.1 一个本地作业卡住半天的真实场景很多人第一次在 IDEA 里新建一个 Spark 工程写两三行WordCount点绿色三角控制台立刻变成一片红色报错。报错内容五花八门NoClassDefFoundError、NoSuchMethodError、ClassNotFoundException: scala.Product$class、Failed to locate the winutils binary、java.lang.reflect.InaccessibleObjectException。我见过一位 A 同学前后折腾两天最后发现问题只是 Scala 二进制版本写成了 2.13而手上的 Spark 包是按 2.12 编译的。这类问题的共性是它们几乎全部来自配置而不是代码。Spark 本身设计得足够抽象一个作业能在集群上跑靠的是master、依赖、序列化、内存这几层参数互相配合在 IDEA 里做本地开发等于把这几层参数从“由集群统一提供”变成“由你自己在运行配置里拼出来”。拼对了一次就永远顺拼不对代码写得再漂亮也起不来。这一篇讲的就是“拼”这件事Spark 在 IDEA 中那些必须配、值得配、配错会很痛苦的项。适合三类人看——刚接触 Spark 想在本机跑通第一个作业的初学者平时靠命令行spark-submit提交、希望本地也能高效调试的工程师以及团队里负责统一开发环境、想让新同学半天内上手的同学。你不需要预先精通 Scala但至少要能看懂pom.xml知道main方法在哪。1.2 把配置分成四层问题就不会乱我习惯把 IDEA 里的 Spark 配置拆成四层出问题时按层排查命中率远比漫无目的地改参数高。层级管什么出问题时的典型症状环境层JDK 版本、Scala SDK、IDEA 插件、系统环境变量编译不过、Unsupported class file major version依赖层Maven/SBT 坐标、provided作用域、Hadoop 版本冲突NoSuchMethodError、ClassNotFoundException运行层Run Configuration 的 VM options、程序参数、工作目录、类路径策略本地启动即退出、master为local[N]却连了集群调试层日志级别、临时目录、序列化方式、断点与远程调试日志刷屏看不到结果、断点不生效、结果写不出来这四层是串行依赖的环境层不对依赖层根本下载不完整依赖层有冲突运行层参数调得再细也没用。因此实际操作顺序一定是从上往下不要跳。提醒不要一上来就去调spark.executor.memory这类集群参数。本地模式下 executor 和 driver 是同一个 JVM这些参数基本不生效调了只会给自己制造“我改过了但没用”的错觉。2. 环境层JDK 与 Scala 版本必须一开始就定死2.1 JDK 选择的取舍逻辑Spark 3.3 之后对 JDK 17 提供了正式支持但需要额外开放一批 JDK 内部模块否则java.lang.reflect.InaccessibleObjectException会在启动阶段直接把你拦住。Spark 2.4 及更早的版本基本只能在 JDK 8 上工作。所以选 JDK 的第一原则是跟着 Spark 版本走而不是跟着“我机器上装了什么”走。我的建议是Spark 3.3 及以上用 JDK 11 最省事JDK 17 也可以但要额外配--add-opens参数。Spark 3.0 到 3.2JDK 8 或 11别碰 17。Spark 2.x老老实实 JDK 8。在 IDEA 里同时存在多个 JDK 是常态所以要在两个地方分别指定File → Project Structure → Project里的 Project SDK以及Modules里每个模块的 Language Level。前者决定用什么 JDK 编译后者决定生成的字节码版本。如果 Language Level 设成 17 而运行时 JDK 是 11会出现编译通过、运行报Unsupported class file major version的情况。这类问题最气人因为编译阶段完全不提示。在 Maven 里我更倾向于把编译版本锁死避免依赖 IDEA 界面设置properties maven.compiler.source11/maven.compiler.source maven.compiler.target11/maven.compiler.target scala.version2.12.18/scala.version scala.binary.version2.12/scala.binary.version spark.version3.5.1/spark.version /properties写死的好处是换机器、换同事、换 CI 环境编译产物一致不会出现“我这儿能跑你那儿不能跑”。2.2 Scala 二进制版本是隐藏地雷Spark 发布包是按 Scala 二进制版本编译的spark-core_2.12和spark-core_2.13是两个完全不同的坐标。很多人pom.xml里写的是_2.12但 IDEA 的 Global Libraries 里挂的 Scala SDK 是 2.13于是编译期就报一堆missing or invalid dependency detected或者勉强编译过了运行时报NoSuchMethodError: scala.Predef$.refArrayOps。处理方式很直接先确定 Spark 版本对应的 Scala 二进制版本再让三处保持一致——pom.xml里的scala.binary.version、IDEA 模块依赖里的 Scala SDK、以及你本地scalac的版本。Spark 版本默认 Scala 二进制版本备注2.4.x2.11老项目常见新项目别选3.0 - 3.22.12稳定生态资料最多3.3 - 3.52.12默认/ 2.13可选选 2.13 需确认所有第三方库都支持这里有个细节值得说清楚Scala 的小版本号2.12.15、2.12.18之间是二进制兼容的但大版本2.12 与 2.13之间不兼容。所以项目里写scala.binary.version是 2.12Scala SDK 用哪个 2.12.x 都行但绝对不能升到 2.13。我通常会在 README 里用一行字标注这一条能省掉新人半天时间。2.3 IDEA 侧的几个开关安装 Scala 插件这一步大家都知道但插件版本和 IDEA 版本的匹配常被忽略。IDEA 大版本升级后旧 Scala 插件可能让索引一直转圈、代码高亮失效。表现为能编译、能运行但代码全是红色波浪线提示找不到SparkSession。这种“假报错”会让人怀疑依赖没下全。遇到这类情况先看Settings → Plugins里 Scala 插件是否与当前 IDEA 版本匹配再去Build → Build Tools → Maven → Importing确认 JDK for importer 指向的是同一个 JDK。导入用的 JDK 和运行时 JDK 不一致索引出来的符号信息就会错位。另外两个值得开的设置Settings → Build, Execution, Deployment → Compiler → Scala Compiler把增量编译打开并确认Target bytecode version与前面 Maven 设置一致。Settings → Editor → General → Auto Import把 Scala 的自动导入打开勾选“Add unambiguous imports on the fly”写代码时省不少手。3. 依赖层把provided玩明白3.1 为什么 Spark 依赖要打provided几乎所有标准 Spark 工程的pom.xml里spark-core和spark-sql的作用域都是provided。原因不复杂集群上的 Spark 运行环境已经带了这些 jar你再打一份进 fat jar轻则包体积从几十兆涨到两百多兆重则因为版本错位触发奇怪的类加载问题。但provided在 IDEA 里有个副作用运行本地main方法时IDEA 默认不把provided作用域的依赖放进类路径于是SparkSession直接ClassNotFoundException。这个坑几乎所有新手都会踩而且报错信息极具误导性——明明依赖在External Libraries里躺着就是找不到。两种解法我推荐第一种在 Run Configuration 的Modify options里勾选Add dependencies with provided scope to classpath。这样不改pom.xml只在本地运行配置层面生效提交到集群时行为不变干净。把provided去掉。缺点是每次mvn package都会把 Spark 全量打进去包肥大而且和集群版本不一致时更危险。关于打包还要提醒一句如果用maven-shade-plugin或maven-assembly-plugin记得把provided范围的依赖排除在外否则前面省下的功夫又还回去了。3.2 一份可直接抄的依赖清单下面这份是我常用的最小可用配置Scala 2.12 Spark 3.5.1 JDK 11dependencies dependency groupIdorg.apache.spark/groupId artifactIdspark-core_${scala.binary.version}/artifactId version${spark.version}/version scopeprovided/scope /dependency dependency groupIdorg.apache.spark/groupId artifactIdspark-sql_${scala.binary.version}/artifactId version${spark.version}/version scopeprovided/scope /dependency dependency groupIdorg.scala-lang/groupId artifactIdscala-library/artifactId version${scala.version}/version /dependency dependency groupIdorg.apache.logging.log4j/groupId artifactIdlog4j-slf4j2-impl/artifactId version2.20.0/version scoperuntime/scope /dependency /dependencies几个点的用意说明一下scala-library不加provided因为它是你代码直接依赖的运行时也需要。日志实现要显式加而且版本要与 Spark 内部使用的 log4j2 版本接近。Spark 3.3 之后从 log4j1 迁移到了 log4j2如果你还在src/main/resources放log4j.properties会发现完全不起作用——因为 log4j2 读的是log4j2.properties或log4j2.xml。这个细节网上一堆旧文章还在传log4j.properties照着抄必然踩坑。不要画蛇添足地加hadoop-client。Spark 的依赖树里已经带了 Hadoop 客户端你再显式引一个不同版本的NoSuchMethodError: org.apache.hadoop.conf.Configuration.getTrimmed这类问题就来了。3.3 版本冲突怎么定位依赖冲突在 Spark 项目里极其常见尤其是公司内部还有一套公共依赖的时候。我排查的标准动作是跑一条命令mvn dependency:tree -Dincludesorg.apache.hadoop,org.apache.spark,org.scala-lang输出里如果同一个 artifact 出现两个版本就要在pom.xml里用dependencyManagement或exclusions收敛到 Spark 自带的那个版本。判断“该收敛到哪个”的依据是以 Spark 官方发布的那个版本的依赖树为准因为集群上的运行环境就是按它来的。如果冲突发生在第三方库身上比如某个 JSON 库被两个组件以不同版本引入我一般会先看mvn dependency:tree -Dverbose里的omitted for conflict提示再决定exclusion加在谁身上。加exclusion的原则是“加在引入方不加在被引入方”这样影响面最小。3.4 SBT 用户的等价写法用 SBT 的话逻辑一样只是语法不同ThisBuild / scalaVersion : 2.12.18 val sparkVersion 3.5.1 libraryDependencies Seq( org.apache.spark %% spark-core % sparkVersion % Provided, org.apache.spark %% spark-sql % sparkVersion % Provided, org.apache.logging.log4j % log4j-slf4j2-impl % 2.20.0 % Runtime )注意%%会自动补上 Scala 二进制版本后缀所以不需要手写_2.12。这也是 SBT 相对 Maven 更不容易出错的地方。不过 SBT 的项目导入 IDEA 时索引更慢如果团队里没有硬性要求我一般还是用 Maven省心。4. 运行层Run Configuration 里的关键几项4.1 VM options内存与 JDK 模块开放本地运行时driver 就是你的main方法所在 JVM所以堆内存由-Xmx控制而不是spark.driver.memory后者在local模式下不会重新拉起 JVM很多时候不生效。给一个我常用的模板适用于 16G 内存、8 核的开发机-Xmx4g -XX:ReservedCodeCacheSize512m -XX:UseG1GC -Dspark.masterlocal[4] -Dspark.sql.shuffle.partitions8参数是怎么定的-Xmx4g本地处理几十万到几百万行数据足够。设太大反而让 GC 停顿变长因为对象存活多了设太小比如 1g跑 join 或者collect大结果集时容易 OOM。local[4]本机 8 核留一半给系统和 IDEA 自身的索引进程。用local[*]会占满所有核IDEA 会卡到无法输入。spark.sql.shuffle.partitions8默认是 200本地跑小数据时会产生 200 个极小任务调度开销远大于计算本身。改成核数的 2 倍左右比较合适这一条对本地跑得快慢的影响非常明显。-XX:ReservedCodeCacheSize512mSpark 大量使用动态生成代码Whole-Stage CodeGen、Kryo 序列化器生成代码缓存不够会看到CodeCache is full警告之后性能断崖式下降。如果用的是 JDK 17还要在 VM options 里补上模块开放参数否则启动阶段就会抛异常--add-opensjava.base/java.langALL-UNNAMED --add-opensjava.base/java.lang.invokeALL-UNNAMED --add-opensjava.base/java.nioALL-UNNAMED --add-opensjava.base/sun.nio.chALL-UNNAMED --add-opensjava.base/java.utilALL-UNNAMED这一串看着吓人但都是 Spark 内部反射访问 JDK 内部 API 所必需的。少一条就可能在某个特定算子上崩而崩的位置往往和这条参数毫无关系排查起来非常费劲。我通常把它做成一个模板配置新项目直接复制。4.2 程序参数与 master 的传法master到底写在代码里还是通过参数传我的做法是永远从参数读代码里给默认值。object WordCountApp { def main(args: Array[String]): Unit { val master if (args.nonEmpty) args(0) else local[4] val spark SparkSession.builder() .appName(word-count-local) .master(master) .config(spark.sql.shuffle.partitions, 8) .getOrCreate() // 业务逻辑 spark.stop() } }这样 Run Configuration 里的Program arguments填local[4]本地调试用打包后spark-submit时不传或传yarn走集群。同一份代码两种用法不用改一行。有人在代码里硬写setMaster(local[*])结果是这个 jar 提交到集群后仍然尝试以本地模式跑资源申请永远失败报错还很不直观。这个坏习惯一定要在早期改掉。Program arguments这一栏还有个用途是传业务参数比如输入路径、输出路径、日期分区。我的习惯是把参数解析写得足够宽容——检查数量、给默认值、打印实际生效值避免本地和集群参数不一致导致跑出来的结果对不上。4.3 Working directory 与类路径策略Working directory默认是模块根目录。这个设置直接影响相对路径的解析。比如你代码里写spark.read.text(data/input.txt)本地跑的时候找的是模块根目录下的data/input.txt。如果你在 Run Configuration 里把工作目录改成了$MODULE_DIR$/src/main/resources这个相对路径就失效了报Path does not exist。我的做法是统一把工作目录设为$MODULE_DIR$所有测试数据放在模块根目录的data/下代码里用相对路径团队里其他人拉下来就能直接跑。测试数据不要太大几十兆以内超过就放本地对象存储或者直接生成。另一个容易忽视的是Shorten command line。Windows 下类路径太长会超过命令行长度限制表现为启动直接失败报CreateProcess error206。解决办法是在 Run Configuration 顶部Modify options里把Shorten command line设为JAR manifest或argfile。这个选项在依赖多的时候几乎是必开的。还有一个坑是 Windows 上的winutils.exe和HADOOP_HOME。Spark 在本地写文件时会调用 Hadoop 的本地文件系统实现Windows 上缺这个二进制文件会报java.io.IOException: Could not locate executable null\bin\winutils.exe。处理方式是在系统环境变量里配好HADOOP_HOME指向一个包含bin/winutils.exe的目录并在 IDEA 的 Run Configuration 环境变量里确认能读到。如果实在不想折腾改用 WSL 或者直接用 Linux 环境开发一劳永逸。5. 调试层日志、临时目录与断点5.1 日志收敛别让控制台被刷屏Spark 默认的 INFO 日志量大得离谱一次count()能刷几百行。本地调试时几乎没法看结果。收敛方式取决于 Spark 版本Spark 3.3 及以上在src/main/resources放log4j2.propertiesrootLogger.level warn rootLogger.appenderRef.stdout.ref console appender.console.type Console appender.console.name console appender.console.target SYSTEM_OUT appender.console.layout.type PatternLayout appender.console.layout.pattern %d{HH:mm:ss} %-5p %c{1} - %m%n logger.spark.name org.apache.spark logger.spark.level warnSpark 3.2 及以下放log4j.propertieslog4j.rootCategoryWARN, console log4j.appender.consoleorg.apache.log4j.ConsoleAppender log4j.appender.console.targetSystem.out log4j.appender.console.layoutorg.apache.log4j.PatternLayout log4j.appender.console.layout.ConversionPattern%d{HH:mm:ss} %p %c{1}: %m%n放错文件名是极高频的错误症状是“配置了但日志一点没变”。判断方法很简单看控制台里日志的格式如果带log4j2或者格式带%-5p这类样式说明是 log4j2 生效了。如果想临时把某个包的日志调到 DEBUG比如排查序列化问题我会用代码方式动态改import org.apache.logging.log4j.core.config.Configurator Configurator.setLevel(org.apache.spark.serializer, org.apache.logging.log4j.Level.DEBUG)这比每次改配置文件重启更灵活。5.2 本地临时目录与 warehouse 的位置本地跑带 SQL 的作业会在工作目录下生成spark-warehouse和metastore_db。如果反复跑不同版本的代码metastore_db里的表定义可能和当前代码对不上报一些莫名其妙的表不存在或者 schema 不匹配。我一般会在 VM options 里显式指定-Dspark.sql.warehouse.dir/tmp/spark-warehouse-dev -Dspark.local.dir/tmp/spark-local指向固定的临时目录好处是清理方便不会污染项目目录也不会误提交到版本库。注意加上.gitignore里的spark-warehouse/、metastore_db/、derby.log这几个文件经常被新手不小心提交上去。spark.local.dir控制的是 shuffle spill 和临时文件的落盘位置。本地磁盘空间紧张时可以指向空间更大的盘。这个参数在本地模式下生效比在集群上调更有意义。5.3 断点调试的几个实操细节IDEA 里打断点调 Spark 作业最常见的困惑是“断点打在 RDD 的 map 里结果它不在主线程停下”。原因在于local[N]模式下N 1时任务会跑在Executor task launch worker线程上和main线程不是一个。IDEA 默认的断点挂起策略是All理论上应该能停但如果你的断点打在闭包内部且该闭包被序列化后在新线程执行有时需要把挂起策略改成Thread。更简单粗暴的办法是调试期间临时改成local[1]所有任务在单个线程上顺序执行断点行为最可预测。定位完逻辑再改回local[4]。我调复杂算子链的时候基本都这么干。还有一个技巧是用foreachPartition里打日志而不是打断点。Spark 的闭包在分布式环境下断点行为本来就不稳定本地模式下虽然可用但会打乱任务调度时序有时候会让本该复现的并发问题消失。日志更可靠。6. 高频故障与速查表6.1 依赖类问题的判断顺序碰到NoSuchMethodError和ClassNotFoundException我按这个顺序看先看报错里提到的类名和方法名反查是哪个 jar 提供的。跑mvn dependency:tree看这个 jar 有几个版本。如果是 Spark 自己的类找不到先确认provided依赖有没有加进类路径第 3.1 节的勾选项。如果是 JDK 内部类找不到看 JDK 版本是否与 Spark 版本匹配。如果是 Scala 相关类报错回去核对 Scala 二进制版本。一个典型的例子java.lang.NoSuchMethodError: org.apache.spark.sql.SparkSession.builder报错很唬人实际问题往往是spark-sql的 jar 版本是 2.x 而代码按 3.x 写的方法签名对不上。或者反过来spark-core2.12 与spark-sql2.13 混搭类加载时找不到对方。6.2 内存与序列化类问题本地 OOM 和集群 OOM 的成因不一样。本地 OOM 很多时候不是数据真的多而是这几种情况collect()把整个数据集拉到 driver。本地 driver 和你写代码的 JVM 是同一个堆再大也有限。调试阶段改用take(20)或者show()。广播变量太大。默认广播阈值 10MB超过后仍然会广播只是方式不同几百 MB 的广播在本地很容易撑爆。-Xmx设太小或者没设默认是物理内存的 1/4看起来很大但和 IDEA 自身的索引进程抢内存。序列化方式默认是 Java 序列化体积大速度慢。换成 Kryo 并注册类效果立竿见影spark.conf.set(spark.serializer, org.apache.spark.serializer.KryoSerializer) spark.conf.set(spark.kryo.registrationRequired, false)先用false跑通稳定后再考虑打开强制注册避免上线才发现有类没注册。6.3 常见问题速查现象大概率原因处理动作ClassNotFoundException: SparkSessionprovided依赖没进类路径Run Configuration 勾选 add-dependencies-with-provided-scopeUnsupported class file major version 61编译 JDK 高于运行 JDK统一 Project SDK 与 Language LevelNoSuchMethodError: scala.Predef$...Scala 二进制版本不一致检查_2.12/_2.13后缀与 SDKCould not locate executable null\bin\winutils.exeWindows 缺 Hadoop 本地二进制配HADOOP_HOME或换 Linux/WSLCodeCache is full动态生成代码过多加-XX:ReservedCodeCacheSize512mInaccessibleObjectExceptionJDK 17 模块限制补--add-opens系列参数CreateProcess error206命令行过长Shorten command line 设为 JAR manifest日志配置不生效log4j 文件名与版本不匹配3.3 用log4j2.properties表结构对不上metastore_db残留旧状态删除metastore_db与spark-warehouse重跑本地跑得极慢shuffle 分区数仍为 200设spark.sql.shuffle.partitions87. 提效配置把重复动作变成模板7.1 实时模板与代码片段Spark 工程的入口代码高度模板化每次都手写SparkSession.builder()一串很浪费。IDEA 的 Live Template 可以解决。Settings → Editor → Live Templates新建一个 Scala 分组定义一个缩写比如sparkinitval spark SparkSession.builder() .appName($APP_NAME$) .master(local[4]) .config(spark.sql.shuffle.partitions, 8) .getOrCreate() import spark.implicits._配合SparkSession的import spark.implicits._这行特别容易漏漏了之后toDF()直接编译不过报错信息还不太好懂。模板里带上就不会忘。同理可以定义rddcount、readparquet、stop几个常用片段。这套东西做一次后面每个新文件都受益。7.2 编译与索引的取舍Scala 编译慢是公认的IDEA 里尤其明显。几个能明显改善的设置打开Settings → Build, Execution, Deployment → Compiler里的Build project automatically但把 Scala 的增量编译依赖关系交给 sbt/Maven 管理不要让 IDEA 自己反复全量编译。排除不参与编译的目录。测试数据目录、日志输出目录一定要 Mark as Excluded否则 IDEA 会去索引它们大文件一多索引卡得人怀疑人生。关闭不必要的检查。Settings → Editor → Inspections里把 Scala 的部分风格检查关掉只留编译错误级别的提示。满屏黄线不影响功能但会影响你找真正的问题。一个容易被忽略的点IDEA 运行配置里有个Build步骤默认会在启动前编译整个模块。工程大了之后每次点绿三角要等一两分钟。我通常把同一份配置复制一份把Before launch里的 Build 去掉用于“代码没改、只想重跑”的场景。7.3 团队统一的配置约定如果是多人协作建议把运行配置导出成可共享的形式Run Configuration右上角勾选Store as project file配置会落到.idea/runConfigurations/目录下可以随项目一起提交。这样新同学 check out 下来直接就有现成的本地运行配置不用自己摸索。配套要在 README 里写清楚三件事JDK 版本、Scala 二进制版本、Spark 版本。这三行信息能挡掉新同学 80% 的环境问题。再加一条“运行前先勾选 add-dependencies-with-provided-scope”基本就齐了。.gitignore里别忘了这几个target/ .idea/workspace.xml spark-warehouse/ metastore_db/ derby.logworkspace.xml提交上去会造成频繁冲突这个是老生常谈但还是经常见到有人提交。8. 我自己踩过的几个坑最后说几个纯经验性的东西属于文档里不会写、但实际开发中迟早会遇到的情况。第一个不要在object里放可变全局状态。本地调试时同一个 JVM 里反复运行object的单例状态会保留下来导致第二次跑结果和第一次不一样。集群上每个 executor 是独立 JVM问题不明显本地能把你折腾到怀疑人生。表现是“第一次跑对了第二次跑数据翻倍”。遇到这种先检查有没有object里的var集合。第二个spark.stop()别忘了但别乱加。在main结尾加spark.stop()是好习惯能释放端口和线程。但如果你的代码是被别的框架调用的提前 stop 会把共享的 SparkContext 一起关掉。本地调试时更常见的坑是加了stop()之后后面的代码再去用spark就报SparkContext has been stopped而报错位置离stop()有几十行很难联想到一起。第三个测试数据用小文件但别只用小文件。本地拿 100 行数据调通的逻辑上集群跑 1 亿行可能因为数据倾斜、分区不合理直接崩。我的做法是本地测试用几万行再故意造一点倾斜数据比如某个 key 占 90%本地就能把大部分倾斜问题提前暴露比上集群再调便宜得多。第四个改完配置记得重启 JVM。IDEA 的 VM options 改动需要重启运行配置才生效但 IDEA 有时候会复用之前的 JVM 进程。改了参数发现“怎么没变化”先点一次Stop确保进程真的退出了再重跑。这个坑我踩过不止一次白白浪费时间。第五个别在本地纠结性能。本地模式的调度、序列化、网络开销和集群完全不同本地跑 30 秒的作业在集群上可能 10 秒也可能 10 分钟。本地只用来验证逻辑正确性性能调优一定放到真实集群上做。把这两件事混在一起很容易在本地调一些根本不影响线上结果的参数。