Flask文件下载中文乱码解决方法

本文深入剖析了Flask中文件下载时中文文件名显示为问号或下划线的根本原因——Content-Disposition响应头的filename字段不支持UTF-8，而浏览器（尤其是Chrome/Edge）默认按ISO-8859-1解析，导致乱码；文章明确指出仅用url_quote处理路径参数或依赖Flask内置的download_name参数远远不够，必须手动构造Response并严格遵循RFC 5987规范，同时提供ASCII兼容的filename和UTF-8编码的filename*双格式头字段，还覆盖了Windows环境下的编码陷阱、bytes/str类型混淆、文件系统读取可靠性等实战痛点，给出可直接复用的安全清洗与编码方案，帮你彻底终结中文下载名乱码难题。

Flask返回文件下载时中文名变问号或下划线

根本原因是 Content-Disposition 响应头里的 filename 字段不支持直接传 UTF-8 字符串，浏览器（尤其是 Chrome、Edge）会按 ISO-8859-1 解析，导致中文被截断或替换成 ? 或 _。

不能只靠 url_quote 编码文件名就完事——它解决的是 URL 路径里的中文问题，不是响应头里的文件名问题。

• 用 url_quote(filename, encoding='utf-8') 处理的是请求路径参数（比如 /download?name=报告.pdf），和 Content-Disposition 无关
• Content-Disposition 需要同时提供 filename（兼容老浏览器）和 filename*=（RFC 5987 格式，支持 UTF-8）
• 不同浏览器对两种格式的支持程度不同：Firefox 优先读 filename*，Chrome 也支持但部分旧版本 fallback 到 filename

正确设置 Content-Disposition 的双格式写法

必须手动拼接响应头，不能只设一个字段。Flask 的 send_file 不自动处理中文名，得自己构造 Response 对象。

关键点是：filename 用 ASCII 安全名（如去掉中文、转下划线），filename*= 用 UTF-8'' 编码格式（注意两个单引号）。

• filename 值只能含 ASCII 字符，建议用 re.sub(r'[^\w.-]', '_', filename) 简单清洗
• filename* 的值格式为 UTF-8''{encoded}，其中 {encoded} 是 urllib.parse.quote 编码后的字符串（不是 url_quote）
• 编码前必须确保原始文件名是 str 类型且为 UTF-8 内容，避免 bytes 直接 encode 出错

from flask import Response, request
from urllib.parse import quote
import re
<p>def make_download_response(file_path, original_name):
with open(file_path, 'rb') as f:
data = f.read()</p><h1>清洗 ASCII 版文件名</h1><pre class="brush:python;toolbar:false;">ascii_name = re.sub(r'[^\w.-]', '_', original_name)
# 构造 filename*（RFC 5987）
encoded_name = quote(original_name.encode('utf-8'))
disposition = f"attachment; filename={ascii_name}; filename*=UTF-8''{encoded_name}"
return Response(
    data,
    mimetype='application/octet-stream',
    headers={'Content-Disposition': disposition}
)

为什么不用 send_file + as_attachment=True？

send_file 的 download_name 参数（Flask ≥2.0）看似能解决，但它默认只写 filename 字段，不写 filename*，在中文场景下仍会乱码。

• Flask 2.0+ 的 download_name 会自动做 url_quote，但仅用于 filename，不生成 filename*
• 低于 Flask 2.0 的版本压根没有 download_name，只能手写响应头
• 即使用了 download_name，遇到带空格、括号、中文的文件名，Chrome 仍可能显示为 download 或 unknown

Windows 下测试容易忽略的编码陷阱

本地开发用 Windows + Chrome 测试时，如果 Python 源文件没声明 UTF-8 编码，或文件名来自 os.listdir()（在某些 Python 版本/系统 locale 下返回 bytes），会导致 original_name 实际是 bytes 而非 str，.encode('utf-8') 报错或静默出错。

• 检查 type(original_name)，必须是 str；如果是 bytes，先用 original_name.decode('utf-8') 或 original_name.decode(sys.getfilesystemencoding())
• 确保 Python 文件开头有 # -*- coding: utf-8 -*-
• 用 pathlib.Path 替代 os.listdir 更可靠，它默认返回 str 名称

真正麻烦的不是怎么写，而是怎么让每个环节都保持 UTF-8 字符流不中断——从文件系统读取、到变量传递、再到 HTTP 头组装，漏一环就退回乱码。

终于介绍完啦！小伙伴们，这篇关于《Flask文件下载中文乱码解决方法》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！