Jenkins报UnmappableCharacterException:Input length=1故障排查

核心报错java.nio.charset.UnmappableCharacterException: Input length = 1与权限无关，从错误堆栈可直接定位触发位置：Jenkins完成Bitbucket代码拉取后，准备执行配置的构建步骤生成临时脚本文件时，遇到系统默认字符集无法映射的字符，写入失败直接终止构建。
触发该问题的两个高频原因：

• 构建步骤配置不兼容Windows环境：日志最后明确标记失败步骤为Execute shell，该步骤原生为Linux/macOS环境设计，Windows环境无默认shell运行环境，即便安装了Git Bash/WSL，默认配置下的路径转义、字符集匹配逻辑均存在兼容问题
• 字符集配置不匹配：Windows 10简体中文环境默认系统字符集为GBK，若Jenkins启动未指定UTF-8编码，构建脚本、拉取的代码路径/文件名中存在GBK码表不包含的字符（如中文标点、全角符号、emoji、UTF-8特殊字符）时，写临时文件就会抛出字符映射错误。

按优先级从高到低依次验证修复：

• 替换不兼容的构建步骤

  Windows环境下不要直接使用默认配置的Execute shell步骤，优先选择以下两种方案：

  1. 换成Execute Windows batch command步骤，将原shell中编写的SFDX测试、部署命令改写为cmd兼容语法后填入
  2. 若要保留shell语法，先进入Jenkins系统配置页，找到Shell配置项，将Shell executable路径手动指定为本地Git安装目录下的bin\bash.exe（参考路径：C:\Program Files\Git\bin\bash.exe），不要使用默认的sh执行路径

• 强制Jenkins以UTF-8编码启动
  找到Jenkins启动配置项，新增以下两个JVM启动参数：

  -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8
  

  若Jenkins以Windows服务方式运行，直接打开Jenkins安装目录下的jenkins.xml文件，找到<arguments>标签，将上述参数追加到现有JVM参数末尾，保存后重启Jenkins服务生效。
• 排查清理不可识别字符
  检查构建步骤内编写的所有命令，删除全角标点、中文特殊符号、不可见控制字符；同时检查Bitbucket仓库内的Apex代码文件名、目录路径，不要包含中文、emoji或其他GBK字符集无法识别的特殊字符。
• 兜底权限校验
  确认运行Jenkins服务的SYSTEM账号对C:\JenkinsHome\workspace\目录拥有完全控制权限：右键目录打开「属性-安全」选项卡，给SYSTEM账号勾选「完全控制」权限，应用配置后重跑构建任务。

内容的提问来源于stack exchange，提问作者Genis Bonet Garcia