RomM项目中的iOS Safari下载文件名编码问题解析

问题背景

在RomM项目3.8.1版本中，用户报告了一个关于iOS设备上通过Safari浏览器下载文件时出现的文件名编码问题。具体表现为：当文件名包含空格或括号等特殊字符时，桌面浏览器能正确显示解码后的文件名（如"Advance Wars (USA) (Rev 1).zip"），而iOS Safari则保留了URL编码格式（如"Advance%20Wars%20%28USA%29%20%28Rev%201%29.zip"）。

技术分析

这个问题本质上与HTTP响应头中的Content-Disposition字段处理方式有关。在原始实现中，RomM后端使用urllib.parse.quote()函数对文件名进行编码，这在大多数现代浏览器中都能被正确解码。然而，iOS Safari（以及基于Safari内核的其他iOS浏览器如Firefox）对此处理方式有所不同。

深入研究发现，这涉及到HTTP规范中关于Content-Disposition头部的两种不同定义方式：

1. 传统的"filename"参数
2. 较新的"filename*"扩展参数（支持明确指定字符编码）

解决方案

经过社区讨论和测试，最终采用的解决方案是同时提供两种格式的Content-Disposition头部：

"Content-Disposition": f'attachment; filename*=UTF-8\'\'{quote(file.file_name)}; filename="{quote(file.file_name)}"'

这种双重定义方式具有以下优点：

1. 兼容性：新浏览器会优先使用filename*参数，支持UTF-8编码
2. 回退机制：旧浏览器会使用传统的filename参数
3. 明确字符集：通过指定UTF-8编码，确保非ASCII字符也能正确显示

测试验证

解决方案在多种环境下进行了充分测试：

1. 桌面浏览器（Firefox、Chrome）：表现正常
2. iOS Safari：成功解决编码问题
3. iOS Firefox（基于Safari内核）：问题同样解决
4. 包含非ASCII字符的文件名（如日文字符）：显示正确
5. 包含特殊字符（空格、括号等）的文件名：处理得当

实现细节

该修复已合并到RomM项目的3.8.2版本中，主要修改了后端rom.py文件中关于Content-Disposition头部的生成逻辑。值得注意的是，这种解决方案不仅适用于RomM项目，对于其他需要处理文件下载的Web应用也具有参考价值。

总结

这个案例展示了Web开发中浏览器兼容性问题的一个典型例子。通过深入理解HTTP协议规范并采用渐进增强的设计思路，开发者可以找到既保持向后兼容又支持现代特性的解决方案。对于类似的文件下载场景，建议开发者始终考虑：

1. 明确指定字符编码
2. 提供新旧两种格式的Content-Disposition
3. 进行多平台、多浏览器的全面测试

这种处理方式已被证明能有效解决iOS Safari等浏览器中的文件名编码问题，同时不影响其他浏览器的正常功能。