如何通过Content-Disposition让文件名包含冒号等特殊字符？

我之前也碰到过完全一样的麻烦——想把12:00 PM这种带冒号的时间戳放进下载文件名里，结果浏览器自动把冒号换成了下划线，折腾了好一会儿才找到根源。其实问题出在HTTP标准的历史兼容上：传统的filename参数不允许冒号这类特殊字符，浏览器会自动做替换处理。下面是我实测有效的解决方案：

核心方案：用RFC 5987定义的filename*参数 #

现代HTTP标准（RFC 5987）引入了filename*参数，专门支持UTF-8编码和特殊字符。它的格式规则是：
filename*=字符集''URL编码后的文件名

比如要设置文件名12:00 PM.txt，对应的响应头应该这么写：

Content-Disposition: attachment; filename="12_00PM.txt"; filename*=UTF-8''12%3A00%20PM.txt

• filename="12_00PM.txt"是给不支持filename*的旧浏览器做降级用的，保证这些浏览器至少能拿到一个可正常显示的文件名
• filename*=UTF-8''12%3A00%20PM.txt是核心：%3A是冒号的URL编码，%20是空格的URL编码，现代浏览器会优先识别这个参数，完美显示带冒号的文件名

各后端语言的实现示例 #

Python Flask #

from flask import Flask, make_response
import urllib.parse

app = Flask(__name__)

@app.route('/download')
def download_file():
    original_filename = "12:00 PM.txt"
    # 对文件名做URL编码处理
    encoded_filename = urllib.parse.quote(original_filename)
    # 构造响应头
    response = make_response("这里是下载文件的内容")
    response.headers["Content-Disposition"] = (
        f'attachment; filename="12_00PM.txt"; filename*=UTF-8\'\'{encoded_filename}'
    )
    return response

Java Servlet #

import java.net.URLEncoder;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class DownloadServlet extends HttpServlet {
    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
        String originalFilename = "12:00 PM.txt";
        String encodedFilename = URLEncoder.encode(originalFilename, "UTF-8");
        
        response.setHeader("Content-Disposition", 
            "attachment; filename=\"12_00PM.txt\"; filename*=UTF-8''" + encodedFilename);
        
        // 写入文件内容到响应流
        response.getWriter().write("这里是下载文件的内容");
    }
}

兼容性小提醒 #

• Chrome、Firefox、Edge、Safari这些现代浏览器都完美支持filename*，直接用就行
• 如果非要兼容IE（现在几乎没人用了），IE对filename*的支持很差，这时要么放弃冒号用下划线替代，要么尝试用GBK编码的filename参数，但IE对特殊字符的处理不稳定，不推荐强行兼容

内容的提问来源于stack exchange，提问作者Joe