只要搜过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 8：
sudo 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，这个配置在单机模式下是帮倒忙。设置了它之后，你再用本地路径提交WordCount，Hadoop会把这个路径当成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找不到输入文件 | 提示FileNotFoundException | fs.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，最后再碰配置。这三步走稳了，后面学伪分布式、学集群搭建，才有真正的底气。
