做前端对接老系统接口的时候，最怕遇到两件事：一是接口文档不写清楚，二是响应回来中文乱码。乱码这玩意儿尤其坑，因为它不是你代码逻辑错了，而是编码链路某处断了。最近处理一个“fetch请求响应用GBK解码”的需求，从浏览器到Node都踩了一遍，把原理和坑梳理清楚以后，其实解法就那几步。如果你也在跟GBK老接口死磕，或者看到response.text()出来的中文变成了“锟斤拷”“�”这种火星文，这篇文章可以直接当工具文收藏。
先说结论：fetch默认把响应体当作UTF-8解码，遇到GBK字节流必然乱码。要让fetch正确解码GBK，核心思路是先用response.arrayBuffer()拿到原始字节，再用TextDecoder('gbk')手动解码。后面我会解释为什么必须这样做、浏览器和Node有什么区别，以及遇到“乱码已经生成”的现场怎么救回来。
1. 乱码是怎么发生的：先搞懂编码链路
1.1 字符编码101：GBK和UTF-8的底层差异
要解决乱码，得先明白乱码是怎么来的。字符编码本质上是“字符”和“字节”之间的映射规则。GBK是一个双字节编码方案，它兼容ASCII，英文字母和符号占1字节，常用中文占2字节，也覆盖了GB2312的全部字符。UTF-8是变长编码，ASCII字符占1字节，中文通常占3字节，而且它有非常严格的字节格式校验规则。
举个例子，“中”这个字：
- GBK编码是：
D6 D0（2字节） - UTF-8编码是：
E4 B8 AD（3字节）
同一个字符，两种编码下字节完全不同。当服务器用GBK输出字节流，而客户端却拿着UTF-8的解码表去解析，结果就是要么出现“�”这样的替换字符，要么出现一堆乱码字。你可以把编码想象成一套暗号规则：收信人拿错了密码本，自然解不出正确信息。HTTP传输的本质就是字节流，字符编码的问题只会在“字节变成字符串”这最后一公里爆发。
1.2 fetch默认按UTF-8解码，问题正在这里
浏览器里的fetch提供了一个很方便的response.text()方法，这个方法会把响应体整个读出来，并且按照某种规则转换成JavaScript字符串。关键点在于：这个规则在现代浏览器里基本默认是UTF-8。
有人会问：如果响应头Content-Type里写了charset=utf-8，那我没写charset的时候，服务器会发GBK吗？实际情况是，很多老系统，尤其是企业内部系统，后端返回application/json或者text/html时压根不带charset，甚至带了charset=utf-8但实际输出的是GBK编码。这个时候response.text()就会按UTF-8去解码GBK字节，出来的东西当然不能看。
这里还要记住一个容易忽略的细节：response.text()是一个“消费body”的操作。响应体一旦被读走，response.arrayBuffer()和response.blob()就都不能用了，因为body流已经被消耗掉。所以如果你想自己解码，从一开始就要决定用arrayBuffer()而不是text()。
1.3 响应的“编码声明”为什么经常被忽略
理论上，HTTP响应头里的Content-Type应该告诉我们编码，比如：
Content-Type: application/json; charset=gbk这个声明是标准的，但现实里它经常缺席或者不可靠。我见过几种典型情况：
- 后端完全不设置charset，只写
Content-Type: application/json。 - 后端统一返回
text/html; charset=utf-8，但代码里拿到的字符串是用老系统组件拼出来的GBK。 - 中间有网关或者负载均衡设备重写了响应头，把charset丢弃了。
- 接口文档声称GBK，实际返回的是UTF-8，或者反过来。
所以，客户端如果把解码这件事完全交给fetch，就是把自己的正确显示建立在对方正确的声明之上。而老系统的响应头，恰恰是最不靠谱的。这也是为什么我们必须把解码主动权拿回到自己手里：先看原始字节，再决定用什么编码去解。
2. 核心方案：fetch配合TextDecoder完成GBK解码
2.1 正确姿势：用arrayBuffer拿到原始字节
要正确处理GBK响应，最简单的方案是绕过fetch默认的解码逻辑，直接拿原始字节。流程分三步：
fetch(url)拿到响应对象。response.arrayBuffer()得到ArrayBuffer。new TextDecoder('gbk').decode(new Uint8Array(buffer))手动解码。
代码长这样：
async function fetchGBK(url, options = {}) { const response = await fetch(url, options); if (!response.ok) { throw new Error(`HTTP error: ${response.status}`); } const buffer = await response.arrayBuffer(); const decoder = new TextDecoder('gbk'); const text = decoder.decode(new Uint8Array(buffer)); return text; }这里有几个关键点。第一，TextDecoder.decode()接收的是BufferSource，所以必须把ArrayBuffer用Uint8Array包一层。第二，TextDecoder('gbk')在浏览器里是合法的构造参数，按照WHATWG Encoding规范，gbk是一个有效的编码标签。第三，如果在调用fetch之后、arrayBuffer()之前，有人先调用了response.text()，那么body已经被消费，后面的解码会直接抛异常或者拿到空结果。
这就是我前面强调的：一旦决定自己解码，就要彻底放弃response.text()，别两头都不靠。
2.2 TextDecoder('gbk')的浏览器支持与兼容性边界
TextDecoder是现代浏览器都支持的API，但“支持到什么编码”有讲究。按规范，new TextDecoder('gbk')在Chrome、Firefox、Safari、Edge里都能正常工作，读取的编码映射也覆盖GBK字符集。如果你在老一点的环境里遇到不支持，可以考虑用gb2312作为标签，或者引入text-encoding这个polyfill。
有一点需要特别说明：GBK是GB2312的超集，GB2312缺一些生僻字、繁体字和符号。所以能写gbk就不要写gb2312，否则遇到冷门字符，解码结果可能会变“�”或者缺字。
另外，Node.js环境要特别小心。Node自带的util.TextDecoder依赖ICU（International Components for Unicode）。如果Node编译时用的是small-icu，gbk不一定支持；完整版ICU可能支持。但为了保险，Node后端请直接使用iconv-lite，这个库专门处理各种非UTF-8编码，API简单稳定。这一部分我会在第3章详细展开。
2.3 自动识别charset并封装通用函数
实际开发中，我们不可能每次都硬编码GBK。更好的做法是：先从响应头里尝试拿到charset，拿到就按它解码；拿不到或者解码结果看起来不对，再回退到GBK。
解析charset的正则很简单：
function getCharset(contentType) { const match = (contentType || '').match(/charset\s*=\s*"?([^";\s]+)"?/i); return match ? match[1].toLowerCase() : null; }然后做一个自动解码函数：
async function fetchTextAuto(url, options = {}) { const response = await fetch(url, options); const buffer = await response.arrayBuffer(); const bytes = new Uint8Array(buffer); const contentType = response.headers.get('content-type') || ''; let charset = getCharset(contentType); // 优先按声明解码 if (charset) { try { const text = new TextDecoder(charset).decode(bytes); // 如果出现替换字符，说明声明很可能不对 if (!text.includes('\uFFFD')) { return text; } } catch (e) { // 不支持的编码，继续往下走 } } // 回退到GBK return new TextDecoder('gbk').decode(bytes); }这里用\uFFFD（就是�）来检测解码错误，算是一种常见经验。如果charset声明是utf-8，但实际字节是GBK，UTF-8解码器遇到非法字节就会产生�，这时候说明声明不可信，于是回退到GBK再试一次。
当然，这个检测不是万无一失的，因为某些双字节组合在UTF-8里可能恰好合法但出来的是别的字。但在我处理老系统接口的真实场景里，这种“声明优先，�触发回退”的策略已经能覆盖90%的情况。如果仍不放心，就在调用时显式传入charset，让使用者自己定。
3. 多环境实战：Node端、乱码已发生和未知编码场景
3.1 Node环境下的fetch/axios GBK解码
Node 18以后有了全局fetch，但它的实现（undici）在解码GBK上并不友好。Node自带的TextDecoder如果你能确认完整ICU支持，也可以试试：
const { TextDecoder } = require('util'); const decoder = new TextDecoder('gbk'); const text = decoder.decode(new Uint8Array(buffer));但注意，很多默认编译的Node并不支持gbk，运行时会抛TypeError: The "gbk" encoding is not supported。这时候最稳妥的方案是用iconv-lite：
npm install iconv-lite然后这样解码：
const iconv = require('iconv-lite'); async function fetchGBKNode(url, options = {}) { const response = await fetch(url, options); const arrayBuffer = await response.arrayBuffer(); const buffer = Buffer.from(arrayBuffer); return iconv.decode(buffer, 'gbk'); }如果你用的是axios，问题会更隐蔽。axios默认会把响应按UTF-8解析成字符串，你拿到response.data的时候可能已经乱码了。解决方法是把responseType设置成arraybuffer，然后再自己解码：
const axios = require('axios'); const iconv = require('iconv-lite'); const response = await axios.get(url, { responseType: 'arraybuffer' }); const text = iconv.decode(Buffer.from(response.data), 'gbk');之所以要Buffer.from(response.data)，是因为axios的arraybuffer在Node里可能表现为Buffer，也可能表现为ArrayBuffer，统一转一下更保险。直接把ArrayBuffer丢给iconv.decode是不行的，它只认Buffer或字符串。
3.2 乱码字符的逆向修复：从“锟斤拷”救回数据
有一种让人头疼的情况：不是从接口直接拿乱码，而是已经从数据库、日志或者消息队列里存了一段乱码字符串，比如“锟斤拷”。你有没有想过，这三个字为什么成了乱码的代名词？
其实原因很经典：假设原始字符是“中文”，它被UTF-8编码成字节流后，如果某个环节用GBK去解码，遇到无法识别的字节，解码器就会用U+FFFD替换字符（�）。这个替换字符再经过GBK编码，就会变成EF BF BD对应的汉字——恰好就是“锟斤拷”。所以“锟斤拷”实际上是“UTF-8字节流被GBK解码并多次替换”的痕迹。
如果我手里只有乱码字符串，原始字节已经丢了，能救回来吗？有一种场景可以救：乱码字符串本身仍然是合法字符，我们可以用UTF-8编码器把它重新变成字节，再用GBK解码。因为乱码字符串对应的字节可能正好是原始字节的一部分。示例：
function recoverMojibake(mojibake) { const bytes = new TextEncoder().encode(mojibake); return new TextDecoder('gbk').decode(bytes); }这个函数的原理就是“把当前字符串按UTF-8编码成字节，再用GBK解回来”。它只适用于部分单层乱码。如果经历过多次编码转换、丢字节或者被替换成“锟斤拷”这种占位符，信息已经损失，就救不回了。
所以我的态度很明确：宁可源头用arrayBuffer()保存字节，也不要事后在乱码字符串上做逆向工程。逆向只是应急手段，不是常规方案。
3.3 编码自动检测：不知道源编码时怎么办
如果响应头没有charset，我们也不确定到底是GBK还是UTF-8，这时候可以做一次“盲测”。常见做法是：
- 先尝试UTF-8合法性校验。
- 如果字节流能通过UTF-8的格式要求，大概率是UTF-8。
- 如果大量字节落在GBK汉字区，且能按GBK解出通顺中文，就是GBK。
这种人工判断可以用库来完成。浏览器端可以用jschardet，Node端也能用chardet或jschardet。示例：
const jschardet = require('jschardet'); const iconv = require('iconv-lite'); const buffer = Buffer.from(await response.arrayBuffer()); const result = jschardet.detect(buffer); const charset = result.encoding.toLowerCase(); const text = iconv.decode(buffer, charset);但我要提醒一句：编码检测不是100%可靠，尤其是文本很短的时候，误判率会明显上升。生产环境最好还是让后端把charset修好，或者先确认接口文档，别把检测库当成银弹。检测库更多是“辅助排查”的角色，而不是“最终方案”。
4. 完整示例：封装一个好用的fetchGBK模块
4.1 从零实现：fetchGBK函数代码与说明
综合前面的原理，我们可以封装一个比较完整的前端公共模块。它应该支持：
- 默认按GBK解码。
- 允许调用方显式指定charset。
- 返回原始
response和解析后的文本。 - 方便解析JSON时清理BOM。
代码如下：
export async function fetchGBK(url, options = {}) { const { charset = 'gbk', responseType = 'text', ...fetchOptions } = options; const response = await fetch(url, fetchOptions); const buffer = await response.arrayBuffer(); const bytes = new Uint8Array(buffer); let text; try { text = new TextDecoder(charset).decode(bytes); } catch (e) { throw new Error(`不支持的字符集: ${charset}`); } if (responseType === 'json') { try { // 去掉BOM后解析，避免JSON.parse报错 const data = JSON.parse(text.replace(/^\uFEFF/, '')); return { response, data }; } catch (e) { throw new Error(`JSON解析失败，前200字符为: ${text.slice(0, 200)}`); } } return { response, text }; }用法很简单：
const { text } = await fetchGBK('/api/legacy/list', { charset: 'gbk' });如果接口返回的是JSON：
const { data } = await fetchGBK('/api/legacy/detail', { responseType: 'json' });这里responseType参数是我自己设计的，用来告诉模块是否进一步做JSON解析。注意，JSON.parse之前剔除\uFEFF很重要。因为某些老系统会在文件开头输出BOM，也就是EF BB BF，解码成字符串后会有不可见的\uFEFF字符，直接JSON.parse会报错。
4.2 处理JSON和HTML不同内容的细节
GBK接口最常见的就是两种返回：JSON和HTML。
先聊JSON。很多人以为JSON必须是UTF-8，其实不是。JSON作为一种文本格式，只要最后能被解析成合法字符串就行。我们拿GBK字节流用TextDecoder('gbk')解出字符串，再JSON.parse，完全没问题。唯一的坑就是BOM，上面已经讲了。
再聊HTML。如果你拿到的是GBK编码的HTML，正确做法是先用fetchGBK把文本解出来，再用DOMParser解析。不要直接把这个HTML字符串交给DOMParser让它自动检测编码，因为你已经手动解码过一次，HTML里的<meta charset="gbk">可能会干扰后续处理。示例：
const { text } = await fetchGBK('/legacy/page.html', { charset: 'gbk' }); const doc = new DOMParser().parseFromString(text, 'text/html');这时文档里的中文已经是正确字符串，DOMParser再解析时不会重新经历编码转换。如果你反过来，直接fetch('/legacy/page.html').then(r => r.text())，那么很可能在r.text()那一步就已经乱码了，后面做什么都晚了。
4.3 性能、缓存与异常处理建议
用arrayBuffer()会把整个响应体一次性读入内存。对小接口无所谓，但如果是一个几MB的GBK文本，内存占用会比较明显。此时可以用流式解码，配合TextDecoder的stream选项，把字节分块读取、分块解码：
async function fetchGBKStream(url, options = {}) { const response = await fetch(url, options); const reader = response.body.getReader(); const decoder = new TextDecoder('gbk'); let result = ''; while (true) { const { value, done } = await reader.read(); if (done) break; // stream: true 让解码器保留跨块的不完整字节 result += decoder.decode(value, { stream: true }); } result += decoder.decode(); // flush return result; }这个方案有两个好处：第一，不用等整个响应体加载完才开始处理；第二，GBK多字节字符可能被分块切断，stream模式会帮我们缓存不完整的字节，下一块到达时自动拼接。
异常处理方面，我建议至少做到：
- 对
response.ok做判断，HTTP非2xx直接抛出或单独处理。 - 对
TextDecoder不支持指定charset的情况做兜底。 - 对JSON解析失败，把前200字符带进错误信息，方便排查。
- 如果
response.bodyUsed为true，说明body已经被消费，要立刻定位代码顺序问题。
5. 常见问题与排查技巧实录
5.1 遇到“�”替换字符怎么办
“�”的学名是U+FFFD，是解码器遇到无法映射的字节时放在结果里的“占位符”。如果你看到每个中文位置都是�，或者中文后面跟一串�，那基本可以断定：字节流被错误的解码方式处理了。
排查步骤按顺序来：
- 先确认响应头里有没有charset，以及它写的是什么。
- 把响应体拿到手，别用
text()，用arrayBuffer()存住字节。 - 用十六进制查看前几十个字节，如果看到大量
D6 D0这类GBK汉字区字节，基本是GBK。 - 用
new TextDecoder('gbk')重新解码，如果�消失，说明就是UTF-8解码器硬解GBK导致的。
这个“先看字节再选解码器”的思路，能解决一大半乱码问题。你不需要背编码表，只要记住：字节是客观存在的，乱码是“解码器选错”的主观结果。
5.2 遇到“锟斤拷”怎么办
“锟斤拷”不是一种普通乱码，它几乎成了编码事故的代名词。它出现的本质是：UTF-8字节被GBK解码后，无效字节被替换成U+FFFD，再经过编码转换变成“锟斤拷”等汉字。
遇到这种情况，最稳妥的办法是回到源头重新用arrayBuffer()取字节，然后用正确的编码解码。如果源头数据已经丢失，只能尝试第3章的逆向修复函数，但成功率取决于实际转换链路。
我还要强调一点：存储数据时一定要保留编码信息。比如在数据库里存文本时，统一转成UTF-8并标记；在日志里输出时，看到乱码就不要再写到库里了，不然后面根本无从查起。我见过很多团队为了图快，把已经乱码的字符串存进数据库，结果后续排查的人越看越乱。
5.3 排查思路速查表
| 现象 | 可能原因 | 推荐方案 |
|---|---|---|
| 中文全部变成“�” | 用UTF-8解码GBK字节，遇到非法字符被替换 | 改用TextDecoder('gbk')重新解码 |
| 出现“锟斤拷” | UTF-8字节被GBK解码，再经历替换字符编码 | 回到源头保存字节，重新解码；或尝试逆向修复 |
| 中文正常但JSON.parse报错 | 文本开头有BOM | text.replace(/^\uFEFF/, '')后再parse |
Node端TextDecoder抛编码不支持 | Node未启用完整ICU | 改用iconv-lite解码Buffer |
| 接口头写utf-8但实际GBK | 后端配置错误或网关改写响应头 | 检测到�后回退GBK，或让后端修正 |
| 大响应解码时卡顿/内存高 | 一次性arrayBuffer()读取 | 改流式解码，配合{ stream: true } |
这张表是我实际排查问题时的“第一反应”。如果你看到某个现象，先对号入座，能省很多时间。
5.4 几个容易忽略的编码坑
最后再列几个我踩过或者说常见的坑，都是细节，但都可能导致乱码。
第一个坑：response.bodyUsed。body只能读一次。如果你想在读取后既保留文本，又想拿buffer做别的事，对不起做不到。正确做法是在读取buffer后自己存一份副本。
第二个坑：请求头里的Accept-Charset并不能强制服务器返回指定编码。它只是告诉服务器“我优先能处理哪些字符集”，而老后端很可能根本无视它。别指望设置这个头就能让服务器吐GBK给你。
第三个坑：console.log显示正常不代表真的正常。很多浏览器的控制台会自己尝试美化输出，有些情况下会把乱码字符悄悄转换或显示成别的样子。要以字节和TextDecoder的结果为准。
第四个坑：如果你在中间处理环节把文本转成Base64，再解码出来，编码信息可能已经被破坏。遇到GBK接口，尽量保持“原始字节 -> 字符串”的单向一步转换，不要中间插入“先转Base64再回来”这种多余动作。
第五个坑：有些老系统会返回Content-Type: text/plain; charset=gb2312，但实际可能包含GBK扩展字符。别因为写了gb2312就死咬着不换，如果解码出来有缺字，立刻试试用gbk标签解码。
做这行越久，越觉得编码问题不是靠背编码表解决的。核心只有一条原则：永远把“字节”和“字符串”拆开看。字节是流，字符串是解码后的视图。你用哪张解码表，决定了看到的是中文还是天书。我在实际处理里，只要对接外部接口涉及中文，一律先拿arrayBuffer再决定解码方式，绝不让框架替我做这个决定。
最后再分享一个小技巧：调试编码问题时，别只盯着console。打开DevTools的Network面板，看看响应头里的charset；再用fetch断点看arrayBuffer的十六进制。比如“中”字的GBK字节是D6 D0，看到这个基本就可以断定该用GBK解码。这个方法比任何工具都直接，也是我快速判断老接口编码的首选。
