计算机网络 / 系统课时
下载文件并设置文件名
下载文件并设置文件名
文件下载主要由响应头决定:Content-Disposition 指示浏览器尝试预览还是保存,filename 与 filename* 决定建议文件名。本课用一个本地 Flask 服务分别返回 inline 与 attachment,并用 curl 检查服务器真正发出的响应头。
学习目标
- 区分
inline与attachment对浏览器处理方式的影响。 - 为 ASCII 与 UTF-8 文件名同时设置兼容的下载名称。
- 用 curl 检查
Content-Disposition,避免只凭浏览器界面判断。
inline 与 attachment 的差别
Content-Disposition: inline 表示客户端可以在支持该 MIME 类型时直接显示;attachment 表示客户端应把响应作为附件处理并提供保存动作。它们是响应处理指示,不会改变文件字节本身。
| 响应头 | 典型结果 | 配合的 Content-Type |
|---|---|---|
inline; filename="report.csv" |
浏览器可能直接显示文本或 PDF | 使用真实 MIME,例如 text/csv、application/pdf |
attachment; filename="report.csv" |
浏览器通常进入下载流程 | 仍应使用真实 MIME,便于客户端正确识别 |
如果希望 PDF 在浏览器标签页中预览,可用 inline 加 application/pdf;如果明确要用户保存同一份 PDF,则改为 attachment。浏览器设置和安全策略仍可能覆盖服务器的建议行为。
用本地服务返回两种响应
下面的服务返回同一份 CSV 内容,只改变 Content-Disposition。中文名通过 filename* 使用 UTF-8 百分号编码,同时保留 ASCII filename 作为兼容回退。
from urllib.parse import quote
from flask import Flask, Response
app = Flask(__name__)
content = "month,total\n2026-10,1280\n".encode("utf-8")
def make_disposition(mode):
# filename 提供 ASCII 回退,filename* 提供 UTF-8 文件名。
encoded = quote("月报-2026-10.csv")
return (
f'{mode}; filename="report-2026-10.csv"; '
f"filename*=UTF-8''{encoded}"
)
@app.get("/preview")
def preview():
# inline 适合让支持 text/csv 的客户端尝试直接展示。
return Response(
content,
mimetype="text/csv",
headers={"Content-Disposition": make_disposition("inline")},
)
@app.get("/download")
def download():
# attachment 明确给出下载处理建议,但文件字节与 preview 相同。
return Response(
content,
mimetype="text/csv",
headers={"Content-Disposition": make_disposition("attachment")},
)
if __name__ == "__main__":
app.run(host="127.0.0.1", port=5000)把代码保存为 app.py,安装 Flask 并启动:
python -m pip install Flask
python app.py预期输出中会出现:
* Running on http://127.0.0.1:5000检查服务器实际发出的文件名
先只读取响应头,这比观察浏览器弹窗更容易确认问题出在服务端还是客户端:
curl -sI http://127.0.0.1:5000/download | grep -i '^Content-Disposition:'预期输出:
Content-Disposition: attachment; filename="report-2026-10.csv"; filename*=UTF-8''%E6%9C%88%E6%8A%A5-2026-10.csv再让 curl 按响应头保存文件。curl 的 -J 读取 Content-Disposition,-O 使用服务器给出的名称;为避免已有同名文件干扰,先进入空目录。
mkdir -p download-test
cd download-test
curl -sOJ http://127.0.0.1:5000/download
ls -1预期输出:
report-2026-10.csv这里 curl 使用 ASCII 回退名;现代浏览器通常会优先理解 filename*,因此下载界面可显示 月报-2026-10.csv。服务器同时发送两者,可以兼顾更广的客户端实现。
文件名兼容性与安全边界
filename* 的格式应写成 UTF-8'' 加百分号编码后的 UTF-8 文件名,不能直接把未经编码的中文拼进去。只发送 filename="月报.csv" 在部分旧客户端或代理链路上可能出现乱码,因此生产接口更适合同时发送 ASCII 回退名和 filename*。
当文件名来自用户输入时,不要直接反射到响应头。至少拒绝或替换回车、换行、正斜杠 / 与反斜杠 \,并在服务端生成受控的回退名,例如 download.csv。这样既避免响应头注入,也避免客户端把名称误解为路径。
验证下载接口时,先用 curl -I 核对 Content-Type 与 Content-Disposition,再测试浏览器行为。只要响应头中的处理方式、回退文件名和 UTF-8 文件名三项都符合预期,预览与下载的差异就能被稳定控制。