PHP下载文件时中文名乱码如何解决？

Question

在使用PHP实现文件下载功能时，若文件名为中文，常出现下载后文件名乱码或显示为问号的问题。该问题主要源于HTTP响应头中Content-Disposition字段对中文字符编码处理不当。当服务器未正确设置文件名的字符编码（如UTF-8），浏览器无法正确解析，导致乱码。尤其在不同浏览器（如Chrome、IE）中兼容性差异更明显。如何通过合理设置响应头，对中文文件名进行URL编码或采用RFC 5987标准编码，是解决PHP下载中文文件名乱码的关键技术难点。

Answer 1

一、问题背景与现象描述

在使用PHP实现文件下载功能时，若原始文件名为中文（如“报告.docx”），用户下载后常发现文件名乱码或显示为“下载文件”、“_”甚至多个问号（???）。这一现象广泛存在于各类Web应用中，尤其是在跨浏览器场景下表现尤为突出。

根本原因在于HTTP响应头中的Content-Disposition字段对非ASCII字符（如中文）的编码处理不一致。该头部用于指示浏览器以“附件”形式保存文件，并指定建议的文件名：

Content-Disposition: attachment; filename="报告.docx"

然而，由于HTTP协议早期设计未充分考虑国际化字符集，不同浏览器对中文文件名的解析方式各异。例如：

• Chrome 支持 UTF-8 编码的 RFC 5987 格式；
• IE 和旧版 Edge 对 URL 编码更友好；
• Safari 对双引号和空格敏感。

二、技术原理剖析：Content-Disposition 与字符编码标准

根据RFC 6266规范，Content-Disposition允许通过两种方式传递非ASCII文件名：

1. filename* 参数：遵循 RFC 5987，支持扩展字符集编码（如UTF-8）；
2. filename 参数：仅限ASCII字符，需对非ASCII进行编码适配。

RFC 5987 定义了参数值的编码格式：charset'language'value，例如：

filename*=UTF-8''%E6%8A%A5%E5%91%8A.docx

其中%E6%8A%A5%E5%91%8A是“报告”的UTF-8 URL编码结果。

但并非所有浏览器都支持filename*，因此必须提供兼容性降级方案。

三、常见解决方案对比分析

方案	编码方式	Chrome	Firefox	IE/Edge	Safari
直接UTF-8	无编码	❌	❌	❌	❌
URL编码 + 双引号	rawurlencode	✅	✅	⚠️部分失败	⚠️空格变+
RFC 5987 (filename*)	UTF-8''...	✅	✅	✅（IE9+）	✅
GB2312 编码（IE专用）	iconv('UTF-8','GB2312//IGNORE')	❌	❌	✅	❌

四、推荐实现方案：多浏览器兼容策略

结合现代浏览器支持与向后兼容原则，推荐采用“双头并行”策略：

<?php
function downloadFile($filePath, $originalFilename) {
    if (!file_exists($filePath)) {
        http_response_code(404);
        die('File not found.');
    }

    $encodedFilename = rawurlencode($originalFilename);
    $utf8Encoded = rawurlencode(mb_convert_encoding($originalFilename, 'UTF-8', 'auto'));

    // 设置基础响应头
    header('Content-Type: application/octet-stream');
    header('Content-Length: ' . filesize($filePath));
    
    // 兼容性 Content-Disposition 策略
    header("Content-Disposition: attachment; 
        filename=\"{$encodedFilename}\"; 
        filename*=UTF-8''{$utf8Encoded}");
    
    readfile($filePath);
    exit;
}
?>

此方法同时设置filename（用于老IE）和filename*（现代浏览器优先识别），实现最大兼容性。

五、深入优化：用户代理检测与智能编码路由

针对特定浏览器行为差异，可引入User-Agent判断逻辑，动态选择编码策略：

function getDispositionHeader($filename, $userAgent) {
    $utf8 = rawurlencode($filename);
    $gbk = rawurlencode(iconv('UTF-8', 'GB2312//IGNORE', $filename));

    if (strpos($userAgent, 'MSIE') !== false || strpos($userAgent, 'Trident') !== false) {
        // IE 使用 GB2312 编码
        return "attachment; filename=\"{$gbk}.docx\"";
    } elseif (strpos($userAgent, 'Safari') !== false && strpos($userAgent, 'Chrome') === false) {
        // Safari 不解析 %20，用空格代替 +
        $safe = str_replace('+', ' ', $utf8);
        return "attachment; filename=\"{$safe}\"";
    } else {
        // 默认使用 RFC 5987
        return "attachment; filename=\"{$utf8}\"; filename*=UTF-8''{$utf8}";
    }
}

六、流程图：中文文件名下载决策逻辑

graph TD
            A[开始下载请求] --> B{文件是否存在?}
            B -- 否 --> C[返回404错误]
            B -- 是 --> D[获取原始中文文件名]
            D --> E[检测User-Agent]
            E --> F{是否为IE?}
            F -- 是 --> G[使用GB2312编码]
            F -- 否 --> H{是否为Safari?}
            H -- 是 --> I[替换+为空格]
            H -- 否 --> J[采用RFC5987双编码]
            G --> K[设置Content-Disposition]
            I --> K
            J --> K
            K --> L[输出文件流]
            L --> M[结束]

七、实际部署注意事项

• 确保PHP脚本文件本身以UTF-8无BOM格式保存，避免输出前导字符导致header发送失败；
• 使用ob_clean()和flush()清理缓冲区，防止意外输出；
• 对于大文件，建议启用readfile()配合fpassthru()提升性能；
• CDN或反向代理可能修改headers，需测试端到端效果；
• 日志记录异常文件名，便于后续分析编码问题；
• 前端可通过AJAX预检接口获取安全文件名，作为fallback提示；
• 考虑将文件名哈希化+后缀保留作为最终兜底策略；
• 定期更新浏览器兼容性矩阵，适应新版本变化；
• 使用mb_http_output()关闭默认输出编码转换；
• 在Nginx/Apache配置中禁用自动charset附加。