客户下载的报表名字成了一串 %E4，我们办公室几台电脑都正常，这种只在一台机器冒出来的问题该从哪儿看？

多数情况不是浏览器不认中文，通常是响应头里的 Content-Disposition 只写了 filename=，后面直接跟了 UTF-8 中文名。按 2026 年常见交付做法，同一个头里要并排放两个值：一个纯 ASCII 兜底名，一个按 RFC 5987 写的 filename*=UTF-8'' 加百分号编码，浏览器各挑能认的那个；前端 download 属性再补一层，新旧客户端大多能对上。

一、先分清是哪种乱码，三种形态改的地方不一样

同样叫文件名乱码，落在截图里是几类完全不同的现象。先分形态再动手，能少走一轮发版：有的问题在字段位置，有的在编码声明，还有的在半路就已经把信息丢了。

• 变成 %E4%B8%AD%E6%96%87.xlsx：编码本身没错，只是放错了字段。值塞在 filename= 里，客户端会把它当成普通字符串原样显示。
• 变成 ä¸ 这类怪字符：UTF-8 字节被按 ISO-8859-1 或本地代码页重新解了一遍，属于声明与实际编码不一致。
• 变成问号、下划线或只剩 .xlsx：如果变成问号或下划线，说明字符在某一层被替换，多见于旧内核或中间代理按非 UTF-8 转码，通常不可逆；如果只剩扩展名，多半是头里混进了分号、换行或引号导致头被截断，属于格式问题。

判断口诀可以记成一句：看到百分号说明编码对、位置错；看到 ä 说明解码用错了字符集；看到问号或空名说明中间已经丢了信息，或者头被截断。三者要改的地方不同，混着改容易越改越乱，也容易先在前端绕一大圈。

二、filename 和 filename* 的分工，以及只写一个的代价

filename 是早期字段，语义上只保证 ASCII 可用，塞中文时各浏览器、各操作系统的代码页处理并不统一；filename* 带字符集和语言标记，值是百分号编码后的字符串，能被正确还原成中文。两者不冲突，同时写等于给能力不同的客户端各留一条路。

• 只写 filename 加中文：新版 Chrome、Edge 多数能猜对，旧内核和部分下载工具容易乱，兼容性接近于靠运气。改动量最小，但验证要覆盖到客户可能存在的旧终端，常见区间半天到一天。
• 只写 filename*：认 RFC 5987 的客户端表现正常，不认的可能连扩展名都拿不到，退回 download 或一串编号。需要逐个客户端核对，常见区间也是一天上下。
• 两个都写：ASCII 兜底名保底，支持中文的客户端显示原名，是 2026 年交付里比较稳的组合。多写一行头，验证覆盖三到四类客户端，经验区间半天到两天。
• 两个都不写：客户端自己从 URL 末段取名，路径里带 ID 或哈希时，用户看到的就是一串没有辨识度的字符。

还有一处细节常被忽略：filename* 的值要整体按 UTF-8 字节做百分号编码，只保留字母、数字和少数安全字符。直接对整串调用 encodeURIComponent，会把括号、单引号等原样留下，遇到严格解析的客户端就可能取不到完整名字。编码后的头字段也宜控制在几十字节量级，给兜底名留出余地。

三、交付现场：英文版系统加旧内核终端，初版只写了一个字段

比较常见的约束是这样：客户机房是英文版 Windows Server，内网还留着旧内核浏览器，运营要求导出名里带中文和批次号，素材本身含空格和括号，交付窗口两周。初版图省事，服务端只写了 filename= 加中文原名，本地 Chrome 一切正常；联调当天，旧内核机器下载出来的名字成了一串 %E4，运营没法按名字区分批次。

做法是补齐三层：先定 ASCII 兜底名（业务词加日期或单号，全程字母数字下划线），再按 UTF-8 字节生成 filename*，两个字段一起写进同一个头，拼之前把斜杠、换行、分号、引号剔掉，最后让前端 blob 下载补上 download 属性。代价是返工：来回多走一轮回归，整体多花两三天，属于常见区间中段。这类问题的成本不在改代码，而在发现得晚，把多客户端命名验证放进提测阶段，通常比上线后等客户反馈省事。

四、适用与不适用边界

这套做法适合导出报表、附件下载、批量打包这类由浏览器直接保存到本地的场景，也适合下载接口对外开放时把命名约定写进对接文档。边界同样明确：

• 适合：中文名导出、客户内网旧终端、运营要按文件名区分批次、对接方明确要求中文名。
• 不必上：文件名全英文数字的内部接口；纯 API 返回文件流或 base64、由前端自行保存的场景，此时响应头不参与取名。
• 另需注意：透传用户上传的原始文件名时，先做长度截断和非法字符过滤，否则除了乱码还会遇到同名覆盖。
• 容易白改一轮的地方：头在源站改了，用户命中的却是 CDN 或对象存储直链，需要在那一层做同样的设置；部分反向代理会按 latin-1 处理头字段，排查时务必看客户端实际收到的头，不要只看应用日志。

常见问题

ASCII 兜底名和 filename* 都补上了，个别客户端还是显示 %E4，该怎么查？

先抓客户端实际收到的响应头。常见原因是 filename* 没有整体按 UTF-8 字节做百分号编码，或者前端下载时又用 URL 末段覆盖了名字，这两处都不在应用日志里体现。

文件名里的空格、括号、分号要不要一起编码？

建议编码或替换。filename* 只保证部分字符安全，空格、括号、分号原样保留时，可能被代理或解析器截断，表现为后半截名字消失，甚至整次下载失效。

前端用 blob 下载，服务端头写对了名字还是不对，为什么？

blob 方式下文件名取自 a 标签的 download 属性，没设就退回 URL 末段，服务端头在这条路径上基本不参与。两条下载路径要分别验证，不能只看一边。

CSV 用 Excel 打开内容乱码，和文件名乱码是一回事吗？

不是。文件名乱码出在响应头的字段和编码声明，内容乱码多与文件本身编码或缺少 BOM 有关，是两处独立问题，需要分开核对。

动手前可以先做一件小事：把当前导出接口的响应头抓下来，确认 filename 与 filename* 是否都在、编码是否正确，再用两三个客户端各下一次做比对。中文名导出、客户内网终端这类场景值得按要求核对一遍；纯英文名接口或由前端自行保存文件的情况则不必额外加工，避免把简单问题做复杂。