Jenkins File Parameter传入的Excel文件复制到工作区后损坏无法使用

Excel（含.xls/.xlsx格式）本质是二进制格式文件（xlsx本质是zip压缩包结构），上传后损坏基本都是文件在传输、存储环节被按纯文本规则处理，篡改了原始字节，常见触发场景：

• 参数类型配置错误：误将文件上传入参配置为字符串、多行文本类参数，Jenkins会默认按文本编码规则解析上传的二进制流，转码过程中破坏原始字节结构；如果使用老旧版本的文件参数插件，本身存在二进制写入bug，写入工作区时会自动追加换行符、修改特殊字节。
• 构建步骤文件操作逻辑错误：在流水线脚本中使用默认文本模式的API读写Excel文件，比如Groovy的readFile、writeFile未指定二进制编码，会强制按系统/全局配置的文本编码重写文件；Shell步骤中把Excel内容读取到环境变量后再通过重定向生成新文件，Shell变量存储二进制内容时会自动截断、转义特殊字节。
• 全局配置或中间链路篡改：Jenkins全局开启了“强制所有文件读写使用UTF-8编码”规则，二进制文件被强制按文本编码转存；Jenkins前置的Nginx反向代理、WAF安全插件开启了上传内容自动转码、内容审计插入标记的规则，改写了原始文件字节；主从节点构建时，文件同步用了ASCII文本传输模式，类似FTP传二进制文件选了文本模式导致的损坏。
• 权限问题导致的文件写入不完整：Jenkins进程对工作区目录没有完整写入权限，文件上传时只写入了部分字节就终止，生成不完整的损坏文件。

• 校正参数配置：删除原有错误参数，重新添加文件类型上传参数，不要使用文本、字符串类参数接收上传文件，参数名使用纯英文/数字组合，不要带中文、特殊字符，留用默认的工作区存储路径即可。如果是声明式流水线，参数定义参考如下配置：

parameters {
    file(name: 'TEST_DATA_EXCEL', description: '上传测试数据Excel文件')
}

• 修正文件操作逻辑：所有涉及Excel的读写操作都使用二进制模式，禁止把二进制文件内容读取为文本字符串处理。Groovy脚本读写二进制文件时指定Base64编码中转，不要直接按文本读取；Shell步骤中不要把Excel内容存入变量重定向生成文件，后续自动化脚本直接引用工作区中上传的原文件路径作为入参即可，示例调用：

python3 data_process.py ${WORKSPACE}/TEST_DATA_EXCEL

• 排查链路与配置问题：先对比本地原文件和Jenkins工作区文件的MD5值，确认损坏发生的环节：如果MD5在到达Jenkins主机前就不一致，检查前置反向代理配置，Nginx站点配置中添加上传接口的charset off;规则，关闭WAF对Excel类二进制文件的内容改写、扫描插入逻辑；如果是Jenkins本地写入后MD5不一致，关闭全局“强制UTF-8读写”配置，升级文件参数插件到最新稳定版，给Jenkins进程开放工作区目录的完整读写权限；如果是主从节点构建场景，关闭主从文件同步的自动编码转义选项，强制二进制模式传输非文本文件。
• 增加前置校验步骤：在构建流程最开始增加文件有效性校验，提前拦截损坏文件，避免后续流程空跑，简单的Python校验逻辑参考：

import pandas as pd
import sys
try:
    # 尝试读取上传的Excel文件
    pd.ExcelFile('TEST_DATA_EXCEL')
    print("Excel文件有效性校验通过")
except Exception as e:
    print(f"Excel文件损坏，无法读取，错误信息：{str(e)}")
    sys.exit(1)

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