下载文件名乱码:响应头编码怎么查

适用范围:提供文件下载的网站或API;示例针对HTTP响应头,不修改文件内容。

同一个PDF在服务器上名称正常,下载后却乱码,先检查下载响应里的文件名,而不是重新编码整个文件。文件名、URL和文件内容的编码是三个不同问题。

读取真正返回文件的响应

在浏览器开发者工具的“网络”页保留请求记录,重新触发一次小文件下载。跟随跳转找到最终文件响应,查看 Content-Disposition、Content-Type 与状态码。若返回的是登录页,先解决认证,不调整下载文件名。

可在本机终端请求自己的测试下载地址:

curl -sS -L --max-redirs 5 -D - -o /dev/null 'https://example.com/test-download'

该命令最多跟随5次跳转,并依次输出每一跳的响应头,应查看最终返回文件的那组头信息。它会下载响应体后丢弃,不适合拿大备份反复测试,也不会自动带入登录Cookie。不要把含签名或令牌的URL公开。[3]

给中文名设置UTF-8扩展参数

服务端可返回下面这一行。普通参数提供ASCII回退名,扩展参数提供UTF-8百分号编码的中文名:

Content-Disposition: attachment; filename="report.pdf"; filename*=UTF-8''%E6%8A%A5%E5%91%8A.pdf

在支持扩展参数的客户端中,它表示“报告.pdf”。filename* 不能直接放未经编码的中文;也不要把空格按表单规则改成加号。不同客户端下载行为可能有差异,应保留回退名。[1]

以Python生成参数值为例,不涉及启动Web服务:

from urllib.parse import quote
name = "报告.pdf"
encoded = quote(name, safe="")
print("attachment; filename=\"report.pdf\"; filename*=UTF-8''" + encoded)

只编码中文文件名参数,不把整条响应头一起编码。避免框架已经编码一次后又额外编码。

排查是谁覆盖了响应头

若应用里已经设置正确,外部响应却不同,检查反向代理、下载加速和对象存储元数据等真正返回文件的位置。重复出现多条不同的Content-Disposition也要纠正,不能依赖浏览器“碰巧选对”。

文件名若来自用户输入,必须过滤回车、换行、路径分隔符及危险字符。保留实际文件类型对应的扩展名,不能让文件被误当成另一种可执行类型。[1]

完成标准

用包含中文、空格的测试文件验证下载名;再检查文件哈希和实际打开结果。名称正常但内容乱码,应另查内容编码。名称和内容都正常后,再恢复正式下载入口,保留修改前的响应头设置。

继续排查

下载断点续传失败:检查Range与206响应;备份下载后如何核对SHA256。

技术依据:[1] RFC 6266:Content-Disposition与国际化文件名;[2] Python urllib.parse.quote;[3] curl重定向与响应头输出。适用版本见本文说明。