Flask返回文件下载时中文名变问号或下划线的根本原因是Content-Disposition头的filename字段不支持UTF-8，需同时设置filename（ASCII安全名）和filename*=UTF-8''{encoded}（RFC 5987格式），且必须手动构造Response。
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 头组装，漏一环就退回乱码。
