用 RFC 5987 的 filename* 正确返回中文下载文件名

举报
yd_217513249 发表于 2026/11/06 12:06:12 2026/11/06
【摘要】 下载接口只设置 filename 时,中文文件名容易被浏览器截断或乱码。本文说明 Content-Disposition 中 ASCII fallback 与 RFC 5987 filename* 的组合写法,给出 Express 最小示例与 curl -OJ 验证步骤,列出编码、安全和兼容性边界。

问题场景

下载接口返回 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。
  • filename fallback 必须放在双引号中,并转义引号和反斜杠;不要在其中放非 ASCII 字符。
  • 头值不能包含 CR/LF,来自查询参数的文件名必须先清理,防止响应头注入。
  • Content-Length 应按字节计算,而不是按 JavaScript 字符串长度计算。
  • 不同浏览器和客户端对 filename* 的支持程度不同,双参数写法比只写 filename* 更稳。
  • curl -OJ 对包含路径分隔符的文件名可能拒绝保存,测试时使用纯文件名;不同 shell 的引号和编码处理也需注意。
【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。