1. 为什么要在IDEA里折腾Spark配置很多人第一次跑Spark程序是把代码写完之后打成jar包扔到集群上提交等日志刷半天出错了再改再打再传。这套流程在调试阶段非常折磨人因为一个断点、一次变量打印都做不了。后来大家发现在IDEA里本地跑Spark才是最舒服的调试方式能断点、能看变量、能单步跟进去看Dataset的物理计划效率完全不在一个量级。但本地跑Spark这件事看起来只是新建一个Maven工程、加几个依赖、写个main方法真动手就会撞上一堆问题控制台被INFO日志刷屏真正想看的那一行结果淹没在几百行输出里跑到一半报序列化错误栈里全是模糊的类名命令行明明能跑的代码在IDEA里就是报找不到主类改一行代码要等半分钟因为每次都完整初始化一遍SparkContext。这篇内容就是把这些年在IDEA里配置和调试Spark程序时需要处理的事情捋清楚。我把它定位成一份配置备忘 踩坑记录适合已经能写出WordCount但在本地运行环节总是别扭的读者也适合刚接手Spark项目、需要快速把本地开发环境调通的同学。全文围绕IDEA这个开发环境讲清楚依赖怎么选、参数怎么配、日志怎么压、调试怎么跑、内存和序列化问题怎么定位不对集群侧的部署展开。在开始之前先明确一点本地模式跑Spark和集群模式跑Spark面向的目标不一样。本地模式的价值是快速验证逻辑和排查业务代码问题不是验证性能。所以配置的思路应该是够用、少干扰、启动快而不是把集群上那套参数原样搬过来。后面涉及的所有取舍都基于这个前提。2. 工程骨架与依赖选择从建项目这一步就要做对2.1 构建工具与项目结构的取舍新建工程时我基本只用Maven不用Gradle理由很实际大部分Spark项目的示例、依赖坐标、打包脚本都是围绕Maven写的遇到问题时搜到的答案也大多是pom片段。用Gradle当然也能跑但你会额外花时间在依赖解析差异上对调试Spark本身没有帮助。创建时选普通Maven工程不要选Spring Boot脚手架。这一点很多人栽过用Spring Boot脚手架生成的项目父POM里锁定了某些库版本和Spark依赖里的Jackson、Netty、Guava版本冲突报错信息通常长成NoSuchMethodError或者ClassNotFoundException很难一眼看出是版本打架。工程结构上我习惯这样分spark-local-demo ├── pom.xml └── src ├── main │ ├── java │ │ └── com/example/spark │ │ ├── core // RDD 相关实验 │ │ ├── sql // DataFrame / SQL 实验 │ │ └── util // 工具类上下文创建、日志配置 │ └── resources │ ├── log4j2.properties │ └── data // 本地小样本数据 └── test └── java把本地样本数据放在resources/data下读的时候用getClass().getClassLoader().getResource(data/xxx.csv).getPath()拿路径。这样换机器、换目录都不用改代码比写死绝对路径省事。踩过的坑是路径里带空格或中文getPath()返回的字符串直接传给SparkSession.read会出问题稳妥做法是转成URI再取path或者干脆用Paths.get(...).toUri().toString()。2.2 Spark依赖的范围怎么定依赖这块核心就三条Spark核心包、Spark SQL包、以及日志实现。至于Hadoop相关依赖本地跑一般让Spark自带的传递依赖解决不要手动去引入一大堆hadoop-*容易把版本搞乱。properties maven.compiler.source8/maven.compiler.source maven.compiler.target8/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding spark.version3.3.2/spark.version scala.binary.version2.12/scala.binary.version /properties dependencies 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 /dependencies这里有个关键选择scope写不写provided。如果这个工程最终要打成jar提交到集群写provided是对的——集群上已经有Spark的jar打进去反而可能冲突。但在IDEA里本地运行provided范围的依赖默认不在运行classpath里直接Run main方法会报NoClassDefFoundError: org/apache/spark/SparkConf。解决方式有两种我更推荐第二种把provided去掉依赖变成默认的compile本地能跑但打包体积变大保留provided在IDEA的运行配置里勾选Include dependencies with Provided scope。这个开关在Run/Debug Configurations的Modify options里找勾上之后本地运行就正常了打包也不会臃肿。我选择第二种的原因是它能同时满足本地能跑和打包干净两个需求一次配置长期有效。如果团队里有人用IDEA、有人用Eclipse就需要注意这个勾选是IDEA特有的别人本地跑不起来时先问一句你勾了provided scope吗。2.3 Scala版本与Java版本的对应关系Spark 3.x 默认编译在Scala 2.12上Spark 3.2之后也可以选2.13。这里最容易错的地方是artifactId后缀写错比如你项目里用的是Scala 2.13的语法或依赖却引了spark-core_2.12IDE里可能不报错但运行时会抛NoSuchMethodError或者IncompatibleClassChangeError。另外一个坑是编译器的Scala插件版本。如果工程里有Scala代码需要装Scala插件并保证插件版本与项目Scala版本匹配。纯Java工程不装Scala插件也能跑Spark因为Spark的API都有Java版本这一点很多人不知道白白装了插件又配不对。还有个JDK版本问题需要注意Spark 3.3起对JDK 17的支持是实验性的Spark 3.5对JDK 17的支持才好一些。JDK 8是最稳的JDK 11基本没问题。如果你本地是新装的JDK 21跑Spark会遇到一堆反射相关的IllegalAccessError报错信息里会出现module java.base does not opens java.lang这类提示。遇到这个不要急着改代码先把运行时的JDK调成8或11问题基本就消失了。2.4 编码与编译参数被忽视的中文乱码来源中文环境下控制台输出乱码是高频问题。稳妥配置是project.build.sourceEncoding设为UTF-8IDEA的File Encodings里把Global、Project、Properties都设成UTF-8运行配置的VM options加-Dfile.encodingUTF-8。三处都对齐之后中文才稳定不乱。只改一处往往在某个环节还是会出问题比如读CSV时列名是乱码或者show()输出的中文变成了问号。我之前排查过一个很隐蔽的场景代码里字符串是UTF-8但VM启动参数继承了系统的GBK导致写入文件时编码不一致读回来做groupBy发现分组数量比预期多——因为同名中文被分成了两种字节序列。这种问题不看编码根本想不到。3. 本地运行参数把SparkConf和SparkSession配明白3.1 master与并行度的设置逻辑本地模式下master的写法有三种区别值得说清楚写法含义适用场景local单线程所有任务串行需要看清晰执行顺序、调试逻辑local[4]4个线程模拟并行需要观察shuffle、并发行为local[*]用满机器所有核快速跑完不关心并发细节我的习惯是默认用local[2]或者local[4]不用local[*]。原因是调试阶段机器上还开着IDE、浏览器、各种后台服务local[*]会把CPU吃满风扇狂转IDE卡顿反而不舒服。更重要的是用固定线程数能复现并发相关的问题比如共享变量更新顺序、累加器的行为local[*]在不同机器上线程数不同问题有时出现有时不出现很难定位。代码里这样写SparkConf conf new SparkConf() .setMaster(local[2]) .setAppName(spark-local-debug) .set(spark.ui.enabled, false) .set(spark.sql.shuffle.partitions, 4) .set(spark.serializer, org.apache.spark.serializer.KryoSerializer); SparkSession spark SparkSession.builder().config(conf).getOrCreate();几个参数说明一下为什么这么设spark.ui.enabledfalse本地调试不需要Web UI关掉能省一个端口占用也少一些启动日志。如果这次调试要看执行计划的可视化再临时打开。spark.sql.shuffle.partitions4默认值是200本地处理几百行数据时200个分区会产生大量空任务每次shuffle都要等调度慢得莫名其妙。改成4或者8groupBy、join这些操作会明显变快。这是个典型的集群默认值不适合本地的例子。spark.serializer用Kryo比Java序列化快而且在本地调试时如果对象不可序列化Kryo的报错信息通常比Java序列化更容易定位到具体字段。再说getOrCreate()。在单元测试或者一个main方法里连续做多个实验时如果每次都new SparkSession会有多个上下文共存的问题Spark 3.x里直接抛异常。用getOrCreate()能复用但要注意它会把旧配置沿用下来改配置不生效。稳妥的做法是在实验之间调用spark.stop()或者干脆一个实验一个main方法、一个测试类一个上下文。3.2 内存给的太少会怎样本地模式默认的driver内存是1g看起来够用但如果你在driver端做collect()把大结果拉回来或者用createDataFrame造了一批不小的测试数据很容易OOM。报错信息是java.lang.OutOfMemoryError: Java heap space。VM options里加-Xms512m -Xmx2g -XX:UseG1GC-Xmx2g对绝大多数本地调试够用。注意这里调整的是driver内存本地模式下driver和executor在同一个进程不是spark.executor.memory——本地模式设executor内存基本没意义因为根本没有独立的executor进程。一个容易混淆的点spark.driver.memory这个配置在本地模式下也不起作用真正生效的是JVM启动参数。这个坑我踩过在代码里set(spark.driver.memory, 4g)然后发现还是OOM因为JVM的堆在进程启动时就定了。3.3 仓库与元数据目录的清理本地跑Spark SQL默认会在工作目录下生成spark-warehouse和metastore_db目录有时候还有derby.log。这些文件带来的麻烦有两个一是换分支或者换表结构时旧的metastore信息还在导致建表报already exists二是derby.log会随着运行越来越胖甚至在某些情况下锁住数据库导致第二次启动失败。处理方式是在配置里明确指定目录并且放在临时路径下.set(spark.sql.warehouse.dir, System.getProperty(java.io.tmpdir) /spark-warehouse) .set(spark.driver.extraJavaOptions, -Dderby.system.home System.getProperty(java.io.tmpdir))或者更干脆在测试开始前用脚本清掉这几个目录。我的习惯是把它写进一个BeforeAll里或者直接在IDE的Run配置里配一个启动前执行的脚本。总之不要让这些产物散落在项目根目录不然git status里会一直挂着一堆没意义的文件。4. 日志治理让控制台只显示你关心的东西4.1 满屏INFO的根源初次本地跑Spark控制台会被这类日志淹没22/06/01 10:12:33 INFO SparkContext: Running Spark version 3.3.2 22/06/01 10:12:33 INFO Utils: Successfully started service sparkDriver on port 41234. ...这些是Spark内部组件的INFO级别日志。它们是正常运作信息但在调试业务逻辑时毫无价值反而会让你找不到自己打的那行System.out.println。很多文章给的方案是在代码里加spark.sparkContext().setLogLevel(WARN)。这个方案能用但有两个局限一是只对Spark内部日志有效对Hadoop、Netty这些第三方库的日志不生效二是必须在SparkSession创建之后才能调用之前的启动日志已经刷出去了。4.2 用log4j2配置文件彻底压制更彻底的做法是在resources下放一个log4j2.properties让它在类加载时就生效status warn name SparkLocalLogConfig rootLogger.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} %-5level %c{1.} - %msg%n logger.spark.name org.apache.spark logger.spark.level warn logger.hadoop.name org.apache.hadoop logger.hadoop.level error logger.netty.name io.netty logger.netty.level error logger.parquet.name org.apache.parquet logger.parquet.level error要点在于按包名分级。Spark主包给warnHadoop和Netty给errorParquet也给error——Parquet的日志特别吵读文件时会打一堆页索引信息。这里有个细节Spark 3.x自带log4j2的实现但你项目里如果没有显式声明log4j2的依赖有时会用默认配置配置文件不被读取。表现是配置写了、格式没变。解决办法是在pom里显式引入dependency groupIdorg.apache.logging.log4j/groupId artifactIdlog4j-slf4j-impl/artifactId version2.17.2/version scopetest/scope /dependencytest范围是为了打包时不带进去Spark集群上自己会提供日志实现。4.3 只保留自己代码的输出调试时我最常用的一个技巧是把root logger打到warn然后把自己项目的包单独放开到info或debuglogger.mine.name com.example.spark logger.mine.level debug再加appender.console.layout.pattern里保留类名缩写%c{1.}这样控制台里属于自己代码的行会清楚地显示S.数据清洗 - ...这种格式一眼就能从噪音里挑出来。这个配置我在好几个项目里都留了一份改包名就行很省事。另外提醒一句System.out.println在生产代码里不推荐但在本地调试里其实很好用因为日志框架的输出会被格式和过滤影响而println的输出永远原样出现。只是想快速看一个变量用println比配日志快。5. 断点调试与执行计划观察5.1 在IDEA里打断点的可行边界Spark的代码分两块driver端的代码构建DataFrame、调用collect、show和executor端的代码map、filter里的闭包。本地模式下两者在同一个JVM里但这不意味着所有地方都能随便打断点。能在driver端打断点这是顺理成章的事DataFrame的构建、select、join这些链式调用的代码本身在driver上执行。也可以在collect()之后的循环里打断点看返回的数据。闭包里的代码要小心。比如DatasetRow result df.filter(col(amount).$greater(100));这里的$greater(100)只是个列表达式真正执行是在task里。在这种lambda里打断点IDEA有时能停下来但停下来之后用Step Over容易卡住甚至超时因为executor线程的调度和driver不同步。我的经验是在闭包里打断点只看不步进即看一眼变量就Resume不要尝试单步。要单步跟逻辑把逻辑抽成普通方法在方法里用println或临时日志代替。5.2 用explain看物理计划的实际价值比断点更常用的排查手段是看执行计划result.explain(true);参数true会输出parsed、analyzed、optimized、physical四个阶段。本地调试时我最常看的是optimized和physical两段optimized里能看到谓词下推有没有生效。如果filter没有下推到读文件那一步说明格式或写法有问题后面加一个filter可能变成全量读取physical里能看到join策略是BroadcastHashJoin还是SortMergeJoin。小表没走broadcast通常是没加hint或者表大小统计不准。一个真实的调优经历本地处理一份几十万行的CSVjoin写得慢explain一看是SortMergeJoin——因为小表没被识别成小表本地读CSV没有统计信息。加了broadcast(smallDf)之后计划变成BroadcastHashJoin时间从十几秒降到两秒。这个验证必须本地做因为改一次代码跑一次只要几秒扔到集群上试太慢。5.3 数据质量问题的定位路径本地调试另一个高频场景是数据本身有问题。show()默认只显示20行且会截断长字符串看着没问题实际数据里有null、有异常值。我会在调试阶段加一段result.printSchema(); result.select( count(when(col(amount).isNull(), 1)).as(null_cnt), count(when(col(amount).$less(0), 1)).as(neg_cnt), countDistinct(col(id)).as(distinct_id), count(*).as(total) ).show();一次性把null数量、负值数量、去重数量、总量都看到。这一步能提前发现很多问题比如某个字段全是null读取时列名不匹配、某个id重复关联逻辑有误。这些检查在集群上做一次要等好久本地几十秒就能跑完。注意本地样本数据要刻意包含脏数据。只用一个规整的样本文件调试上线后大概率会翻车。我习惯准备两份一份干净的小文件用来验证业务逻辑一份带null、带异常值、带格式错误的文件用来验证容错分支。6. 序列化、版本冲突与那些反复出现的报错6.1 NotSerializableException的排查套路这个报错几乎人人都遇到完整信息通常是org.apache.spark.SparkException: Task not serializable Caused by: java.io.NotSerializableException: com.example.spark.SomeHelper排查顺序我总结成三步第一步看报错里指出的类。如果这个类是你自己写的工具类被某个lambda引用了那就是它没实现Serializable。要么加上implements Serializable要么把它变成static方法或者局部变量——闭包捕获外部类的实例引用是主因。第二步如果类名看着陌生但像某个第三方对象比如数据库连接、HTTP客户端、日志器说明你在闭包里用了不可序列化的对象。最常见的错误写法是在map里用一个共享的数据库连接或SimpleDateFormat。正确做法是每个分区的task自己创建用mapPartitions而不是map。第三步如果报错指向的是一个匿名内部类或者lambda那多半是lambda捕获了外部类this。比如在某个Service类的成员方法里写map(x - this.process(x))整个Service实例就被序列化了。改成static方法或者把用到的字段抽成局部变量。一个加速排查的技巧临时把序列化器换成Java序列化去掉spark.serializer那行Java序列化的报错信息更啰嗦但更具体会明确写出哪个字段不可序列化。定位到问题后再换回Kryo。6.2 Guava与Jackson的版本冲突这个坑的典型表现是代码里调了一个方法IDEA里编译通过运行时抛NoSuchMethodError。原因通常是Spark依赖了某个版本的Guava比如14.x而你引入的另一个库依赖了更高的版本比如30.xMaven的最近优先策略选择了高版本但Spark需要的是低版本里存在的方法签名。定位方法是在项目根目录执行mvn dependency:tree -Dincludescom.google.guava:guava看有几个版本谁引进来的。处理方式有两种一是把冲突的库排除掉dependency groupId某个引入方/groupId artifactId某个包/artifactId versionx.y.z/version exclusions exclusion groupIdcom.google.guava/groupId artifactIdguava/artifactId /exclusion /exclusions /dependency二是显式声明一个和Spark匹配的版本。我倾向于前者让Spark的依赖保持原样。Jackson的冲突同理NoClassDefFoundError指向com/fasterxml/jackson/databind/...时先去查依赖树。6.3 主类找不到与运行配置的细节本地Run时提示ClassNotFoundException或Error: Could not find or load main class通常是这几个原因输出目录没编译。Build Rebuild Project一下或者看target/classes下有没有对应的class文件运行配置里指定了错误的模块或类名用了provided范围但没勾选那个include选项前面提到过。另外一个隐蔽的问题是多模块工程里的依赖顺序。如果模块A依赖模块BB又依赖Spark在A里运行主类时有时会找不到Spark的类。处理办法是把Spark依赖在A的pom里也声明一次或者在运行配置里显式添加B的classpath。6.4 反复启动慢的优化思路每次改代码都要完整启动一次SparkSession大概要等几秒到十几秒。这个时间主要花在上下文初始化、服务端口绑定、元数据加载上。能优化的手段有限但有几点可以考虑关掉spark.ui.enabled省掉UI服务的启动把spark.sql.warehouse.dir指向临时目录避免每次扫描如果只是改业务逻辑、不改上下文配置把多个实验写在同一个main方法里共用一次上下文用测试框架时把SparkSession放在BeforeAll里创建、AfterAll里stop不要每个测试方法都建一次。需要注意的是共用上下文会让状态在实验之间残留比如临时视图、注册的UDF、改了默认配置。彻底干净的做法还是一个实验一个类这点要看具体情况取舍。我的折中是同一主题的几段实验共用一个上下文跨主题的分开。7. 联调阶段从本地到集群的配置切换7.1 用外部配置区分运行环境本地能跑之后下一步是提交到集群。如果到处写死local[2]和路径改起来很痛苦。我的做法是把环境差异抽到一个配置里spark.masterlocal[2] spark.ui.enabledfalse spark.sql.shuffle.partitions4然后在代码里读配置本地读application-local.properties集群通过提交参数覆盖。这样本地调试不用改代码打包时也不用动。更进一步可以把master从代码里彻底移除——用spark-submit提交时通过--master指定代码里不写setMaster。这样同一份代码在本地和集群都能用本地在IDE里手动指定集群由提交脚本管。这个做法有个前提代码里不能调用setMaster(local)否则会覆盖提交参数并告警。7.2 本地路径与HDFS路径的治理本地调试读写都是本地路径集群上是HDFS或者对象存储。这里最容易出的错是路径写死成/Users/xxx/data提交到集群直接找不到文件。处理思路定义一个路径解析的入口本地给本地路径集群给远端前缀。比如读取时统一用一个resolvePath(String relative)方法内部判断当前master。更简单的办法是在配置里写完整路径本地一份、集群一份。还有一类问题来自输出目录的覆盖行为。Spark默认不允许覆盖已存在的输出目录会抛AnalysisException: path already exists。本地反复调试时这个报错特别频繁。可以输出前先删目录或者用write.mode(overwrite)显式声明覆盖。要注意overwrite在测试里很方便但如果误用到生产表上代价很大。我的习惯是本地调试用overwrite生产代码里单独封装一个写入方法默认走append或者显式判断。7.3 打包时的依赖处理本地调好之后打包要注意provided那批依赖不会被打进去这是对的。但如果项目里用了UDF或者其他需要在集群上额外加载的类要确认它们在compile范围里。另外如果用shade插件处理依赖冲突注意重定位规则别把Spark自己的类也重定位了那会导致运行时报找不到类。一个实践建议本地调试能跑通后先在本地用local[4]跑一遍完整的端到端流程再打成jar。如果jar在集群上报类找不到先比对依赖树确认没有把集群已有的库重复打包进去。这类问题在本地往往看不出来因为本地Classpath和集群不一样。8. 一些值得长期保留的习惯配置8.1 一个可直接复用的上下文工具类把上下文创建收敛到一个工具类里避免每个main方法重复写一遍public final class LocalSpark { private LocalSpark() {} public static SparkSession create(String appName) { SparkConf conf new SparkConf() .setAppName(appName) .set(spark.ui.enabled, false) .set(spark.sql.shuffle.partitions, 4) .set(spark.serializer, org.apache.spark.serializer.KryoSerializer) .set(spark.sql.warehouse.dir, System.getProperty(java.io.tmpdir) /spark-warehouse); SparkSession spark SparkSession.builder().config(conf).getOrCreate(); spark.sparkContext().setLogLevel(WARN); return spark; } public static void close(SparkSession spark) { if (spark ! null) { spark.stop(); } } }注意这里没有setMaster本地运行时在IDE的Run配置或环境变量里补上。如果坚持在代码里指定可以读一个系统属性有则用、无则默认local[2]。代码里配上setLogLevel(WARN)作为兜底即使log4j2配置文件没被读到也不至于刷屏。8.2 运行配置里值得勾选和填写的几项在Run/Debug Configurations里我固定会做这几件事VM options填-Xmx2g -Dfile.encodingUTF-8勾选Include dependencies with Provided scopeWorking directory设为项目根目录避免相对路径读不到文件如果用了--add-opens才能跑JDK 17把对应的JVM参数也写进去。如果项目里用到System.setProperty(hadoop.home.dir, ...)来解决Windows下的winutils问题也可以放在VM参数里比在代码里写更干净。不过近几年在Windows上跑本地Spark的机会少了多数人用Mac或Linux这个配置可以忽略。8.3 样本数据与测试数据的管理本地调试的效率很大程度上取决于样本数据准备得好不好。我的经验数据量控制在几千到几万行既能触发真实的shuffle又不会等太久字段覆盖要全包括可能是null的字段、可能有异常的字段准备一份故意有问题的数据用于验证容错逻辑数据文件放resources下路径通过classpath获取。还有一个细节CSV读取时显式给schema不要靠inferSchema。推断schema在本地看着方便但会多扫描一遍数据而且推断出的类型可能和预期不一致比如全数字的列推断成整数含空值又变成字符串。显式给schema能节省时间也避免类型判断引发的后续问题。9. 最后分享两个容易忽略的小配置第一个是spark.local.dir。本地模式下shuffle数据默认写在/tmp下如果系统清理策略激进长时间运行可能遇到shuffle文件读写失败。把它指到一个固定的工作目录会更稳在配置里设一下就行。第二个是控制台的输出截断。show()的truncate参数默认是true超过20个字符会被截断。调试时建议写成show(false)不然你看到的数据和真实数据不一致容易误判——我自己就因为被截断的字符串判断过数据没问题结果后面才发现尾部有异常字符。这个配置改动成本为零但确实能省掉一次误判。