hadoop 3.x 必须使用 java 8 或 11，禁用 17+；fs.defaultfs 必须设为 hdfs://localhost:9000；ssh 需对 localhost 免密；首次启动前必须执行 hdfs namenode -format。
Java版本必须是8或11，别用17+或OpenJDK 21
Hadoop 3.x 官方明确只支持 Java 8 和 Java 11（openjdk-11-jdk 或 jdk-11.0.x），用 Java 17+ 会直接报 UnsupportedClassVersionError 错误，启动 hdfs namenode -format 或 start-dfs.sh 时失败。
常见踩坑点：
- Ubuntu/Debian 系统默认装的是
openjdk-17-jdk，得先卸载：sudo apt remove openjdk-17-jdk - CentOS/RHEL 用
yum remove java-17-openjdk*，再装java-11-openjdk-devel -
JAVA_HOME必须指向 JDK 根目录（如/usr/lib/jvm/java-11-openjdk-amd64），不能只写/usr/bin/java - 验证方式：运行
java -version和echo $JAVA_HOME，两者输出要一致且版本号含11.0.或1.8.0_
配置文件里 fs.defaultFS 必须写成 hdfs://localhost:9000，不是 file:/// 或 localhost:9000
这是最常出错的配置项。Hadoop 启动后找不到 NameNode，日志里反复出现 Connection refused，大概率就是这里写错了。
core-site.xml 中必须严格按如下格式写：
<configuration><property><name>fs.defaultFS</name><value>hdfs://localhost:9000</value></property></configuration>
注意三点：
- 协议头必须是
hdfs://，不是file://（那是本地模式）、也不是http:// - 主机名必须是
localhost（伪分布式）或真实 hostname（集群），不能留空或写127.0.0.1（某些版本解析异常） - 端口必须是
9000，这是 HDFS 默认 RPC 端口；改了就得同步改hdfs-site.xml里的dfs.namenode.rpc-address
SSH 免密登录必须对本机生效，连 localhost 都要能无密码 ssh
Hadoop 启动脚本（如 start-dfs.sh）内部会调用 ssh localhost 启动进程。哪怕单机伪分布式，也必须让 ssh localhost 不输密码——否则卡在 “starting namenode…” 就不动了。
实操要点：
- 先确认
ssh命令可用：which ssh、ssh -V - 生成密钥对：
ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa（-P ''表示空密码） - 追加公钥：
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys - 设权限：
chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys - 测试：
ssh localhost成功退出即 OK；失败就看ssh -v localhost输出里卡在哪一步
第一次启动前必须执行 hdfs namenode -format，且只能执行一次
不格式化就启动，namenode 日志里会报 Failed to load image from，然后自动退出。格式化本质是初始化元数据目录（默认 $HADOOP_HOME/dfs/name），生成 VERSION 文件和空 current/ 目录。
关键提醒：
- 执行前确保
hdfs-site.xml已配置dfs.namenode.name.dir（推荐绝对路径，如/app/hadoop/dfs/name） - 执行命令必须用 Hadoop 用户（比如
hadoop），不能用root，否则后续启动进程权限不一致 - 格式化成功后，
ls -l $HADOOP_HOME/dfs/name/current/应看到VERSION、seen_txid等文件 - 如果二次格式化，旧数据全丢，且需手动清空
dfs/data目录，否则 datanode 启动失败
fs.defaultFS 协议写法、SSH 对 localhost 的免密、以及 format 是否真成功这四点。每一步验证输出比“照着教程敲完”更关键。
