qrcp项目中Safari浏览器文件名编码问题的分析与解决

问题背景

在文件传输工具qrcp的使用过程中，开发者发现当文件名包含非ASCII字符（如中文"啊.txt"）时，在Safari浏览器中下载的文件名会出现乱码现象。具体表现为：原本应为"啊.txt"的文件名在Safari中被错误显示为"å.txt"。

问题根源分析

经过深入分析，这个问题源于HTTP响应头中Content-Disposition字段对非ASCII字符的处理方式。qrcp服务端在发送文件时，会将文件名直接以UTF-8编码形式放入filename参数中。然而，根据HTTP规范：

1. 传统的filename参数默认使用ISO-8859-1(Latin-1)字符集编码
2. Safari浏览器严格遵循这一规范，将UTF-8编码的字节序列错误解释为ISO-8859-1字符
3. 例如中文字符"啊"的UTF-8编码是\xe5\x95\x8a，在ISO-8859-1中被解释为三个字符：å、•和Š

解决方案

根据RFC 6266规范，正确的解决方案是同时提供两个参数：

1. 保留原有的filename参数，确保向后兼容性
2. 新增filename*参数，使用RFC 5987定义的编码格式

具体实现要点：

1. filename*参数的格式为：utf-8'' + URL编码的文件名
2. 现代浏览器会优先使用filename*参数
3. 旧版浏览器会回退到filename参数

技术实现细节

在实际代码实现中，需要注意以下几点：

1. 对文件名进行URL编码时，需要正确处理空格等特殊字符（转换为%20）
2. 语言标签部分可以留空，但单引号不能省略
3. 字符集声明必须小写"utf-8"
4. 两个参数之间用分号分隔

示例格式：

Content-Disposition: attachment; filename="啊.txt"; filename*=utf-8''%E5%95%8A.txt

兼容性考虑

这种解决方案具有很好的兼容性：

1. 现代浏览器（Chrome、Firefox、Edge等）都能正确处理filename*参数
2. 旧版浏览器会忽略无法识别的filename*参数，回退到filename参数
3. 即使回退到filename参数，虽然可能显示不正确，但文件内容不受影响

总结

通过分析qrcp项目在Safari浏览器中的文件名编码问题，我们深入理解了HTTP协议中文件下载相关的规范要求。采用filename和filename*双参数方案，既解决了现代浏览器的UTF-8支持问题，又保持了与旧版浏览器的兼容性。这种解决方案不仅适用于qrcp项目，也可以作为其他Web应用中文件下载功能开发的参考。