Ubuntu 下 Jenkins 构建常见错误与快速修复
一 快速定位与通用排查
- 查看构建日志的最后 20–30 行，先定位报错关键字（如：Exception、ERROR、exit status、No such file、Permission denied）。
- 在构建机上以Jenkins 运行用户手动执行构建命令（如 mvn、npm、./gradlew、shell 脚本），复现问题并观察完整输出。
- 区分是Jenkins 控制器还是Agent/节点问题：在对应机器上单独运行相同命令；检查工作空间路径、磁盘空间、内存与 CPU。
- 若通过 SSH 发布（Publish Over SSH、scp、rsync），先在命令行用相同私钥和目标账号测试连通与脚本执行。
- 检查权限与所有者：Jenkins 工作空间与远程目标目录是否属于 Jenkins 用户；必要时用 chown/chmod 修正。
- 确认环境变量与工具链：PATH、JAVA_HOME、M2_HOME、Node、Python、Docker 等版本与路径一致（建议用 which/whereis 验证）。
二 高频场景与对应修复
-
SSH 分发或执行脚本失败（exit status 1、UNSTABLE）
- 现象：文件能传到远端，但执行脚本就中断或返回1。
- 处理：
- 在远端确认脚本具备可执行权限（chmod +x），且属主正确；在脚本首行使用绝对路径解释器（如 #!/usr/bin/env bash）。
- 检查远程工作目录是否存在、磁盘是否充足；在脚本开头打印 pwd、whoami、env 便于排查。
- 若使用密钥登录，确保远端 ~/.ssh/authorized_keys 正确、权限为600/700；必要时在 Jenkins 节点用 ssh user@host 手动执行脚本验证。
- 在 Ubuntu 22.04 上，若遇到旧客户端/密钥导致的握手失败，可在 /etc/ssh/sshd_config 增加：
- HostKeyAlgorithms +ssh-rsa
- PubkeyAcceptedAlgorithms +ssh-rsa
然后重启 sshd：systemctl restart ssh。注意：启用 ssh-rsa 会略降安全性，优先使用更安全的密钥算法。
-
Java AWT/图形库缺失（libawt_xawt.so 报 libXrender.so.1 或 libXtst.so.6 找不到）
- 现象：构建或插件需要 GUI 渲染时报错，如：java.lang.UnsatisfiedLinkError: …/libawt_xawt.so: libXrender.so.1: cannot open shared object file。
- 处理：
- 安装缺失依赖：sudo apt-get install -y libxrender1 libxtst6 libxrandr2 libxi6（通常已足够）。
- 若是服务器无头环境，启动参数加入 -Djava.awt.headless=true，或在 /etc/default/jenkins（或 systemd 服务）中设置 JAVA_OPTS。
- 若仍报 AWT 初始化问题，安装字体与字体配置：sudo apt-get install -y ttf-dejavu fontconfig，然后重启 Jenkins。
-
Maven 依赖解析失败（Failure to find … was cached in the local repository）
- 现象：依赖在本地仓库损坏或远程不可达，构建一直失败。
- 处理：
- 清理 Jenkins 使用的本地仓库缓存（常见路径：/var/lib/jenkins/.m2/repository），再触发构建重新下载。
- 检查 settings.xml 的镜像/仓库与网络连通性；必要时更换镜像源或临时使用官方仓库。
- 若从其他机器拷贝仓库到 Jenkins 用户目录，记得执行 chown -R jenkins:jenkins，避免权限导致无法读取。
-
找不到命令或工具未安装（Cannot run program “xxx”: No such file or directory）
- 现象：构建步骤调用外部工具（如 phing、npm、docker、mvn）时报“找不到程序”。
- 处理：
- 在构建机上安装缺失工具（如 sudo apt-get install -y phing），并确保 PATH 包含其安装路径。
- 在 Jenkins 节点配置中显式设置工具路径（如 JDK、Maven、NodeJS 安装目录），或使用工具自动安装插件统一管理版本。
三 远程部署与权限要点
- 使用 Publish Over SSH 时，注意“Remote directory”与“Source files”拼接后的绝对路径是否正确；若全局配置了“Remote root directory”，检查是否无意间在路径前拼接了 /root 等导致访问受限。
- 远程脚本建议：
- 使用绝对路径；先 cd 到工作目录再执行。
- 开头打印环境信息（pwd、whoami、env | sort），便于定位目录与权限问题。
- 对可能产生问题的命令加 set -eux 或捕获错误并输出日志，避免静默失败。
四 最小可行修复清单
- 在构建机上切换到 Jenkins 用户，手动执行构建命令，确认能跑通。
- 安装常见依赖：sudo apt-get update && sudo apt-get install -y libxrender1 libxtst6 ttf-dejavu fontconfig。
- 若用 SSH 发布：chmod +x 远端脚本；必要时在 /etc/ssh/sshd_config 增加 HostKeyAlgorithms +ssh-rsa 与 PubkeyAcceptedAlgorithms +ssh-rsa 并重启 sshd。
- 清理 Maven 缓存（/var/lib/jenkins/.m2/repository）后重跑；拷贝仓库时修正属主为 jenkins:jenkins。
- 在 Jenkins 系统配置或节点配置中显式设置 JAVA_HOME / PATH / Maven / Node 路径，避免环境不一致。