Windows 10/11 通过 WSL 2 安装 Hadoop 3.1.3 单机环境完整指南-育师

1. 项目概述：为什么要在Windows上折腾Hadoop？

如果你和我一样，主要工作环境是Windows，但又需要学习、测试或者开发基于Hadoop的大数据应用，那么直接在Windows上安装一个单机版的Hadoop就成了一个绕不开的“必修课”。很多人一听到Hadoop，第一反应就是Linux集群，觉得在Windows上搞这个纯属自找麻烦。但说实话，对于绝大多数开发者、学生或者数据分析师来说，我们需要的并不是一个生产级别的、多节点的高可用集群，而是一个能在本机快速搭建、用于代码调试、功能验证和学习原理的沙箱环境。

Hadoop 3.1.3是一个比较经典的稳定版本，虽然现在有更新的3.2.x、3.3.x，但3.1.3的文档和社区资源非常丰富，踩坑时更容易找到解决方案，对于入门和日常开发测试来说完全够用。在Windows上安装它，核心目的就是模拟一个完整的Hadoop运行环境，让你能够运行MapReduce程序、操作HDFS文件系统，甚至跑一跑Hive、Spark on YARN等上层应用，而无需额外准备Linux服务器或虚拟机，极大提升了学习和开发前期的效率。

当然，Windows并非Hadoop的原生支持平台，所以整个过程会涉及到一些“非标准”操作，比如需要借助一些工具来提供Linux环境下的基础服务。别担心，我会把每一步的原理、可能遇到的坑以及我的解决经验都详细拆解出来。只要你跟着步骤走，保持耐心，在Windows 10或Windows 11上成功跑起Hadoop 3.1.3是完全可以实现的。整个过程，我们追求的不是极致的性能，而是环境的可用性、稳定性和可复现性。

2. 核心思路与前置准备：模拟Linux环境是关键

在Linux上安装Hadoop相对直接，因为其底层依赖（如Shell环境、文件系统权限、原生库）都是现成的。而在Windows上，我们需要一个“桥梁”来满足这些依赖。主流方案有两种：使用Cygwin或使用Windows Subsystem for Linux (WSL)。我这里强烈推荐并详细讲解基于WSL的方案，因为它更接近原生Linux，性能损耗小，且与Windows系统集成度更高，管理起来更方便。

2.1 方案选型：为什么是WSL而不是Cygwin？

Cygwin是一个在Windows上模拟POSIX兼容环境的大型工具集，它通过一个兼容层（cygwin1.dll）将Linux API调用翻译成Windows API。早期很多在Windows上运行Hadoop的教程都基于Cygwin。但它有几个明显缺点：

性能开销：兼容层带来了额外的性能损耗。
路径问题：Cygwin的路径（如/cygdrive/c/Users）与Windows路径（C:\Users）需要转换，在配置Hadoop时容易混淆。
环境复杂：安装包庞大，需要手动选择很多开发包，对新手不友好。

WSL（Windows Subsystem for Linux）则是微软官方提供的、在Windows内核之上运行一个完整的Linux兼容层。WSL 2更是基于轻量级虚拟机技术，提供了完整的Linux内核。它的优势在于：

近乎原生性能：文件I/O、网络等性能接近原生Linux。
无缝交互：可以直接在Windows资源管理器中访问Linux文件系统（\\wsl$），也可以在Linux中通过/mnt/c访问Windows盘符，路径处理清晰。
系统集成好：通过wsl命令在Windows终端（如Windows Terminal）中直接启动Linux Shell，体验流畅。

因此，我们的核心思路就是：在Windows上启用WSL 2并安装一个Linux发行版（如Ubuntu），然后在这个Linux子系统中安装和配置Hadoop。这样，Hadoop实际上是运行在一个“真正的”Linux环境中，只是这个环境被Windows托管了。

2.2 准备工作清单

在开始安装Hadoop之前，我们需要确保Windows环境就绪。请按顺序完成以下检查与安装：

操作系统版本：确保你的Windows 10版本为2004及以上（内部版本19041及以上），或者Windows 11。这是支持WSL 2的最低要求。可以在“设置”->“系统”->“关于”中查看。
启用WSL功能：以管理员身份打开Windows PowerShell或命令提示符，运行以下命令。这会启用“适用于Linux的Windows子系统”和“虚拟机平台”两个可选功能。
```
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
```
执行后务必重启电脑，使更改生效。
设置WSL 2为默认版本：重启后，再次以管理员身份打开PowerShell，运行：
```
wsl --set-default-version 2
```
如果提示WSL 2需要内核更新，请根据提示链接下载并安装“WSL2 Linux内核更新包”。
安装Linux发行版：打开Microsoft Store，搜索“Ubuntu”。建议选择最新的LTS版本，例如“Ubuntu 22.04 LTS”。点击获取并安装。安装完成后，从开始菜单启动Ubuntu，它会完成初始设置，要求你创建用户名和密码。这个用户名和密码很重要，后续会频繁使用。
验证WSL版本：安装好Ubuntu后，在Windows PowerShell中运行wsl -l -v，你应该能看到安装的发行版（如Ubuntu-22.04）及其版本（VERSION列应为2）。

注意：如果你的网络环境访问Microsoft Store有困难，也可以手动下载Linux发行版的Appx包进行离线安装。但通过Store安装是最简单的方式。

至此，你的Windows已经拥有了一个完整的Linux运行环境。接下来所有的操作，除非特别说明，都将在WSL中的Ubuntu终端里进行。

3. 详细安装与配置步骤实录

现在，我们进入WSL的Ubuntu环境，开始Hadoop的安装之旅。打开Windows Terminal（推荐）或PowerShell，输入wsl或ubuntu命令即可进入Ubuntu命令行。

3.1 基础环境配置：用户、SSH与Java

Hadoop分布式运行需要SSH免密登录，即使单机模式，某些脚本也会检查SSH服务。同时，Hadoop是Java编写的，所以JDK是必须的。

3.1.1 更新系统与创建Hadoop专用用户

虽然可以使用安装时创建的个人用户，但为了环境隔离和避免权限问题，我习惯为Hadoop创建一个专用用户。

# 首先更新软件包列表 sudo apt update sudo apt upgrade -y # 创建名为 hadoop 的用户，并设置密码（按提示输入） sudo adduser hadoop

系统会提示你设置密码和填写一些信息，密码可以简单点如hadoop，其他信息可以直接回车跳过。

接下来，我们需要给这个新用户添加sudo权限，方便后续安装软件：

sudo usermod -aG sudo hadoop

然后，切换到hadoop用户进行操作：

su - hadoop

输入你刚才设置的密码。你会发现命令行提示符的用户名变成了hadoop。

3.1.2 配置SSH免密登录

Hadoop的启动脚本（如start-dfs.sh,start-yarn.sh）需要通过SSH连接到各个节点（包括本地）来启动守护进程。配置免密登录后，这些脚本才能无干预运行。

# 1. 安装SSH服务器和客户端 sudo apt install openssh-server openssh-client -y # 2. 生成SSH密钥对。一路回车，使用默认位置和不设置密码。 ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa # 3. 将公钥追加到授权密钥文件，并设置正确的权限 cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys chmod 0600 ~/.ssh/authorized_keys # 4. 测试SSH连接到本机是否不需要密码 ssh localhost

第一次SSH连接时，会询问是否将主机加入已知主机列表，输入yes。如果配置成功，你应该能直接登录到本机而不需要输入密码。执行exit命令退出SSH会话，回到原来的终端。

实操心得：如果ssh localhost仍然要求输入密码，99%的原因是~/.ssh目录或authorized_keys文件的权限不对。确保.ssh目录权限为700 (chmod 700 ~/.ssh)，authorized_keys文件权限为600。

3.1.3 安装Java (JDK 8)

Hadoop 3.1.3官方兼容JDK 8。虽然更高版本也可能工作，但为了最大程度避免兼容性问题，我们安装OpenJDK 8。

sudo apt install openjdk-8-jdk -y

安装完成后，验证安装：

java -version

你应该看到类似openjdk version "1.8.0_392"的输出。接下来需要配置JAVA_HOME环境变量。首先找到JDK的安装路径：

update-alternatives --config java

记下路径，例如/usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java。那么JAVA_HOME就是其上级目录的上级目录：/usr/lib/jvm/java-8-openjdk-amd64。

编辑hadoop用户的bash配置文件：

nano ~/.bashrc

在文件末尾添加以下行（请根据你实际查到的路径修改）：

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 export PATH=$PATH:$JAVA_HOME/bin

保存退出（Ctrl+X，然后按Y，再回车）。让配置立即生效：

source ~/.bashrc

验证JAVA_HOME：

echo $JAVA_HOME

应该正确输出你设置的路径。

3.2 Hadoop 3.1.3 安装与核心配置

3.2.1 下载与解压

我们切换到hadoop用户的家目录进行操作。

cd ~

使用wget从Apache镜像下载Hadoop 3.1.3二进制包。如果下载速度慢，可以先用浏览器从 Apache Hadoop官网找到下载链接，然后在WSL里用wget加链接下载。

wget https://archive.apache.org/dist/hadoop/common/hadoop-3.1.3/hadoop-3.1.3.tar.gz

下载完成后，解压并移动到合适的目录。我习惯放在/usr/local下，但为了权限方便，我们先解压到当前用户目录，然后建立软链接或直接配置环境变量。

tar -xzvf hadoop-3.1.3.tar.gz mv hadoop-3.1.3 ~/hadoop # 重命名并移动到用户目录下，方便管理

现在，Hadoop的主目录就是/home/hadoop/hadoop。

3.2.2 配置环境变量

同样编辑~/.bashrc文件：

nano ~/.bashrc

在文件末尾添加Hadoop相关环境变量：

export HADOOP_HOME=/home/hadoop/hadoop export HADOOP_INSTALL=$HADOOP_HOME export HADOOP_MAPRED_HOME=$HADOOP_HOME export HADOOP_COMMON_HOME=$HADOOP_HOME export HADOOP_HDFS_HOME=$HADOOP_HOME export YARN_HOME=$HADOOP_HOME export HADOOP_COMMON_LIB_NATIVE_DIR=$HADOOP_HOME/lib/native export PATH=$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin

保存退出，并使其生效：

source ~/.bashrc

验证：输入hadoop version，应该能看到Hadoop 3.1.3的版本信息。

3.2.3 修改Hadoop配置文件（最关键的一步）

Hadoop的配置文件位于$HADOOP_HOME/etc/hadoop/目录下。我们需要修改以下几个核心文件。请务必仔细核对每项配置。

1.hadoop-env.sh：配置Hadoop运行环境。

cd $HADOOP_HOME/etc/hadoop nano hadoop-env.sh

找到export JAVA_HOME=这一行，取消注释，并设置为我们之前找到的JDK路径：

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

还可以在同一文件中设置Hadoop的日志目录等，但默认即可。

2.core-site.xml：Hadoop核心配置，定义文件系统默认的URI和临时目录。

nano core-site.xml

在<configuration>标签内添加：

<configuration> <property> <name>fs.defaultFS</name> <value>hdfs://localhost:9000</value> <description>HDFS的默认访问地址和端口</description> </property> <property> <name>hadoop.tmp.dir</name> <value>/home/hadoop/hadoopdata/tmp</value> <description>Hadoop临时文件存储目录，非常重要！NameNode和DataNode的数据目录会基于此生成。</description> </property> </configuration>

注意：hadoop.tmp.dir的路径需要提前创建，并且hadoop用户要有读写权限。我们稍后创建。

3.hdfs-site.xml：HDFS相关配置，如副本数、数据存储路径。

nano hdfs-site.xml

在<configuration>标签内添加。因为是单机模式，我们把副本数设为1，并明确指定NameNode和DataNode的数据存储目录。

<configuration> <property> <name>dfs.replication</name> <value>1</value> <description>数据块副本数量，单机模式设为1</description> </property> <property> <name>dfs.namenode.name.dir</name> <value>file:///home/hadoop/hadoopdata/dfs/name</value> <description>NameNode元数据存储路径</description> </property> <property> <name>dfs.datanode.data.dir</name> <value>file:///home/hadoop/hadoopdata/dfs/data</value> <description>DataNode数据块存储路径</description> </property> </configuration>

4.mapred-site.xml：MapReduce框架配置，指定使用YARN作为资源调度器。

nano mapred-site.xml

<configuration> <property> <name>mapreduce.framework.name</name> <value>yarn</value> <description>指定MapReduce作业运行在YARN框架上</description> </property> </configuration>

5.yarn-site.xml：YARN资源管理器配置。

nano yarn-site.xml

<configuration> <property> <name>yarn.nodemanager.aux-services</name> <value>mapreduce_shuffle</value> <description>NodeManager上运行的附属服务，MapReduce需要shuffle服务</description> </property> <property> <name>yarn.nodemanager.aux-services.mapreduce_shuffle.class</name> <value>org.apache.hadoop.mapred.ShuffleHandler</value> </property> <property> <name>yarn.resourcemanager.hostname</name> <value>localhost</value> <description>ResourceManager运行的主机名</description> </property> </configuration>

3.2.4 创建必要的目录并设置权限

根据配置文件中的路径，创建所有需要的目录：

mkdir -p ~/hadoopdata/tmp mkdir -p ~/hadoopdata/dfs/name mkdir -p ~/hadoopdata/dfs/data

确保hadoop用户拥有这些目录的所有权：

chown -R hadoop:hadoop ~/hadoopdata chmod -R 755 ~/hadoopdata

4. 启动、验证与基础操作

经过漫长的配置，终于到了激动人心的启动时刻。

4.1 格式化HDFS

这是第一次启动前必须且只能执行一次的操作，它会初始化NameNode的元数据存储目录。如果后续启动失败需要重新格式化，务必先彻底删除~/hadoopdata/dfs/name和~/hadoopdata/dfs/data目录下的所有内容，否则可能导致数据不一致。

hdfs namenode -format

看到类似 “Storage directory /home/hadoop/hadoopdata/dfs/name has been successfully formatted” 的提示，说明格式化成功。

4.2 启动Hadoop守护进程

Hadoop提供了便捷的脚本启动所有服务。我们先启动HDFS。

start-dfs.sh

这个脚本会启动NameNode、DataNode和SecondaryNameNode。你会看到一些启动日志。用jps命令（Java进程查看工具）来检查是否启动成功：

jps

你应该能看到至少包含NameNode,DataNode,SecondaryNameNode的进程列表。

接下来启动YARN：

start-yarn.sh

再次运行jps，应该会多出ResourceManager和NodeManager进程。

4.3 验证服务与Web UI访问

Hadoop各个组件都提供了Web管理界面，这是验证服务是否正常运行的直观方式。

HDFS NameNode UI: 在Windows的浏览器中打开http://localhost:9870。注意：Hadoop 3.x 默认NameNode的Web端口从50070改为了9870。如果页面能打开，并显示Overview、Datanodes等信息，说明HDFS启动成功。
YARN ResourceManager UI: 打开http://localhost:8088。这里可以查看集群资源使用情况和提交的作业。

重要提示：由于Hadoop服务运行在WSL的Linux环境中，而浏览器在Windows端，localhost能互通是因为WSL 2做了网络桥接。如果无法访问，请检查WSL 2的防火墙设置，或者尝试在WSL内部用curl http://localhost:9870测试服务是否在监听。

4.4 基础HDFS操作体验

现在，让我们在命令行中体验一下HDFS的基本操作，感受一下这个“分布式”文件系统。

# 1. 在HDFS上创建一个用户目录（类似于Linux的/home） hdfs dfs -mkdir -p /user/hadoop # 2. 从本地文件系统上传一个文件到HDFS。先创建一个测试文件。 echo "Hello, Hadoop on Windows with WSL!" > ~/test.txt hdfs dfs -put ~/test.txt /user/hadoop/ # 3. 查看HDFS上的文件列表 hdfs dfs -ls /user/hadoop # 4. 查看HDFS上文件的内容 hdfs dfs -cat /user/hadoop/test.txt # 5. 从HDFS下载文件到本地 hdfs dfs -get /user/hadoop/test.txt ~/test_download.txt cat ~/test_download.txt

如果这些命令都能成功执行，那么恭喜你，一个单机版的Hadoop已经在你的Windows上完美运行起来了！

4.5 运行一个示例MapReduce作业

Hadoop自带了一些示例JAR包，我们可以运行经典的WordCount程序来测试整个MapReduce on YARN的流程是否通畅。

# 1. 在HDFS上创建输入目录，并上传一些文本文件作为输入。 # 我们可以用Hadoop的配置文件作为输入源。 hdfs dfs -mkdir /user/hadoop/input hdfs dfs -put $HADOOP_HOME/etc/hadoop/*.xml /user/hadoop/input/ # 2. 运行WordCount示例程序。 # hadoop-mapreduce-examples-3.1.3.jar 包含了各种示例。 # 指定输入目录和输出目录（输出目录必须不存在）。 hadoop jar $HADOOP_HOME/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.1.3.jar wordcount /user/hadoop/input /user/hadoop/output # 3. 观察YARN Web UI (http://localhost:8088)，你会看到一个新的应用被提交和运行。 # 等待作业完成。完成后，查看输出结果。 hdfs dfs -cat /user/hadoop/output/part-r-00000 | head -20

你会看到各个单词及其出现的次数。至此，你的Hadoop环境已经具备了完整的HDFS存储和MapReduce计算能力。

5. 常见问题与故障排查实录

在Windows+WSL环境下安装Hadoop，虽然步骤清晰，但依然可能遇到一些特有的问题。下面是我在多次安装中总结的“坑”和解决方案。

5.1 WSL相关网络与权限问题

问题1：Hadoop Web UI (9870, 8088) 在Windows浏览器中无法访问。

排查：首先在WSL内部用curl http://localhost:9870测试。如果WSL内能访问，说明服务正常，是Windows到WSL的网络问题。
解决：
1. 获取WSL 2的IP地址：在WSL中运行ip addr show eth0 | grep inet。你会看到一个类似172.x.x.x的IP。
2. 在Windows浏览器中，用这个IP地址替换localhost访问，如http://172.x.x.x:9870。
3. 更一劳永逸的方法：在WSL中编辑Hadoop配置文件，将localhost绑定到0.0.0.0，或者直接使用WSL的主机名。但最简单还是用IP访问。

问题2：启动脚本报错 “Connection refused” 或 SSH相关错误。

排查：执行ssh localhost是否真的免密。检查~/.ssh目录权限（必须700），authorized_keys文件权限（必须600）。
解决：确保SSH服务正在运行：sudo service ssh status。如果没运行，启动它：sudo service ssh start。还可以将SSH服务设为开机自启：sudo systemctl enable ssh（WSL 2可能需要额外配置systemd支持）。

5.2 Hadoop启动与运行报错

问题3：执行start-dfs.sh后，jps看不到 NameNode 或 DataNode。

排查：查看日志！日志是排错的生命线。Hadoop的日志默认在$HADOOP_HOME/logs/目录下。查看最新的对应日志文件，如hadoop-hadoop-namenode-<主机名>.log。
常见原因与解决：
- 端口被占用：Hadoop默认使用9000、9870、50070等端口。用netstat -tlnp | grep :9000查看。如果被占用，可以修改core-site.xml中的fs.defaultFS端口，或者停止占用端口的程序。
- 目录权限不足：确保hadoop.tmp.dir以及HDFS数据目录（dfs.namenode.name.dir,dfs.datanode.data.dir）的所属用户和组是hadoop，并且有读写权限。用ls -ld <目录路径>检查。
- 多次格式化导致ClusterID不一致：如果DataNode的VERSION文件中的clusterID与NameNode的不一致，DataNode就无法启动。解决方法：停止所有服务，删除dfs.name.dir和dfs.data.dir目录下的所有内容，重新格式化NameNode (hdfs namenode -format)，再启动。

问题4：运行MapReduce作业失败，YARN Web UI显示作业状态为 FAILED。

排查：点击失败的应用ID，进入应用详情页，查看Logs链接，特别是stderr和syslog。
常见原因：
- 内存不足：WSL默认分配的内存可能较小。可以在Windows用户目录下的.wslconfig文件（如C:\Users\<你的用户名>\.wslconfig）中增加内存限制：
```
[wsl2] memory=4GB # 根据你的机器情况调整，建议至少4G processors=2
```
  修改后，在PowerShell中执行wsl --shutdown关闭WSL，再重新打开。
- 本地库（Native Library）问题：某些Hadoop功能依赖本地库。可以尝试在$HADOOP_HOME/etc/hadoop/hadoop-env.sh中添加export HADOOP_OPTS="-Djava.library.path=$HADOOP_HOME/lib/native"。或者直接忽略，对于基础WordCount影响不大。

5.3 日常使用与维护技巧

停止服务：与启动脚本对应，使用stop-yarn.sh和stop-dfs.sh来优雅地停止服务。
重置环境：如果你想从头再来，最干净的方式是：
1. 停止所有Hadoop进程。
2. 删除Hadoop数据目录：rm -rf ~/hadoopdata
3. 删除Hadoop安装目录（如果你想重装）：rm -rf ~/hadoop
4. 重新解压、配置、格式化、启动。
资源清理：长期使用后，HDFS会存储数据，MapReduce作业会产生中间文件。定期清理不用的数据：hdfs dfs -rm -r /user/hadoop/output（删除输出目录）。对于YARN的作业历史日志，可以配置日志聚合并设置保留时间。

在Windows上通过WSL运行Hadoop，本质上是在一个高度集成的Linux容器中运行它。这带来了近乎原生的体验，同时又保留了Windows主系统的便利性。对于学习、开发和轻量级测试而言，这套方案已经非常成熟和可靠。最大的挑战往往来自于最初的环境配置和网络设置，一旦跨过这个坎，后面就是海阔天空。