本质是缓存文件系统级损坏，须从物理缓存层切入：立即脱机故障节点，用smartctl检测磁盘坏块，强制清理~/.m2、~/.npm等全路径缓存，迁移至独立存储，并配置工作区本地缓存+健康校验。
这类问题本质是缓存文件系统级损坏，不是常规的依赖版本或网络问题，必须从物理缓存层切入处理，否则单靠重试、清理个别目录或改配置无法根治。
确认是否为坏块导致的缓存故障
坏块引发的构建失败通常有以下特征：
- 同一台构建机上多个不同项目、不同分支、甚至不同语言（Java + Node）同时报错，且错误位置随机（如编译找不到符号、解析 pom.xml 失败、tar 解包校验失败、npm install 卡死在 extract 阶段）
- 错误日志中出现底层 I/O 异常关键词：Input/output error、Bad address、Corrupted jar、invalid tar header、checksum mismatch（非网络超时导致）
- 手动进入工作区执行
ls -la ~/.m2/repository/xxx或ls -la ~/.npm/_cacache/时命令卡住、返回异常或列出乱码文件名 - 构建机磁盘健康状态告警（可通过
smartctl -a /dev/sdX查看 Reallocated_Sector_Ct、Current_Pending_Sector 等值）
立即止损：隔离故障构建节点
不要在疑似坏块的机器上继续触发任何构建任务，避免扩大损坏范围：
- 在 Jenkins 管理界面 → 节点管理 → 找到该构建机 → 点击 脱机，填写原因（例如：“I/O error detected in local cache storage”）
- 检查该节点是否被设为默认执行器；若已启用“Use this node as a cloud agent”，请临时禁用或切换标签
- 查看当前正在运行的构建，对已在该节点上启动但未完成的任务，可安全中止（Abort）——坏块下继续运行大概率失败且可能写坏更多文件
彻底清除并重建缓存物理路径
不能只删 ~/.m2/repository 或 ~/.npm，而要清空其所在文件系统分区的全部缓存痕迹，并规避受损扇区：
- 登录构建机，确认 Maven/Npm 缓存挂载点：
df -h ~/.m2 ~/.npm。若二者同属一个磁盘分区（如/var/lib/jenkins），且该分区存在坏块风险，则需整体迁移 - 停止 Jenkins 服务：
systemctl stop jenkins - 备份关键配置（如
~/.m2/settings.xml、~/.npmrc）后，执行强制清理：rm -rf ~/.m2/repository ~/.npm ~/.npm/_cacache ~/.yarn/cache - 如使用 SSD 且确认存在坏块，建议运行：
sudo fstrim -v /（TRIM 告知 SSD 回收无效块）；机械盘可尝试：sudo e2fsck -c -c /dev/sdX1（-c -c 表示两次读写检测） - 重新挂载更可靠的存储路径（推荐）：
新建目录如/mnt/cache-jenkins（挂载到独立 SSD 或 NAS）→ 修改 Jenkins 启动用户家目录软链：ln -snf /mnt/cache-jenkins /var/lib/jenkins/.m2和ln -snf /mnt/cache-jenkins/.npm
预防机制：从架构层面规避单点缓存失效
坏块无法完全杜绝，但可通过设计降低影响面和恢复时间：
-
禁止共享全局缓存：Jenkins 系统配置中，Maven 本地仓库策略必须设为 Local to the workspace（而非 Local to the executor 或 Shared）；Npm 则在构建脚本开头加
npm config set cache $(pwd)/.npm-cache -
启用校验与自动修复：在 Jenkins 流水线首步加入缓存健康检查脚本：
find ~/.m2/repository -name "*.jar" -size -100c -delete 2>/dev/null || truenpm cache verify - 构建机标准化镜像：将 Jenkins Agent 制作为带健康自检脚本的容器镜像或 VM 模板，每次拉起新节点前自动运行磁盘扫描 + 缓存初始化
-
监控前置化：通过 Prometheus + Node Exporter 监控
node_filesystem_readonly、node_filesystem_device_error及diskio_io_time_seconds_total突增，触发告警并自动脱机
坏块问题不常发生，但一旦出现就是硬伤。核心逻辑是：先停、再判、清物理层、换路径、加防护。处理完一台，务必对同批次采购的其他构建机做批量 SMART 检测，避免连锁故障。
