刚开始学Hadoop的时候，很多人都会先被一堆名词砸晕：DataNode、NameNode、YARN、ResourceManager、Shuffle、Spill……还没搞清楚这些单词之间的关系，就要面对一个看起来简单的题目——用MapReduce统计一堆文本里每个单词出现的次数。而WordMapper和WordReducer，就是你写的第一个真正意义上跑在分布式框架里的代码类。
说实话，我当时写第一个WordCount的时候，光是搞清楚Mapper和Reducer谁先谁后、输入输出键值对为什么全是Writable类型，就折腾了好几个晚上。等真正把代码打包、提交到集群、看到控制台刷出Job运行进度、最后在HDFS的输出目录里拿到结果，那一刻我才觉得自己稍微沾了点框架的边。这篇博客我就把从零写WordMapper和WordReducer到成功运行MapReduce的全过程拆开聊，包括代码逐行解释、环境准备、打包提交命令、以及我在实际跑批时踩过的一堆坑。
这内容适合刚开始学MapReduce的人，也适合那些虽然听过WordCount但还没自己完整跑过一遍的同学。我把能讲的细节都讲出来，你看完照着做一遍，基本就能把MapReduce的开发流程串起来了。
1. 别被绕晕：MapReduce到底在解决什么问题
1.1 WordCount这个经典题目为什么这么经典
MapReduce编程模型最早来自Google那套思想，说白了就是一句话：把一个需要处理海量数据的任务，拆成很多小任务分给多台机器同时算，再把算出来的局部结果汇总成最终的全局结果。
WordCount就是这个模型里最纯粹的缩影。它没有复杂的业务逻辑，就是把一个超大文本文件（或者很多个超大文本文件）里的单词全部拆出来，然后数一下每个单词出现了多少次。
那为什么不写个普通的Java程序逐行读文件统计呢？原因很简单：如果这个文件有几十TB，单台机器的内存和CPU根本扛不住。就算能勉强跑完，耗时也极其夸张。而MapReduce的思路是把这个文件切块，比如一块128MB，分散到集群的多个节点上，每台机器只处理自己那几块数据，最后再归并。这就是所谓的“分而治之”。
WordCount经典还因为它恰好把MapReduce的两个核心阶段都用上了。Map阶段做拆分和初加工，Reduce阶段做汇总和收口。你学完WordCount，实际就学明白了MapReduce的核心抽象：Map永远是把一份数据变成多份中间数据，Reduce永远是多份中间数据合成一份结果。这个思想理解了，后面各种复杂的MapReduce作业都是在这个基础上套壳。
1.2 Mapper和Reducer分别是干什么的
整个MapReduce作业里，用户真正要写的核心代码就是Mapper和Reducer两个类。
Mapper的输入是源数据里的键值对，输出是一堆新的键值对。拿WordCount举例，输入是文件的每一行，key是这一行在文件里的偏移量，value是这一行的文本内容。Mapper做的事情极其简单：把这行文本按空格（或者其他分隔符）切开，拿到每个单词，然后发出去一条 record，形如(word, 1)。也就是说，不管这个词出现了几次，先每个单词记上一笔。
Reducer的输入就稍微特殊了：它拿到的不是单个的键值对，而是“相同key的一组值列表”。框架在图省事在外面保证了一件事——所有key相同的中间记录，一定会被送到同一个Reducer实例上。所以在Reducer的reduce方法里，我们看到一个values集合，里面装着某个单词所有的1。这时只需要循环累加，把这个单词的次数加出来，输出(word, totalCount)。
这里有个特别重要的概念需要理清楚：Map端是并行度高、处理逻辑轻量的地方，应该尽量在这里把数据拆得足够细；Reduce端是收口的阶段，数据明细已经变成汇总，所以逻辑重点在聚合和化简。如果你把很多业务逻辑堆在Reducer里，那么这个阶段会成为瓶颈，跑得会特别慢。后面我还会专门说这个。
1.3 一个单词从输入到输出，完整走了一遍什么流程
为了让你脑子里有个完整的链条，我先把一个单词从文件到最终结果的完整旅程讲一遍，细节后面再补。
假设HDFS上有一个文件，被切成若干数据块，每个数据块对应一个Input Split。框架会为每个Split启动一个Map任务。Map任务读取Split里的每一行，调用你写的map方法，把结果写到本地磁盘（不是写HDFS，这里是Map端中间结果，写本地是为了性能）。
写入之前，系统还会对输出的key做一次分区计算，默认的HashPartitioner会对key求hash，再跟Reducer数量取模，决定这条记录该去哪个Reduce任务。同一个单词的所有记录，因为key一样，hash一样，会分到同一个区里去。
然后经历一个叫Shuffle的过程，框架把所有Map任务的中间结果按照分区拉取到对应的Reduce节点，并且对数据按键排序、归并。这里的排序是MapReduce自带的行为，即使你不设置任何排序规则，中间结果也是有序的。
Reduce端拿到的是(word, [1, 1, 1, 1, ...])这样的结构，你的reduce方法就负责把这个数组加起来，输出一个结果到HDFS上。
一句话概括：Map负责拆和标，框架负责传和排，Reduce负责聚合和落盘。这就是MapReduce的全部秘密。
2. 动手前的环境准备与工程搭建
2.1 开发环境与依赖清单
写MapReduce代码不需要多高端的配置，一个装了Java的电脑就行。如果你要提交到集群，建议在跟集群大版本一致的Hadoop环境下编译。最省事的方法是创建一个Maven工程，引入下面这些依赖：
<dependencies> <dependency> <groupId>org.apache.hadoop</groupId> <artifactId>hadoop-client</artifactId> <version>3.3.6</version> </dependency> </dependencies>如果用的是Hadoop 2.x，可以用hadoop-mapreduce-client-core和hadoop-common这两个依赖配合，不过在Maven中央仓库直接引hadoop-client最省事，它会带齐Common、HDFS、YARN、MapReduce相关的核心类。
强调一个容易忽略的点：Maven依赖的版本，一定要跟你要提交的目标集群版本一致或者接近。这个真不是玄学，Hadoop的RPC协议在不同小版本之间偶尔会不兼容，你本地用3.3.6编译的jar，提交到3.1.3的集群上，经常会出现奇怪的类加载或者协议异常。我见过最离谱的一次是本地打包成功，集群上报UnsupportedOperationException，查了一天最后发现是版本差异导致的内部API变动。
2.2 本地模式下先跑通的核心配置
在我们还没搭集群的时候，其实可以先在本地跑通WordCount。Hadoop支持local模式，也就是不启动任何守护进程，直接在本地文件系统上以单机多线程方式模拟MapReduce运行。
本地运行的好处是调试方便，你不用去管HDFS和YARN，直接像普通Java程序一样跑。这时候有个简单的做法：把mapreduce.framework.name设置成local，同时把输入路径指向本地文件。
比如在IDE里跑的时候，可以直接这样设置：
configuration.set("mapreduce.framework.name", "local"); configuration.set("fs.defaultFS", "file:///");然后直接给Job传入本地路径，比如/Users/me/wordcount/input和/Users/me/wordcount/output。这样跑起来之后，日志会刷在IDE里，非常直观。
还有一点很实用：不需要真正打包成jar，在本地模式下，Job对象可以直接通过Job.getInstance(configuration)构建，然后waitForCompletion(true)提交即可。因为本地模式是进程内模拟，不需要通过命令行提交。
但是注意，本地模式跑通了不等于集群能跑，它只是帮你验证逻辑是否正确。真正上集群以后，类加载、依赖、权限的问题全都会冒出来。
2.3 集群运行前必须检查的三件事
如果你已经有一个测试集群，正式提交任务前，我建议先检查下面三件事，不然任务一提交就挂，非常浪费感情。
第一个是HDFS上输入路径是否真实存在、数据是否已经上传。很多人本地跑通了，到集群上直接给一个不存在的路径，然后看到FileNotFoundException一脸茫然。先执行一遍hdfs dfs -ls /input确认一下。
第二个是输出目录绝对不能提前存在。MapReduce框架有一个硬性要求：输出目录不能已经存在，否则会直接报FileAlreadyExistsException。这跟很多人的习惯不一样，一般程序会覆盖目录，但MapReduce认为覆盖太危险，干脆强制你换个新路径。第一次跑的时候我总是忘记，结果每次都要先删一次输出目录。
第三个是确认集群资源足够。看看YARN的资源池是不是还有其他大任务占着，队列有没有剩余内存。WordCount虽然轻量，但如果你Hadoop的每个容器大小设置得很大，而集群总共就几个G内存，可能连ApplicationMaster都起不来。
3. WordMapper与WordReducer核心代码逐行拆解
3.1 Mapper侧代码：拆词、标记、发射
下面这段就是我们的WordMapper类，也就是标题里说的WordMapper。我直接把完整代码贴出来，然后逐段解释。
package com.example.demo; import java.io.IOException; import org.apache.hadoop.io.IntWritable; import org.apache.hadoop.io.LongWritable; import org.apache.hadoop.io.Text; import org.apache.hadoop.mapreduce.Mapper; public class WordMapper extends Mapper<LongWritable, Text, Text, IntWritable> { private static final IntWritable ONE = new IntWritable(1); private Text word = new Text(); @Override protected void map(LongWritable key, Text value, Context context) throws IOException, InterruptedException { String line = value.toString(); String[] words = line.split("\\s+|[,.;:!?\"()]"); for (String w : words) { if (w.isEmpty()) { continue; } String cleanedWord = w.toLowerCase(); word.set(cleanedWord); context.write(word, ONE); } } }第一行类声明里的四个泛型，是很多人一开始最容易懵的地方。<LongWritable, Text, Text, IntWritable>分别代表输入的key类型、输入value类型、输出key类型、输出value类型。输入key是行偏移量，所以是LongWritable；输入value是行内容，所以是Text；输出key是单词，所以是Text；输出value是计数1，所以是IntWritable。
map方法里的key虽然看起来没有使用，但这个是框架规定的入参结构，你不能去掉它。实际运行中，每个Map任务会逐行调用这个map方法，也就是说每一行文本都会走一遍这个函数。
有个细节：我的代码对文本做了一点预处理，把标点符号也切掉了，还转了小写。这在实际业务里很有用，因为数据不会像教科书里那样干净。如果你只按空格切，类似Hello,和Hello就会被当成两个词统计，结果明显不对。虽然代码稍微多了一点，但统计质量会好不少。
再强调一个Map阶段的常见误区：很多人会把统计逻辑直接写在Mapper里，比如在map方法里用一个Map去累积每个单词出现的次数。这是不对的，原因有两点。第一，Map任务可能会被框架反复调用，还可能在多个Map任务上处理同一份数据的多个分片，你自己在Mapper里做本地聚合，逻辑上容易出问题；第二，Mapper的价值就是把一条一条的中间结果交给框架做Shuffle，如果你在Map端就把所有数据聚合起来了，那Reduce阶段就没有存在的必要了，整个并行计算模型就变味了。Mapper就是用来发记录的，不是用来做全局统计的。
3.2 Reducer侧代码：分组、求和、输出
看完了WordMapper，再看WordReducer。这里的类名我按照通用命名习惯，取名叫WordReducer。
package com.example.demo; import java.io.IOException; import org.apache.hadoop.io.IntWritable; import org.apache.hadoop.io.Text; import org.apache.hadoop.mapreduce.Reducer; public class WordReducer extends Reducer<Text, IntWritable, Text, IntWritable> { private IntWritable result = new IntWritable(); @Override protected void reduce(Text key, Iterable<IntWritable> values, Context context) throws IOException, InterruptedException { int sum = 0; for (IntWritable val : values) { sum += val.get(); } result.set(sum); context.write(key, result); } }注意这里的泛型：<Text, IntWritable, Text, IntWritable>，前两个是输入的key和value类型，分别是单词和它对应的计数列表；后两个是输出的key和value类型，分别是单词和最终的次数。
reduce方法里，key是当前正在处理的单词，values是该单词对应的所有计数集合。框架已经保证把所有相同key的value聚合到一个迭代器里，你只需要循环累加就行。
有一点要说透：values传给我们的类型是Iterable而不是一个普通的List，这个设计是有原因的。因为在海量数据场景下，一个极端热门的单词（比如英文文本里的"the"）可能对应百万条甚至上亿条记录，如果框架提前把这些values全部构造成一个集合放到内存里，内存早就爆了。用迭代器的方式，框架可以分批从磁盘取、用完即弃，保证内存占用可控。所以我们写Reducer的时候，也尽量不要自己把这些values复制到一个内存List里再做二次处理，除非你明确知道数据量很小。
还有一个小细节：result对象是在类级别定义的，每次reduce方法里调用result.set(sum)更新值，然后context.write(key, result)。这里不直接new IntWritable(sum)是为了复用对象，减少频繁创建对象带来的GC压力。这个习惯在大数据场景下很值得保持，虽然对于WordCount这种小作业来说无所谓，但养成好习惯总没错。
3.3 代码里这些泛型到底怎么对应起来
很多初学者看MapReduce代码，最大的障碍就是四个泛型到底在跟什么东西对应。我专门用一个表来梳理清楚。
| 类型位置 | WordMapper中的泛型 | 实际含义 | 例子 |
|---|---|---|---|
| 输入key | LongWritable | 文件行偏移量 | 文件第100个字节的位置，值是99 |
| 输入value | Text | 一整行字符串 | "hello world hello" |
| 输出key | Text | 切分出来的单词 | "hello" |
| 输出value | IntWritable | 单词出现一次 | 1 |
再看Reducer侧的接收类型，你会发现Reducer输入的key和value，正好就是Mapper输出的key和value类型。这不是巧合，而是框架规定了数据流方向：Mapper输出什么类型，Reducer输入就是什么类型。而Reducer的输出类型，就是整个作业最终写到HDFS上的结果类型。
很多编译报错，比如Type mismatch，本质就是这几处的泛型没有对应好。我见过不少同学把Mapper的泛型写对了，但Reducer的泛型照搬了Mapper的输入，结果编译直接报错。以后你看到类似错误，第一反应就是去对一遍这六处类型是不是首尾相接。
这里再补充一个细节，Hadoop为什么不用Java的Integer、String，而要用IntWritable和Text这些Writable类型？因为MapReduce的中间结果会在不同节点之间通过网络传输，还会落盘到本地文件系统，Writable类型提供了一种非常高效的序列化方式，比Java原生序列化更紧凑、更快。所以你在写MapReduce代码时也要习惯用Writable类型，不要自己去换成Java基础类型，除非你在Reducer内部做计算，才用.get()取出来。
4. 编写Driver主类：把作业提交给运行框架
4.1 Job对象配置清单
光有Mapper和Reducer还不行，你得有一个主类把这两个类组装起来，告诉Hadoop这个作业该怎么跑。这个类在MapReduce里习惯叫Driver，因为它是提交作业的入口，有点像开车的人把控方向盘。
下面是一个标准Driver类的写法：
package com.example.demo; import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.Path; import org.apache.hadoop.io.IntWritable; import org.apache.hadoop.io.Text; import org.apache.hadoop.mapreduce.Job; import org.apache.hadoop.mapreduce.lib.input.FileInputFormat; import org.apache.hadoop.mapreduce.lib.output.FileOutputFormat; public class WordCountDriver { public static void main(String[] args) throws Exception { if (args.length < 2) { System.err.println("Usage: WordCountDriver <inputPath> <outputPath>"); System.exit(-1); } Configuration conf = new Configuration(); Job job = Job.getInstance(conf, "word count"); job.setJarByClass(WordCountDriver.class); job.setMapperClass(WordMapper.class); job.setReducerClass(WordReducer.class); job.setOutputKeyClass(Text.class); job.setOutputValueClass(IntWritable.class); FileInputFormat.setInputPaths(job, new Path(args[0])); FileOutputFormat.setOutputPath(job, new Path(args[1])); boolean success = job.waitForCompletion(true); System.exit(success ? 0 : 1); } }这个类里每一行都值得说道说道。
Job.getInstance(conf, "word count")这一步是创建作业实例，第二个参数就是作业名称，会在YARN的界面上显示出来。实际工作中，起一个能描述业务含义的名字非常有用，不然你会在ResourceManager上一眼看到一堆word count，根本分不清是哪个业务。这里建议用业务命名，比如user-log-wordcount-20240601。
job.setJarByClass(WordCountDriver.class)这行特别关键，它告诉框架：你这个作业的jar包由哪个类定位。框架通过这个类找到jar包的位置，然后分发到各个节点上去执行你的Mapper和Reducer。如果这行不写，在本地模式可能还好，提交到集群后很多节点根本找不到你的类，直接报ClassNotFoundException。
job.setMapperClass和job.setReducerClass不用多说，就是注册我们写的两个类。
job.setOutputKeyClass(Text.class)和job.setOutputValueClass(IntWritable.class)设置的是Reducer最终输出到HDFS上的类型，这个会根据Reducer泛型的后两个值来设置。但如果有同学在Mapper和Reducer的输出类型不一致的情况（比如有些作业只需要Map不需要Reduce，Mapper的输出就是最终结果），那就还需要额外调用job.setMapOutputKeyClass和job.setMapOutputValueClass。WordCount这个例子不需要，因为Mapper的中间输出类型和Reducer最终输出类型恰好一致。
4.2 路径参数的两种给法
代码里用的输入输出路径是从args参数里取的，也就是运行jar包时在命令行传进去。比如：
hadoop jar wordcount-demo.jar com.example.demo.WordCountDriver /input /output这里的/input和/output都是HDFS上的路径，不是本地路径。很多新手在这栽跟头——先是花半天时间把文件传到本地某个目录，然后传路径给程序，结果程序跑在集群节点上，根本读不到你本地文件。
另外还有一种硬编码路径的方式：
FileInputFormat.setInputPaths(job, new Path("hdfs://mycluster:8020/user/data/input")); FileOutputFormat.setOutputPath(job, new Path("hdfs://mycluster:8020/user/data/output"));这种方式适合写测试或临时脚本，但生产环境里我还是推荐从命令行传参。因为你一旦硬编码，就会面临改一次代码重新打包一次jar的情况，特别麻烦。把路径做成运行时参数，代码就是通用的。
4.3 Combiner：一个免费的优化点
在我们上面这个Driver里，有一个很值得讲的优化选项：Combiner，中文经常叫“合并器”。它的作用是在Map端做一次本地预聚合，把Reducer需要处理的数据量大幅缩小。
很多教科书里会把它说得很玄，其实就一句话：Combiner是一个运行在Map任务本地、跟Reducer逻辑一样的微型Reducer。它先对Map输出做一遍局部求和，然后再把局部结果发给真正的Reducer做全局求和。
比如同一个Map任务里处理了100行文本，其中"hello"出现了100次，Mapper发出去的记录是100条(hello, 1)。没有Combiner的时候，这100条会被原封不动地发送到Reducer；有了Combiner，Map端先把这100条聚合成1条(hello, 100)，再发出去。网络传输的数据量减少了一个数量级。
WordCount里设置Combiner极其简单，因为Combiner的逻辑跟Reducer完全一样，都是求和。所以只需要在Driver里加一行：
job.setCombinerClass(WordReducer.class);也就是说，我们直接复用WordReducer作为Combiner。
这里有个需要警惕的地方：Combiner只在Map端做局部聚合，它不能替代Reducer的全局聚合，两者的执行时机完全不一样。另外，如果你的Reducer逻辑不是可交换、可结合的，比如计算中位数，或者对顺序敏感的操作，那就不能直接复用Reducer逻辑作为Combiner。这种场景下要么不设Combiner，要么单独写一个全局安全的Combiner实现。我第一次在真实项目里用Combiner时，就是因为没搞清楚这个约束，导致最终结果和预期不一致，排查了很久才发现是Combiner把不可交换的逻辑做了局部合并，产生了错误结果。
5. 打包、提交、运行MapReduce作业
5.1 Maven打包的两种方式
写完了代码就要想办法让集群跑起来。第一步是把代码打成jar包。
最简单的打包方式是直接用Maven的package命令。在工程根目录执行：
mvn clean package这样会在target目录下生成一个普通的jar。但有个问题：这个jar里可能没有包含依赖的第三方库。如果你的代码里除了Hadoop自带的类没有其他外部依赖，那这个jar就够了，因为Hadoop集群的节点上本身就有Hadoop依赖包。我有一个测试用的WordCount代码就是这么干的，jar很小，几百KB，提交之后很稳定。
如果代码里还有别的依赖（比如如果你在Mapper里用到了某个序列化库、JSON解析库，那就要仔细处理）。这种情况下，推荐用Maven Shade插件打一个“胖jar”：
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.5.1</version> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> </execution> </executions> </plugin> </plugins> </build>这个插件会把所有依赖的class打进去，生成的jar会大很多，几MB甚至几十MB，但它能跑。要注意的是，shade可能会把一些配置文件覆盖掉，如果集群上出现奇怪的Hadoop配置，可以适当在plugin里加过滤器排除掉META-INF下的敏感文件。这个属于进阶问题，新手遇到再处理就行。
5.2 提交到集群的命令与运行日志解读
jar包准备好之后，提交命令格式如下：
hadoop jar wordcount-demo.jar com.example.demo.WordCountDriver /input /output如果你用的是Hadoop 2.x+，也可以写yarn jar，两者效果基本一样。hadoop jar的本质是启动一个进程，去连接ResourceManager，申请ApplicationMaster，再由AM向NodeManager申请容器来跑Map和Reduce任务。
提交成功之后，控制台会开始刷一堆日志。新手看到日志第一反应就是慌，其实只需要关注几个关键点。
第一个是看到Job job_xxx开头的行，说明你的作业已经在YARN上创建成功了，后面跟的那串数字是作业ID，日志里和YARN的Web界面上都能查到。
第二个是会出现一个进度条，类似：
map 0% reduce 0% map 100% reduce 0% map 100% reduce 100%这是作业的整体进度。map阶段计数到了100%，意味着所有Map任务执行完成。reduce到100%，说明所有Reduce任务也已经完成。如果进度卡在某个百分比不动，就要注意了，尤其是reduce阶段经常卡在33.3%的位置，那通常是Reducer在拉取Map输出数据，数据量大的话确实会卡一段时间，但如果卡很久不动，基本是节点间网络或者磁盘出了问题。
第三个是任务完成后会有一个作业统计信息打印，包含Completed Jobs: 1，以及各类计数器的值。比如Map input records、Reduce shuffle bytes这些，以后调优会用到。我现在每次跑完任务，都会习惯性看一眼两个指标：Reduce shuffle bytes和Total time spent by all maps in occupied slots (ms)。前者反映Shuffle数据量，后者反映Map阶段整体耗时。
5.3 结果文件长什么样
作业成功跑完之后，你到HDFS上查看输出目录：
hdfs dfs -ls /output正常情况下会看到几个文件和一个隐藏的临时目录。关键文件叫part-r-00000，part-r-00001这样的名字，第一个数字是分区编号，从0开始，数量跟Reduce任务数一致。你可以直接把内容打出来：
hdfs dfs -cat /output/part-r-00000 | head -10输出大概是这样的格式：
hello 2 world 3 hadoop 1每一行是“单词 + 制表符 + 次数”。这里我多说一句：MapReduce默认用制表符来分隔key和value，如果你想改成其他分隔符，需要在Reducer输出时自定义。平时看结果就按这个默认格式来记，免得到时候以为数据有问题，实际上是分隔符没看清。
还有一点值得提：如果输出目录下出现了_SUCCESS文件，那就说明作业确实完成了，这是Hadoop写的一个标志文件。很多人跑完任务不确定是不是全成功了，又不愿意去看日志，直接看这个文件是最快的判断方式。我习惯在自动化脚本里用test -f /output/_SUCCESS来确认任务是否跑成功。
6. 常见问题与排查技巧实录
6.1 报错信息速查表
我在实际使用中积累了不少坑，这里用表格列几个最常见的错误、原因和解决方案，方便你对照排查。
| 报错现象 | 大概率原因 | 解决方法 |
|---|---|---|
ClassNotFoundException: com.example.demo.WordMapper | 没有正确设置setJarByClass，或jar没有包含Mapper/Reducer类 | Driver里检查setJarByClass是否指向主类；确认打出来的jar里面真的包含class文件 |
FileAlreadyExistsException: Output directory hdfs://.../output already exists | 输出路径已经存在，MapReduce禁止覆盖输出 | 执行hdfs dfs -rm -r /output删掉旧目录或换一个新路径 |
FileNotFoundException: /input does not exist | HDFS里根本没有这个输入路径 | hdfs dfs -ls /查看根目录；确认文件已经上传到HDFS |
Java heap space | Map或Reduce任务内存给的不够 | 调整容器内存参数，YARN的配置或代码里通过mapreduce.map.memory.mb和mapreduce.reduce.memory.mb调大容器内存 |
Connection refused或Call From xxx to localhost:8020 failed | 客户端连不上NameNode | 检查core-site.xml里的fs.defaultFS是否指向正确的NameNode地址和端口 |
map 100% reduce 0%长时间不动 | Reduce任务拉取Map输出阶段慢，或节点间网络问题 | 看YARN日志确认是不是有节点挂了；检查数据倾斜情况；如果单Reducer数据量太大，考虑增加Reducer个数 |
Exit code: 1且日志里只有一串堆栈但看不出原因 | 代码里运行时抛异常，或者依赖缺失 | 去YARN日志里翻syslog，找具体堆栈；确认使用了shade-fatjar时依赖是否完整 |
6.2 三个最容易让新手崩溃的场景
场景一：本地跑得好好的，集群上一提交就报类找不到。这个几乎每个人都遇到过。原因很可能是你本地跑的时候用的是IDE自带的依赖环境，类加载没问题；但提交到集群后，框架要根据setJarByClass定位jar，然后把jar分发到TaskTracker去执行。如果你打包的时候没有把类打进去，或者类名写错了，就会找不到。解决办法很憨但很有效：用jar tf wordcount-demo.jar命令打开jar包，看看你写的class是否在里面，路径是否跟代码里包名一致。
场景二：任务提交成功，但运行了一两分钟，所有Map任务全部失败。打开日志一看，是Unparsable或者乱码，通常原因是你的输入文件不是纯文本。我遇到过一次，测试数据是一个从Windows上传的文件，带有BOM头，第一行解析直接出错。解决方式是先用sed -i 's/\r$//'把文件清洗一下，或者在上传前就统一做数据清洗。另一个可能是文件编码除了UTF-8是其他编码，例如GBK，这时需要指定编码解析方式，问题就麻烦不少了。
场景三：跑完了，结果都是0或者没数据。这个问题就值得仔细分析了，多半是你写的Mapper输出key的规则有问题，导致所有单词都变成了同一个key，或者单词被拆分得面目全非。我调试过一个类似问题：一段日志里的每条记录都是INFO 2024-01-01 10:00:00 user_login，如果我用空格切分，那么"INFO"、"2024-01-01"、"10:00:00"这些都会变成key参与统计，结果一堆没意义的垃圾结果。这时候就需要在split的时候加入过滤逻辑或者使用更精细的正则。
6.3 运行效能小提醒
最后分享几个提升WordCount这类作业运行效率的小技巧。
第一个是合理设置Reducer数量。默认情况下Reducer是1个，就意味着所有数据都要汇总到一个节点上处理，如果输入数据量大，这1个Reducer会成为严重瓶颈。可以在Driver里指定：
job.setNumReduceTasks(4);对于WordCount这种聚合类作业，Reducer数量可以适当调大，比如输入10GB数据，我一般会开8到16个Reducer。但也不能盲目开很多个，因为每个Reducer都会输出一个结果文件，文件太多反而导致后续处理顺着“小文件问题”扩散。
第二个是利用Comparator或者自定义分区减少倾斜。WordCount里某些热门单词会导致个别Reducer处理的数据量特别多，其他Reducer空闲，这就是数据倾斜。虽然统计计数类作业的倾斜没有Join那么明显，但真正大文本里，热门词的count可能非常夸张。如果发现某个Reducer跑的时长和其他Reducer差异巨大，基本是倾斜了。解决方案是进一步拆细key，比如把key扩展成word+hash再聚合，之后二次降低热度分布，不过这属于进阶优化了。
第三个是别省略Combiner。我见过不少同事写WordCount时不设置Combiner，认为有没有都行，数据量小的时候确实感觉不到差别，但数据量一上去，Shuffle和网络传输的耗时立马就上来了。你只是写两行代码就能让作业快很多，何乐而不为。
第四点是合理设置Block大小和复制因子。如果只是自己测试，输入文件尽量在几百MB以内都行。如果要在真实场景跑，文件的块大小会影响Map任务数量。Hadoop默认128MB一个Split，如果你的文件很小（比如10MB），它只会产生1个Map任务，那再怎么优化也快不起来。不过这是数据本身的问题，只用MapReduce框架解决不了。
以我的经验，写WordCount这第一个MapReduce作业，最大的价值不是“学会了一个统计单词的例子”，而是把一条链路彻底走通了：编写Mapper和Reducer、组装Job、打包、提交、看日志、找问题。你后面写再复杂的MapReduce作业，跑不动了无非还是在跟这条链路打交道。把这条链路走通之后，你就不是在看Hadoop的文档，而是真正在用Hadoop了。
最后再说一个我踩过的坑：写Driver时，System.exit(success ? 0 : 1)这一行千万别省。有些例子为了偷懒省略了它，主线程一结束就直接退出了，作业还没跑完就没了。这个细节直接决定了你的程序是能正常等待作业完成并退出，还是交出去之后就杳无音信。写MapReduce代码时，主类就是门面，该写的启动逻辑一处都不能少。
你现在就可以照着这篇文章，把自己电脑里的Hadoop环境搭起来，写个WordMapper和WordReducer跑一遍。有什么问题，欢迎在评论区把你的报错贴出来，我看到会尽量帮你诊断。第一次跑通分布式作业的感觉，真的和普通程序完全不一样，那种“几十台机器一起替我数单词”的参与感，你会记住很久的。
