用 RFC 5987 的 filename* 正确返回中文下载文件名
问题场景
下载接口返回 Content-Disposition: attachment; filename="测试.txt" 时,部分浏览器会把中文显示成乱码,或在保存时截断文件名。原因是 filename 参数按传统 HTTP 头规则应使用 ASCII 可见字符,直接塞入 UTF-8 字节并不可靠。RFC 5987 定义了 filename* 参数:声明字符集与语言,再放百分号编码后的文件名。推荐同时给出 ASCII fallback 与 filename*,让新浏览器优先使用 UTF-8 名称,旧客户端退回 fallback。
一个合规的响应头形如:
Content-Disposition: attachment; filename="download.txt"; filename*=UTF-8''%E4%B8%AD%E6%96%87.txt
UTF-8'' 中两个单引号不能省略,前半段是字符集,后半段是百分号编码后的 UTF-8 文件名。
Express 最小实现
下面的示例只依赖 Express,返回一段文本并以中文文件名下载。cleanName 去掉路径、控制字符、双引号和反斜杠,避免头注入;asciiFallback 只保留 ASCII 可见字符;encodeRFC5987 对 filename* 的值做编码。
const express = require('express');
const path = require('path');
const app = express();
function cleanName(input) {
const base = path.basename(String(input || 'download.txt'));
const out = Array.from(base).filter(ch => {
const c = ch.codePointAt(0);
return c >= 32 && c !== 127 && ch !== '"' && ch !== String.fromCharCode(92);
}).join('').trim();
return out && out !== '.' && out !== '..' ? out : 'download.txt';
}
function asciiFallback(name) {
return Array.from(name).map(ch => {
const c = ch.codePointAt(0);
return c >= 32 && c <= 126 && ch !== '"' && ch !== String.fromCharCode(92) ? ch : '_';
}).join('') || 'download.txt';
}
function encodeRFC5987(value) {
return encodeURIComponent(value).replace(/['()*]/g, ch =>
'%' + ch.charCodeAt(0).toString(16).toUpperCase()
);
}
app.get('/download', (req, res) => {
const name = cleanName(req.query.name);
const fallback = asciiFallback(name);
const body = '你好,这是下载内容。\n';
res.setHeader('Content-Type', 'text/plain; charset=utf-8');
res.setHeader('Content-Length', Buffer.byteLength(body));
res.setHeader(
'Content-Disposition',
`attachment; filename="${fallback}"; filename*=UTF-8''${encodeRFC5987(name)}`
);
res.end(body);
});
app.listen(3000, () => {
console.log('http://localhost:3000/download?name=%E6%B5%8B%E8%AF%95.txt');
});
运行:
npm init -y
npm install express
node server.js
验证响应头
先只看头,不保存文件:
curl -sD - -o /dev/null "http://localhost:3000/download?name=%E6%B5%8B%E8%AF%95%E6%96%87%E4%BB%B6.txt"
应看到类似:
Content-Disposition: attachment; filename="____.txt"; filename*=UTF-8''%E6%B5%8B%E8%AF%95%E6%96%87%E4%BB%B6.txt
fallback 中的下划线数量取决于替换规则,不必与示例完全一致。再用 curl -OJ 让 curl 读取响应头中的文件名并落盘:
curl -OJ "http://localhost:3000/download?name=%E6%B5%8B%E8%AF%95%E6%96%87%E4%BB%B6.txt"
ls -l 测试文件.txt
-O 表示保存到文件,-J 表示优先使用 Content-Disposition 中的文件名。若终端和文件系统使用 UTF-8,应得到中文文件名;若客户端不支持 filename*,会退回 filename 的 ASCII 名称。
边界与限制
filename*的值必须是百分号编码后的 UTF-8,不能直接写中文,也不能只对整段头做编码。encodeURIComponent不会转义'、(、)、*,这些字符不属于 RFC 5987 的attr-char,需要额外替换为%XX。filenamefallback 必须放在双引号中,并转义引号和反斜杠;不要在其中放非 ASCII 字符。- 头值不能包含 CR/LF,来自查询参数的文件名必须先清理,防止响应头注入。
Content-Length应按字节计算,而不是按 JavaScript 字符串长度计算。- 不同浏览器和客户端对
filename*的支持程度不同,双参数写法比只写filename*更稳。 curl -OJ对包含路径分隔符的文件名可能拒绝保存,测试时使用纯文件名;不同 shell 的引号和编码处理也需注意。
- 点赞
- 收藏
- 关注作者
评论(0)