Jenkins agent启动失败报UTF-8编码相关错误如何解决

• 校验JNLP文件本身编码：在树莓派节点执行curl http://jenkins.chenny.homes/computer/venus/jenkins-agent.jnlp?encrypt=true -o test.jnlp下载目标文件，再执行file -i test.jnlp确认文件编码，同时打开文件检查是否存在乱码字符，重点关注节点名称、Jenkins站点名称等自定义配置字段是否有非UTF-8编码的内容。
• 检查Agent端Java默认编码：你提供的编码配置是Jenkins Master端的，需要确认树莓派上Java环境的编码配置，执行java -XshowSettings:properties -version 2>&1 | grep file.encoding查看slave端默认编码，树莓派官方系统默认编码常为非UTF-8格式，是高发问题点。
• 检查反向代理编码配置：若你的Jenkins Master通过Nginx、Caddy等反向代理提供访问，需要确认代理服务是否正确配置了UTF-8编码响应头，未配置或配置错误会导致传输过程中编码被篡改。
• 校验Jenkins全局字符集配置：进入Jenkins后台「Manage Jenkins -> Configure System」，检查全局属性中是否添加了LANG=en_US.UTF-8、LC_ALL=en_US.UTF-8的环境变量，同时确认Master启动参数是否包含-Dsun.jnu.encoding=UTF-8，仅配置file.encoding不足以覆盖所有字符解析场景。

• 优先给Agent启动命令增加编码参数，修改后的启动命令如下：

/usr/bin/java -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -jar /home/pi/jenkins_agent/slave.jar -jnlpUrl http://jenkins.chenny.homes/computer/venus/jenkins-agent.jnlp -secret xxxxx -workDir "/home/pi/jenkins_agent/workspace"

• 若使用反向代理，以Nginx为例，在Jenkins对应的站点配置中增加以下规则：

charset utf-8;
add_header Content-Type "application/x-java-jnlp-file; charset=utf-8";

修改后重载Nginx配置再重试Agent启动。

• 补全Jenkins Master启动参数：修改Jenkins启动配置，在启动命令中增加-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8两个参数，重启Jenkins Master生效。
• 本地JNLP文件验证：如果上述方案无效，可以先把JNLP文件下载到树莓派本地，用本地文件启动Agent验证问题根源：

# 下载JNLP文件到本地
curl http://jenkins.chenny.homes/computer/venus/jenkins-agent.jnlp?encrypt=true -o /home/pi/jenkins_agent/agent.jnlp
# 本地文件启动Agent
java -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -jar /home/pi/jenkins_agent/slave.jar -jnlpFile /home/pi/jenkins_agent/agent.jnlp -secret xxxxx -workDir "/home/pi/jenkins_agent/workspace"

如果本地启动正常，说明问题出在网络传输链路的编码篡改，重点排查反向代理、DNS劫持等中间链路。

内容的提问来源于stack exchange，提问作者Chen Du