精读君如果你搜过 Hadoop 安装教程，应该见过那种一上来就让你准备三台虚拟机、配置免密登录、格式化 NameNode 的文章。但我个人觉得，很多第一次接触 Hadoop 的人根本不需要这么重型的开局——你只是想在本地把 MapReduce 跑通，弄清安装目录、配置文件、执行命令是怎么回事。真正适合这种场景的，是 Hadoop 的单机模式（Standalone Mode / Local Mode），也就是标题里说的“单机（非分布式）配置”。这篇文章我会从零开始，把 Hadoop 3.3.6 在 Ubuntu 系统上的下载、环境变量、验证、跑通自带 wordcount 示例的完整过程拆开讲，所有命令都按“能直接复制”的标准来写。如果你机器上装的是 CentOS、macOS 或者 Windows 的 WSL 环境，也只要把包管理器相关命令换一下，整体思路完全一致。
说句实在话，单机模式是三种运行方式里最容易被误解的一个：它默认就在发行包里，几乎不需要配置，但很多人因为照抄了“伪分布式”或“集群”教程，反而把它搞复杂了。这篇教程会明确告诉你单机模式下哪些文件该碰、哪些文件千万别碰，以及如何用一条命令验证你的 Hadoop 确实能干活。全文主要基于 Linux 下的常规路径 /usr/local/hadoop，并且会穿插一些我实际安装中遇到的报错和解决办法。
1. 装 Hadoop 之前，先搞清楚你要的到底是哪种“单机”
1.1 Hadoop 三种部署模式，别再被名词绕晕
Hadoop 官方把部署模式分成三种：本地模式、伪分布式、完全分布式。很多教程在开头就会混用“单机”“伪分布式”“集群”这些词，导致新手一开始就跑偏。
本地模式（Standalone Mode） 是 Hadoop 解压后的默认状态，不需要修改任何配置文件，也不启动 NameNode、DataNode、ResourceManager 这些守护进程。MapReduce 作业会在本机的同一个 Java 进程里通过 LocalJobRunner 直接执行，输入输出都走本地文件系统，不走 HDFS。
伪分布式模式（Pseudo-Distributed Mode） 是在一台机器上分别用独立 Java 进程模拟 HDFS 的 NameNode/DataNode 以及 YARN 的 ResourceManager/NodeManager。这个模式下你才需要修改 core-site.xml、hdfs-site.xml 等文件，才能执行 start-dfs.sh、start-yarn.sh。
完全分布式模式（Fully Distributed Mode） 才是生产环境里常说的“集群”，多台机器各司其职，HDFS 和 YARN 分散在不同节点上。
三种模式的区别可以用一张表总结：
| 模式 | 是否修改配置 | 守护进程 | 文件系统 | 适用场景 |
|---|---|---|---|---|
| 本地模式 / 单机 | 基本不用改 | 无 | 本地文件系统 | 学习 MapReduce、调试程序、跑通 Demo |
| 伪分布式 | 修改多个 XML | 单机多进程 | HDFS（单节点） | 模拟集群、学习 HDFS 和 YARN 操作 |
| 完全分布式 | 多机分别配置 | 多机多进程 | HDFS（多节点） | 生产环境、大规模数据处理 |
1.2 单机模式能做什么，不能做什么
单机模式能干的事情其实不少。它最大的价值是让你在没有集群压力的情况下，快速验证 Hadoop 环境是否可用、MapReduce 代码是否能运行。自带的 hadoop-mapreduce-examples 包里有 wordcount、grep、terasort 等经典示例，本地模式通通能跑。我自己在帮别人排查 Hadoop 环境问题的时候，也经常先用单机模式跑一个 wordcount，确认 Java 版本、环境变量、jar 包完整度都正常，再往更复杂的模式上排查。
但单机模式也有非常明确的边界：它不使用 HDFS，所以你看不到 hdfs:// 开头的地址，也不应该执行 start-dfs.sh、hdfs namenode -format 这类命令；它不启动 YARN，所以不要指望访问 8088 端口看 ResourceManager 页面；它不产生任何后台常驻 Java 进程，所以用 jps 命令查看时，除了 jps 自己，不应该看到 NameNode、DataNode 这些进程。如果你需要的是“能在网页上看到 DataNode 存活”这种效果，那你要装的是伪分布式，不是本文的单机模式。
所以动手前先确认一件事：你是想验证 Hadoop 本身能跑，还是想学 HDFS 的存储和集群调度？如果是前者，继续往下看；如果是后者，单机模式只适合当成你整个学习路径的第一级台阶。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：JDK 版本和下载源是隐藏重灾区
2.1 JDK 版本是第一道关卡，Hadoop 3.x 建议 Java 8 或 11
Hadoop 是用 Java 写的，所以本机必须要有 JDK。很多人在这一步就开始翻车，不是因为没装 Java，而是装了一个 Hadoop 不兼容的版本。Hadoop 3.3.x 官方支持 Java 8 和 Java 11，不建议直接用 Java 17 或更高版去跑，容易遇到模块化相关的兼容问题。如果你只是为了跑 Hadoop，不要贪新，装一个 OpenJDK 11 最省心。
先检查系统里有没有 Java：
bash复制java -version
如果提示找不到命令，Ubuntu/Debian 系可以执行：
bash复制sudo apt update
sudo apt install -y openjdk-11-jdk
CentOS/RHEL 系则用：
bash复制sudo yum install -y java-11-openjdk-devel
装完再执行 java -version 确认能输出版本号。如果你系统里有多套 JDK，可以用下面的命令切换默认版本：
bash复制sudo update-alternatives --config java
这里有一个新手常踩的坑：java -version 能执行，不代表 Hadoop 能找到 JAVA_HOME。Hadoop 启动脚本会去读取 JAVA_HOME 这个环境变量，而不是简单地在 PATH 里找 java。所以我通常在配置环境变量前，先用 readlink -f $(which java) 定位真实路径，比如输出是 /usr/lib/jvm/java-11-openjdk-amd64/bin/java，那它的上一级目录 /usr/lib/jvm/java-11-openjdk-amd64 就是要填进 JAVA_HOME 的值。
2.2 下载 Hadoop 安装包：优选镜像站，千万别下源码包
Hadoop 的官方下载入口在 Apache 官网，页面会列出当前推荐的稳定版本。国内网络环境下，我更推荐用清华镜像或阿里云镜像下载，速度快很多。镜像目录一般在：
text复制https://mirrors.tuna.tsinghua.edu.cn/apache/hadoop/common/
进入后选择对应版本目录，比如 hadoop-3.3.6/，然后下载 hadoop-3.3.6.tar.gz 这个文件。注意文件名里带不带 src：hadoop-3.3.6-src.tar.gz 是源码包，需要自己编译，不是拿来直接安装的；我们要的是编译好的二进制包，也就是不带 src 的那个 tar.gz。
下载完成后可以用 tar -tzf hadoop-3.3.6.tar.gz | head 快速确认文件完整性，能正常列出文件名就说明压缩包没坏。如果你的网络下载经常中断，建议下完后校验一下文件大小，或者用 md5sum 和官方提供的校验值对比一下，避免解压到一半报错。
2.3 安装目录和权限：不要用 root 直接跑 Hadoop
我习惯把 Hadoop 统一放在 /usr/local/hadoop 这个路径下，一方面路径短，后面配置命令写起来方便；另一方面这个目录在 Linux 的 FHS 规范里本来就是放本地安装软件的，后续从单机模式往伪分布式、集群迁移时不会和用户目录纠缠。
假设下载好的 tar.gz 在 ~/downloads 下，执行：
bash复制cd ~/downloads
tar -xzf hadoop-3.3.6.tar.gz
sudo mv hadoop-3.3.6 /usr/local/hadoop
sudo chown -R $USER:$USER /usr/local/hadoop
第三步把属主改成当前普通用户，这一步非常重要。如果不改，后面用普通用户执行 Hadoop 命令时，可能会因为无法写入 /usr/local/hadoop 而产生各种 Permission denied 问题。为什么我建议不要用 root 直接跑？因为 Hadoop 很多脚本对 root 用户有额外限制，而且一旦你习惯用 root 执行，后面到了多用户环境或者生产环境会非常被动。老老实实开一个带 sudo 权限的普通用户来学 Hadoop，能少踩很多坑。
如果你不想动用 sudo 权限，也可以直接解压到自己的家目录，比如 ~/hadoop，效果完全一样。只是后面的 HADOOP_HOME 和所有引用路径都要同步改。
3. 一步步安装配置：环境变量和目录结构验证
3.1 配置 JAVA_HOME、HADOOP_HOME 和 PATH
Hadoop 不像某些软件装完就能直接用，它需要你告诉系统“Hadoop 装在哪”和“Java 装在哪”。最推荐的做法是把环境变量写进当前用户的 ~/.bashrc，而不是 /etc/profile。理由很简单：~/.bashrc 是每个终端会话都会加载的，改完 source 一下立刻生效，不会影响整个系统的其他用户，也更适合个人开发环境。
用 vim、nano 或任意文本编辑器打开 ~/.bashrc，在文件末尾追加：
bash复制export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export HADOOP_HOME=/usr/local/hadoop
export PATH=$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin
如果你不确定 JAVA_HOME 的具体路径，先用 readlink -f $(which java) 查一下真实地址，再把最后的 /bin/java 去掉就是 JAVA_HOME 的值。$HADOOP_HOME/bin 是 Hadoop 核心命令所在目录，比如 hadoop、hdfs；$HADOOP_HOME/sbin 里面是 start-dfs.sh、stop-dfs.sh 这类管理脚本。单机模式用不到 sbin，但把两个目录都加进 PATH，以后想升级成伪分布式就不用再改一遍环境变量。
保存后执行：
bash复制source ~/.bashrc
这时可以检查一下变量是否生效：
bash复制echo $JAVA_HOME
echo $HADOOP_HOME
which hadoop
which hadoop 能输出 /usr/local/hadoop/bin/hadoop 就说明 PATH 配置正确。
3.2 验证安装：执行 hadoop version 会出现什么
环境变量配好后的第一道验证命令是：
bash复制hadoop version
正常情况下会输出类似这样的内容：
text复制Hadoop 3.3.6
Java version: 11.0.x
能看到 Hadoop 版本号，说明 JDK、HADOOP_HOME、PATH 这三者已经串起来了。如果终端提示 hadoop: command not found，大概率是 source ~/.bashrc 没有执行，或者环境变量里 HADOOP_HOME 写错了路径，先别急着排查别的，回到上一步重新检查。
还有一个小提示：部分 Hadoop 版本在输出版本信息前后会打印一行 WARN，内容是找不到 native-hadoop library。这是找不到本地 native 库的警告，在单机模式下完全不影响使用，不需要去处理。只有当你跑一些对性能敏感的本地库操作时，才需要考虑安装对应的 native 支持，初学阶段直接忽略即可。
3.3 单机模式不需要启动任何服务，那怎样才算“装好了”
很多新手装完 Hadoop 后会习惯性地敲 start-dfs.sh，这其实是把单机模式和伪分布式搞混了。单机模式下根本不应该去启动 HDFS 或 YARN 服务，即使你执行了 start-dfs.sh，也会因为没有配置对应的 namenode 目录和 hdfs-site.xml 而报错，或者启动出一些半吊子进程让你更难排查。
单机模式的“安装完成”标志，其实就两件事：第一，hadoop version 能正常输出版本号；第二，能成功跑通一个自带的 MapReduce 示例。前者证明环境没问题，后者证明计算流程能真正走通。你可以用 jps 命令看一下当前 Java 进程，单机模式下只会有 jps 自己，不会看到 NameNode、DataNode 之类的名字。这不是安装失败，恰恰是正常状态。
等你确认 Hadoop 版本没问题，再去 $HADOOP_HOME/etc/hadoop 目录下看一圈，里面会有 core-site.xml、hdfs-site.xml、mapred-site.xml、yarn-site.xml 等文件。这一眼是为下一步做准备的，但先不要急着改。
4. 别急着改那堆 XML：单机模式默认配置就是最合适的
4.1 集群教程里常改的四个文件，在单机模式下都是多余动作
网上大量“Hadoop 安装与配置”教程，在解压完后就立刻让人去改 core-site.xml，把 fs.defaultFS 改成 hdfs://localhost:9000，还让人改 hdfs-site.xml 设置副本数、改 mapred-site.xml 指定 YARN，改 yarn-site.xml 配置调度器。这套动作是伪分布式或完全分布式才需要的。如果按照集群教程走一遍单机安装，你会发现命令能执行，但行为变得非常奇怪，甚至本地模式那种“轻量”的优势完全消失。
为什么？因为单机模式下 Hadoop 走的是默认值：文件系统默认是 file:///，也就是本地文件系统；MapReduce 框架默认是 local，也就是 LocalJobRunner。此时你不需要告诉它任何额外信息。你如果把 fs.defaultFS 改成 hdfs://localhost:9000，那么在不启动 HDFS 的情况下，跑示例反而会因为连不上 NameNode 而失败，白白增加排查难度。
4.2 单机模式下真正值得检查的是 hadoop-env.sh 里的 JAVA_HOME
虽然本文的主要配置动作都在 ~/.bashrc 里完成了，但有一个文件需要单独拿出来讲：$HADOOP_HOME/etc/hadoop/hadoop-env.sh。这个文件是 Hadoop 所有启动脚本都会加载的环境变量文件，里面会定义 JAVA_HOME、HADOOP_HOME 等变量。
在部分系统上，Hadoop 启动脚本能读取到终端会话里的 JAVA_HOME，所以不改也能跑。但在某些通过 sudo 切换用户、或者在 systemd 环境里执行 Hadoop 的场景下，终端里 export 的变量可能不会传递进去，导致报错 Error: JAVA_HOME is not set and could not be found。
如果遇到这种报错，解决方案是在 hadoop-env.sh 里把 JAVA_HOME 写死：
bash复制export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
修改后执行 hadoop version 再验证一次。虽然对单机模式来说这不是必须步骤，但我个人建议你顺手写上，利大于弊，能让以后任何脚本调用 Hadoop 时都不依赖当前 shell 的临时变量。唯一的坑是，编辑这个文件时不要多余的空格和引号，比如 export JAVA_HOME = /path 这种写法在 shell 里是错的，很多复制粘贴教程里的排版问题就是这么来的。
4.3 理解 file:/// 和 hdfs:/// 的区别，才能理解单机模式
单机模式跑 MapReduce 时，输入路径和输出路径都填的是本地系统路径。比如 /home/user/input 就是实实在在的 Linux 目录，你可以用 ls 直接看到文件。而伪分布式或集群环境下，你通常需要先执行 hdfs dfs -put 把文件上传到 HDFS，然后在命令行写 hdfs:///input 这类路径。这就是为什么很多照着集群教程操作的人会在单机模式下懵掉：明明输入文件就在本地，程序却告诉你文件不存在，或者反过来，命令执行完却不知道结果被写到哪里去了。
我的建议是：在单机模式下，所有路径都按普通 Linux 路径来理解和操作。目录不存在就用 mkdir -p 创建，输出目录重复了就 rm -rf 删掉，别把 HDFS 的命令习惯带进来。等你切换到伪分布式模式，再重新建立“先 put 到 HDFS、再从 HDFS 读结果”的心智模型。
5. 跑通第一个 MapReduce 任务：wordcount 全流程演示
5.1 准备输入数据：直接在本地创建文件
跑通 Hadoop 自带示例是验证安装的黄金标准。我选 wordcount 作为第一个 MapReduce 作业，因为它逻辑最简单，输入输出都很直观，几乎每一本大数据入门教材都会讲。
先建一个专门