只要搜过Hadoop安装的人多少都有过这种体验打开一篇标题写着“保姆级”“全网最全”的教程正文却让你先改SSH配置、配免密登录、格式化NameNode一顿操作猛如虎最后连hadoop version都跑不动。我自己也是这么绕过来的后来帮人排查环境问题第一句话永远是先确认你要装的到底是哪种模式。这篇就详细说说Hadoop单机安装配置也就是官方文档里的 Standalone Operation。它是最轻量的一种部署方式不需要HDFS、不需要YARN守护进程、不需要SSH免密适合本地编写和调试MapReduce程序也适合第一次接触Hadoop的人搞清楚“装好了”到底长什么样。内容会按官方手册的逻辑走但比官方文档多补上实际命令和异常处理目标是让你照着敲一遍就能跑通。1. 安装前的三件大事版本选型、JDK匹配、单机模式与伪分布式的边界1.1 版本选型不是越新越好Hadoop官网的下载页会把最新稳定版放在前面但你直接下载“最新子版本”不一定是最优解。我自己更推荐 3.3.x 系列比如 3.3.4、3.3.6。原因很简单这个系列在业界用得最广网上遇到问题时能搜到的解决方案最多而且官方文档对 3.3.x 的测试覆盖完善社区里常见的Spark、Flink等组件适配也没问题。不建议从2.x开始学。2.x和3.x在API、命令参数、默认端口、shell脚本行为上都有差异很多老教程还停留在2.x。你照着操作到一半很可能发现某些目录不存在、某个命令被弃用了然后浪费时间纠结“是不是我敲错了”。初学阶段减少变量比追求新版本重要得多。另外要选二进制发行版不用自己编译源码。下载文件名一般是hadoop-3.3.6.tar.gz。如果你看到hadoop-3.3.6-src.tar.gz那是源代码包初学阶段完全不需要碰。1.2 JDK版本为什么直接决定启动成败Hadoop 3.3.x 官方要求 Java 8 或 Java 11。很多人装完Hadoop运行时报ClassNotFoundException或NoClassDefFoundError根本原因不是Hadoop损坏而是JDK版本不对。比如热搜里经常出现的java.lang.NoClassDefFoundError: org/apache/hadoop/crypto我在有的机器上见过多半是用了高版本JDK或者系统里同时装了多个JDK导致Hadoop调用了错误的一个。所以第一步先把Java环境稳住。我个人的原则是能用OpenJDK 8优先用OpenJDK 8。虽说Java 11也支持但很多老资料、老配置都基于Java 8实践过遇到问题好排查。如果你的系统默认装了Java 17或更高别抱侥幸心理尽早切换或补装一个8/11。确认版本只需两条命令java -version javac -version正常输出里会看到openjdk version 1.8.0_xxx或11.0.xxx。如果你看到17.0.x后面跑官方WordCount示例时大概率会遇到加密包相关报错。1.3 单机、伪分布式、真正的集群先别混为一谈这里必须把概念掰开因为大部分安装失败的教程问题都出在“混着用”。单机模式Standalone Mode是Hadoop默认的运行方式。官方文档说得明白默认情况下Hadoop配置为非分布式模式作为单个Java进程运行。这个模式主要用来调试MapReduce程序不启动NameNode、DataNode、ResourceManager、NodeManager这些守护进程也没有真正的HDFS。你在本地文件系统上读写数据直接跑作业。伪分布式模式Pseudo-Distributed Mode则是用一台机器模拟分布式集群。它会真的启动NameNode、DataNode、ResourceManager、NodeManager这些进程也能用HDFS shell需要配置多个XML文件还需要SSH免密最终通过start-dfs.sh和start-yarn.sh启动。很多网上的“单机安装教程”实际讲的是伪分布式。真正的集群就更好理解了多台机器各自跑不同角色。这里不展开。这篇教程锁定“单机模式”。所以后面强调的所有步骤都不涉及格式化NameNode、不涉及start-dfs.sh、不涉及SSH免密。你如果看到某篇教程让你做这些那它讲的其实是伪分布式不是单机模式别被带偏。2. 环境准备JDK安装与两个“没必要做”的操作2.1 以Ubuntu为例安装OpenJDK 8我以 Ubuntu 20.04、22.04 为例其他Linux发行版逻辑相同。先更新软件源然后安装OpenJDK 8sudo apt update sudo apt install -y openjdk-8-jdk如果你的系统较新软件源里可能没有openjdk-8。这时安装openjdk-11问题也不大sudo apt install -y openjdk-11-jdk安装完成后找到Java的真实安装路径。这一步很多人会忽略因为java -version能跑不代表JAVA_HOME正确。readlink -f $(which java)在Ubuntu上通常输出为/usr/lib/jvm/java-8-openjdk-amd64/bin/java记下/usr/lib/jvm/java-8-openjdk-amd64后面配置JAVA_HOME要用。如果你用的是CentOS/RHEL系列安装包通常叫java-1.8.0-openjdk-devel路径类似/usr/lib/jvm/java-1.8.0-openjdk自己根据readlink结果确认。2.2 要不要新建hadoop用户先给结论单机模式下用当前普通用户完全没问题技术上不需要新建用户。但我还是建议你新建一个专用用户原因不是“必须”而是“干净”Hadoop在运行时可能会产生大量日志、临时目录和中间文件分开用户不容易污染系统环境以后你从单机模式走向伪分布式、集群部署多机环境基本都要求统一用户身份提前适应能少踩坑root用户装Hadoop能用但如果在root下启动了一些进程生成的目录权限其他用户动不了之后换普通用户又会出现权限错乱。创建用户的命令很简单sudo useradd -m -s /bin/bash hadoop sudo passwd hadoop后续需要把安装目录的所有权交给你使用的用户。比如我把Hadoop解压到/opt/hadoop那就要执行sudo chown -R hadoop:hadoop /opt/hadoop如果你只用root学习在root下安装也可以跑通但我不推荐。宁可一开始麻烦一点也不要后面权限问题一个接一个。2.3 hosts与SSH免密单机模式不需要这是我最想帮新手省时间的一点单机模式不需要配置SSH免密也不需要专门改/etc/hosts。网上大量教程会教你执行ssh localhost、生成密钥、把公钥加到authorized_keys然后解释“Hadoop要通过SSH远程启动守护进程”。没错伪分布式的脚本确实会通过SSH到localhost去启动NameNode等进程所以伪分布式必须配免密。但单机模式压根不启动这些守护进程你做免密纯粹是在绕远路。同样道理单机模式也不用执行hdfs namenode -format。那是在NameNode启动前初始化文件系统元数据的操作。单机模式连NameNode进程都没有你格式化谁呢所以如果你想验证“Hadoop单机安装配置”是否成功唯一靠谱标准是先跑通hadoop version再跑通官方WordCount示例。这两件事都不需要SSH也不需要改hosts。3. 下载、校验、解压官方手册里的那套标准流程3.1 下载地址与镜像选择Hadoop官方下载页面是https://hadoop.apache.org/releases.html里面会列出各版本和校验文件。想下历史版本要到Apache归档地址https://archive.apache.org/dist/hadoop/common/如果需要更快的下载速度可以用清华镜像https://mirrors.tuna.tsinghua.edu.cn/apache/hadoop/common/下载时注意文件名我以3.3.6为例wget https://mirrors.tuna.tsinghua.edu.cn/apache/hadoop/common/hadoop-3.3.6/hadoop-3.3.6.tar.gz这里多说一句不要只看文件名里的版本号下载完成后最好校验一下。很多网络环境不稳定下载损坏是常见现象而损坏的压缩包在解压时才报CRC错误那时候再排查会浪费很长时间。3.2 校验SHA-512再解压Apache为每个发布包提供了.sha512校验文件。下载同名校验文件wget https://mirrors.tuna.tsinghua.edu.cn/apache/hadoop/common/hadoop-3.3.6/hadoop-3.3.6.tar.gz.sha512然后计算压缩包的SHA-512值shasum -a 512 hadoop-3.3.6.tar.gz将输出和.sha512文件里的内容对比一致后再解压。最省事的方式是用-c参数echo $(cat hadoop-3.3.6.tar.gz.sha512) hadoop-3.3.6.tar.gz | shasum -a 512 -c -看到OK就是校验通过。然后解压tar -xzf hadoop-3.3.6.tar.gz解压后我会习惯把目录放到/opt下并建立软链接sudo mv hadoop-3.3.6 /opt/ sudo ln -s /opt/hadoop-3.3.6 /opt/hadoop sudo chown -R hadoop:hadoop /opt/hadoop /opt/hadoop-3.3.6建立软链接的好处是以后升级Hadoop版本只要换掉链接指向不需要改一堆环境变量里的路径。3.3 解压后的目录结构有什么用安装完先别急着乱翻了解下面几个关键目录就够目录作用bin/Hadoop的核心命令行工具比如hadoop、hdfs等sbin/守护进程启动/停止脚本单机模式基本用不到伪分布式以后才会用到etc/hadoop/配置文件目录包含hadoop-env.sh、core-site.xml等share/hadoop/mapreduce/MapReduce的jar包和官方示例jar包logs/日志目录运行报错时第一排查地点lib/Hadoop依赖的本地库和第三方库对单机模式来说你真正要记住的是bin/hadoop、etc/hadoop/hadoop-env.sh和share/hadoop/mapreduce。后面所有操作都围绕它们展开。3.4 跑通hadoop version确认Java被正确找到现在先别配置任何复杂东西直接执行/opt/hadoop/bin/hadoop version如果一切正常你会看到类似输出Hadoop 3.3.6 Source code repository https://github.com/apache/hadoop -r ... Compiled by stevel on ... Compiled with protoc ...如果提示JAVA_HOME is not set不要慌这正是我们要在下一节解决的问题。换句话说hadoop version是安装过程中的第一个检查点它验证的不只是Hadoop本身还包括Java环境有没有被正确发现。4. 单机模式到底要不要改配置一次讲透hadoop-env.sh和四个XML文件4.1 官方文档对Standalone模式的原话Hadoop官方文档的“Single Node Setup”章节写得很清楚默认情况下Hadoop被配置为以非分布式模式运行作为一个单独的Java进程。这种模式在调试时很有用。下面还有一句很多人没注意默认配置下不需要修改任何配置文件但建议在hadoop-env.sh中设置JAVA_HOME环境变量。这句话道破了单机模式的真相它默认就能跑你不用照着伪分布式的文章改一堆XML。网上很多“Hadoop单机安装配置”的教程一上来就让你配置core-site.xml里的fs.defaultFS为hdfs://localhost:9000这个配置在单机模式下是帮倒忙。设置了它之后你再用本地路径提交WordCountHadoop会把这个路径当成HDFS路径去解析结果提示找不到文件。你以为是Hadoop没装好其实是配置错了方向。4.2 必改的一处hadoop-env.sh里的JAVA_HOME文件路径是/opt/hadoop/etc/hadoop/hadoop-env.sh打开后搜索JAVA_HOME你会看到一行被注释掉的# export JAVA_HOME。把它改成你实际的Java路径并取消注释export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64如果你已经非常确定系统的JAVA_HOME环境变量全局可用也可以不改这个文件。但我在实际中吃过亏某些终端环境、某些调用方式下Hadoop脚本拿不到你.bashrc里定义的变量。为了稳定建议直接在hadoop-env.sh里写死。这是官方文档推荐的做法也是让后续命令少报错的“双保险”。改完之后再执行一次/opt/hadoop/bin/hadoop version这次应该就能看到版本信息了。4.3 四个XML文件为什么可以保持默认新手常被各种教程搞得很焦虑觉得不多配几个XML文件就不算“配置”。但实际上Hadoop解压后在etc/hadoop目录下core-site.xml、hdfs-site.xml、mapred-site.xml、yarn-site.xml默认要么是空的要么是不存在的模板。正式运行时Hadoop会套用内部默认值。在单机模式下这些默认值中最重要的一个是默认文件系统是file:///也就是说Hadoop读写的是本地文件系统默认执行框架是LocalJobRunner也就是任务在本地JVM里跑。所以如果你的目标是装好单机版请保持这四个XML文件为空/默认。如果以前改过现在想回滚直接把它们内容清空或者删除重新从模板复制一份。4.4 环境变量写入.bashrc的双保险逻辑虽然不配置XML文件但环境变量还是要配的。打开当前用户的~/.bashrc在末尾追加export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export HADOOP_HOME/opt/hadoop export HADOOP_INSTALL$HADOOP_HOME export PATH$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin保存后执行source ~/.bashrc然后验证echo $HADOOP_HOME hadoop version这里把sbin也加进PATH是因为以后你要是转向伪分布式还需要用start-dfs.sh、stop-dfs.sh这些命令。现在加上不会影响单机模式。环境变量的核心逻辑是交互式shell里能用Hadoop脚本内部也能用。但Hadoop脚本内部更依赖的是hadoop-env.sh里写明的JAVA_HOME。所以我一直强调两个地方都配不是多此一举是为了防止“换一种启动方式就找不到Java”这种诡异问题。5. 跑通官方WordCount装机是否成功的唯一标准5.1 准备测试数据先创建一个测试目录准备一个简单的文本文件。我在用户目录下操作mkdir -p ~/wordcount/input cd ~/wordcount echo hello hadoop hello world input/test.txt注意output目录一定不能事先存在。MapReduce框架要求输出目录必须是新建的否则会直接报文件已存在的异常。这也算一个经典雷区。5.2 执行WordCount的完整命令官方自带示例jar包路径在/opt/hadoop/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.6.jar执行命令hadoop jar /opt/hadoop/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.6.jar wordcount ~/wordcount/input ~/wordcount/output命令格式是固定的hadoop jar jar包 程序名 输入目录 输出目录。执行时你会看到一大段日志里面包含INFO mapreduce.Job: Running job: job_local123456 INFO mapreduce.Job: map 100% reduce 100% INFO mapreduce.Job: Job job_local123456 completed successfully看到completed successfully就说明这次单机安装配置已经成功了。5.3 查看结果作业跑完后查看输出目录cat ~/wordcount/output/*会输出类似hadoop 1 hello 2 world 1这里每行是“单词 出现次数”。WordCount是MapReduce最经典的入门案例它把输入文件里的所有单词统计一遍在Map阶段做拆分计数在Reduce阶段做汇总。单机模式下这个过程全部在本地JVM中完成非常适合理解MapReduce的数据流转。5.4 失败时的排查顺序如果没跑通不要急着卸载重装按下面的顺序排查先看Java环境执行hadoop version能否正常输出。如果不行回去改hadoop-env.sh。确认输出目录不存在如果之前跑过一次再跑一次前记得rm -rf ~/wordcount/output。检查目录权限如果当前用户不是Hadoop安装目录的所有者执行chown -R hadoop:hadoop /opt/hadoop并确认~/wordcount目录可写。看日志Hadoop运行日志在/opt/hadoop/logs/目录下搜索ERROR和Exception关键字。有一种高频报错值得单独说java.lang.NoClassDefFoundError: org/apache/hadoop/crypto或UnsupportedClassVersionError。遇到这种基本可以断定是JDK版本问题。切换回JDK 8并保证hadoop-env.sh和~/.bashrc里的JAVA_HOME都指向同一版本再重新试。6. 非战斗减员清单装完之后的真实坑和后续路线6.1 新手最容易踩的五个坑我把这些年看到的“非战斗减员”整理成一张表希望你能避开症状表面现象根源正确处理WordCount找不到输入文件提示FileNotFoundExceptionfs.defaultFS被写成hdfs://localhost:9000清空或删除core-site.xml里的配置所有命令都提示权限不足Permission denied用root安装后切到普通用户运行统一用户执行chown安装时正常重启后失效hadoop命令找不到环境变量写在某个不生效的文件里统一写在当前用户的~/.bashrc压缩包解压报错CRC错误、tar: Error is not recoverable下载损坏下载后先校验SHA-512一跑就报JDK相关异常NoClassDefFoundError多JDK版本切换混乱固定用OpenJDK 8/11路径写死这张表里第一条最具迷惑性。很多人明明按教程一步步做了却死在一个本不该加的配置上。所以单机模式下遇到问题第一反应应该是“是不是多配了”而不是“是不是少配了”。6.2 从单机到伪分布式改动清单当单机模式已经完全跑通想更深入学习HDFS和YARN下一步就是转向伪分布式。这里给你一个精简改动清单不展开细讲但方向不会错配置SSH localhost免密修改core-site.xml将fs.defaultFS设为hdfs://localhost:9000修改hdfs-site.xml设置dfs.replication为1修改mapred-site.xml设置mapreduce.framework.name为yarn修改yarn-site.xml配置yarn.nodemanager.aux-services为mapreduce_shuffle执行一次hdfs namenode -format用start-dfs.sh和start-yarn.sh启动守护进程用jps验证进程。你会发现伪分布式需要额外配置的东西恰恰是单机模式不需要的。先把单机模式的基础打牢再去碰伪分布式排查思路会清晰很多。6.3 接下来该怎么学如果你已经跑通了WordCount我建议按这个顺序继续第一把官方示例jar包里的其他程序跑一遍比如grep、teragen、terasort。这些程序不一定多实用但能帮你熟悉“提交一个MapReduce作业”的完整流程。第二学会查看日志。Hadoop的日志目录里藏着大量信息很多看起来玄乎的问题只要打开syslog或userlogs看一眼Exception堆栈就能定位。第三开始学HDFS命令。虽然单机模式没有HDFS但你已经可以在本地文件系统上体验hadoop fs的部分命令逻辑。等进了伪分布式再把路径切到HDFS真环境就不容易晕。第四尝试在IDE里写一个最简单的MapReduce程序用hadoop jar提交到本地运行。这一步会让你从“会安装”进步到“会开发”。我自己实际操作下来Hadoop单机安装配置最大的门槛不是命令复杂而是被网上的伪分布式教程带偏。守住一条主线先hadoop version再WordCount最后再碰配置。这三步走稳了后面学伪分布式、学集群搭建才有真正的底气。