一、依赖缺失与类路径错误1. NoClassDefFoundError: com/ctc/wstx/io/InputBootstrapper现象Exception in thread main java.lang.NoClassDefFoundError: com/ctc/wstx/io/InputBootstrapper Caused by: java.lang.ClassNotFoundException: com.ctc.wstx.io.InputBootstrapper原因Hadoop 客户端解析 XML 配置文件需要 Woodstox 库但项目未引入该依赖。解决Maven 项目在pom.xml中添加dependency groupIdcom.fasterxml.woodstox/groupId artifactIdwoodstox-core/artifactId version5.4.0/version /dependency更省心的方式是直接引入完整客户端dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version你的Hadoop版本/version /dependency若使用 Gradle 或手动管理 jar记得把hadoop-client或woodstox-core放入 classpath。2. UnsupportedFileSystemException: No FileSystem for scheme hdfs现象org.apache.hadoop.fs.UnsupportedFileSystemException: No FileSystem for scheme hdfs原因虽然添加了hadoop-common但缺少 HDFS 客户端的具体实现hadoop-hdfs-client无法识别hdfs://协议。解决确认项目中已包含dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-hdfs-client/artifactId version3.3.6/version /dependency如果 Maven 仓库网络不佳可直接下载对应 jar 并添加到 Module 的依赖中。二、文件路径与配置文件错误3. FileNotFoundException: 本地文件路径解析错误现象java.io.FileNotFoundException: File E:Hadoop/testupload.txt代码里明明写的是d:/testupload.txt却变成了带冒号的错误路径。原因Hadoop 的Path在 Windows 下若不加协议前缀可能被当成相对路径或解析错误。解决使用标准 URI 格式new Path(file:///D:/testupload.txt)。或者用 Java 的File生成 URInew Path(new File(D:/testupload.txt).toURI().toString());4. 启动时报“JAVA_HOME is not set”现象执行start-dfs.sh时从节点上出现Error: JAVA_HOME is not set and could not be found.原因Hadoop 脚本通过 SSH 远程执行命令不会加载.bashrc或/etc/profile中的环境变量。解决在所有节点的$HADOOP_HOME/etc/hadoop/hadoop-env.sh中硬编码 Java 路径export JAVA_HOME/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.392.b08-2.el7_9.x86_64可以用readlink -f $(which java)找到完整 JDK 路径取上两级目录作为JAVA_HOME确保该目录下有bin/java。5. “bin/java is not executable”现象bin/java: No such file or directory或提示bin/java不可执行。原因JAVA_HOME错误地指向了 JRE 目录没有bin/java或路径本身不存在。解决安装完整 JDKyum install java-1.8.0-openjdk-devel使用readlink -f $(which java)找到真实路径例如/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.392.b08-2.el7_9.x86_64/jre/bin/java则JAVA_HOME应设为/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.392.b08-2.el7_9.x86_64即去掉/jre/bin/java。6. Hadoop 3.x 使用 slaves 文件导致从节点无法启动现象从节点没有 DataNode 进程NameNode 日志提示找不到 slave。原因Hadoop 3.x 已经用workers文件替代了slaves。解决删除或备份旧的slaves在$HADOOP_HOME/etc/hadoop/下创建workers每行写一个从节点主机名echo -e slave1\nslave2 workers7. 数据目录不存在DataNode 启动失败现象DataNode 日志提示Directory /usr/local/hadoop-3.3.6/data/datanode does not exist。原因hdfs-site.xml中配置的数据目录未预先创建Hadoop 不会自动创建多级目录。解决在所有节点手动创建mkdir -p /usr/local/hadoop-3.3.6/data/{namenode,datanode,tmp}三、NameNode 安全模式与 DataNode 运行问题8. SafeModeException: Name node is in safe mode现象org.apache.hadoop.hdfs.server.namenode.SafeModeException: Cannot create file /files/info.txt. Name node is in safe mode.原因HDFS 启动后会进入一段安全模式等待 DataNode 上报足够的数据块。此时禁止写入。解决在 NameNode 所在节点手动退出hdfs dfsadmin -safemode leave用hdfs dfsadmin -safemode get检查返回Safe mode is OFF即可。9. 0 datanode(s) running —— 写入时找不到 DataNode现象File /files/info.txt could only be written to 0 of the 1 minReplication nodes. There are 0 datanode(s) running and 0 node(s) are excluded in this operation.原因DataNode 进程未启动或启动后因clusterID 不匹配、权限不足、网络不通等原因挂掉。解决首先检查进程jps应显示DataNode。若没有手动启动hdfs --daemon start datanode或重启整个 HDFSstop-dfs.sh start-dfs.sh如果 DataNode 反复退出查看日志$HADOOP_HOME/logs/hadoop-*-datanode-*.log常见处理Incompatible clusterIDs清理 DataNode 数据目录实验环境rm -rf /tmp/hadoop-*/dfs/data/current hdfs namenode -format start-dfs.sh权限问题确保数据目录属主是启动用户且有读写权限。主机名解析确保 DataNode 能 ping 通 NameNode 的主机名。最后通过hdfs dfsadmin -report确认Live datanodes ≥ 1。重要提示DataNode 是独立守护进程不会随 Java 程序启动而自动运行必须事先在集群节点上启动。四、主机名解析与集群通信10. UnknownHostException: master现象Windows 上的 Java 程序连接完全分布式集群时java.net.UnknownHostException: master原因Windows 无法将master解析为 Linux 服务器的 IP。解决在 Windows 的C:\Windows\System32\drivers\etc\hosts文件中添加192.168.1.100 master或在代码中直接用 IPFileSystem.get(new URI(hdfs://192.168.1.100:9000), conf, root);11. ssh: Could not resolve hostname slave1现象启动从节点或 SCP 传输时提示无法解析slave1。原因主节点不能解析从节点的主机名。解决在所有节点的/etc/hosts中添加完整的集群主机映射192.168.1.100 master 192.168.1.101 slave1 192.168.1.102 slave2并确保已配置 SSH 免密登录ssh-copy-id。12. Slave 节点 jps 只有 Jps无 DataNode原因可能原因① 使用了废弃的slaves文件② SSH 免密未配③ 从节点hadoop-env.sh未设置JAVA_HOME④ 从节点无法解析 master 主机名。解决逐一排查改用workers文件配置 SSH 免密在所有节点的hadoop-env.sh中强制写入JAVA_HOME在从节点/etc/hosts中添加 master 映射五、权限与安全设置13. root 用户启动被拒HDFS_NAMENODE_USER not defined现象ERROR: but there is no HDFS_NAMENODE_USER defined. Aborting operation.原因Hadoop 默认不允许 root 直接启动守护进程需显式声明允许的用户。解决在hadoop-env.sh末尾添加仅限实验环境export HDFS_NAMENODE_USERroot export HDFS_DATANODE_USERroot export HDFS_SECONDARYNAMENODE_USERroot export YARN_RESOURCEMANAGER_USERroot export YARN_NODEMANAGER_USERroot生产环境务必创建普通用户如hadoop并赋权。六、版本与工具适配14. IDEA 社区版无法安装 Big Data Tools 插件现象社区版 IDEA 搜索不到Big Data Tools或提示不支持。原因该插件仅限 Ultimate 版。替代方案浏览器直接访问http://namenode:9870查看 HDFSIDEA 内嵌终端使用hdfs dfs命令编写 Java 代码操作 HDFS使用免费客户端如 HDFS Explorer15. Windows 与 Linux 集群 Hadoop 版本不一致现象Windows 开发环境使用 Hadoop 3.3.6集群却是 2.10.2导致 RPC 协议不匹配。解决将集群升级到与开发环境一致的 3.3.6 版本下载安装包复用配置文件重新格式化 NameNode。七、实验收尾需要手动关闭 DataNode 吗个人实验环境强烈建议手动关闭。DataNode 等守护进程会持续占用系统资源直接关机可能导致下次启动时 NameNode 长时间停留在安全模式。执行stop-dfs.sh并用jps确认无残留进程即可。生产环境请勿随意执行应由管理员操作。八、总结与避坑指南依赖要完整使用hadoop-client或确保hadoop-common、hadoop-hdfs-client、woodstox-core均已引入。路径要规范Windows 本地路径使用file:///D:/...格式配置文件中的目录用正斜杠目录需预先创建。环境变量硬编码所有节点的hadoop-env.sh必须显式设置JAVA_HOME这是最常见的启动失败根源。主机名互通所有节点包括 Windows 客户端必须能通过主机名互相 ping 通/etc/hosts或hosts文件要配置完整。配置文件更新升级 Hadoop 版本后注意废弃项如slaves→workers。安全模式与 DataNode第一次启动或异常关机后记得检查安全模式确认 DataNode 存活再进行写入操作。权限声明用 root 启动实验集群时务必在hadoop-env.sh中添加_USER变量。这些错误单看一条似乎都很“低级”但连续出现时非常消磨热情。把全部坑踩完并记录下来下次再遇到就能秒杀了。希望这篇文章能帮你绕过这些暗礁顺利跑通 Hadoop 序列化实验