导航菜单

  • 1.claudecode
  • 2.claudecode
  • readline
  • iconv-lite
  • 1. 学前准备：你需要先懂什么
    • 1.1 字符编码是什么
    • 1.2 Buffer 是什么
    • 1.3 安装第三方包
  • 2. iconv-lite 解决什么问题
  • 3. 安装与第一个可运行示例
  • 4. encode：字符串 → Buffer
  • 5. decode：Buffer → 字符串
  • 6. encodingExists：检查编码名是否支持
  • 7. GBK 文件读写
  • 8. 新手常用编码（简表）
  • 9. 注意事项
    • 9.1 目标编码里不存在的字符
    • 9.2 不要混用错误的 fs 编码选项
    • 9.3 与 Node 内置 buffer.toString('utf8') 的分工
  • 10. 知识点速查

1. 学前准备：你需要先懂什么 #

下面三块若完全陌生，建议先花十几分钟理解概念，再往下写代码。

1.1 字符编码是什么 #

计算机里文字最终都是字节。同一段字节，用不同「编码规则」解释，会得到不同文字。新手最常碰到的两种：

名称 常见场景
UTF-8 现代网站、JSON、Node 源码文件、终端默认倾向
GBK / GB2312 部分 Windows 记事本保存的 txt、老系统接口、国内部分 CSV/日志

Node 里你写的 "你好" 这种字符串字面量，在内存里按 Unicode 处理；但磁盘上的文件或网络收到的二进制，可能是 GBK 存的——这时就需要 iconv-lite 做转换。

1.2 Buffer 是什么 #

Buffer 是 Node 里表示原始字节的类型，类似「字节数组」。iconv-lite 的 encode 会得到 Buffer，decode 的第一个参数通常是 Buffer。你不需要先精通 Buffer，只要知道：要按 GBK 读文件时，先用 fs.readFile 读成 Buffer，再 decode。

1.3 安装第三方包 #

iconv-lite 不是 Node 内置模块，需要先在一个项目目录里初始化并安装（见第 2 节）。运行示例前，请在该目录执行过 npm install iconv-lite。

2. iconv-lite 解决什么问题 #

日常开发里，JavaScript 字符串默认按 UTF-8 思维 工作；而你可能收到或要写出 GBK 字节。若直接把 GBK 的 Buffer 当成 UTF-8 去 toString('utf8')，中文往往会变成乱码（常见是 或问号）。

iconv-lite 的作用可以概括成两句话：

  • encode(字符串, 编码名)：把 JS 字符串 → 指定编码的 Buffer
  • decode(Buffer, 编码名)：把指定编码的 Buffer → JS 字符串

它是纯 JavaScript 实现，安装时一般不需要编译 C++ 扩展，在 Windows 上也比较省心。

3. 安装与第一个可运行示例 #

在你要放练习脚本的文件夹里打开终端（PowerShell 或 CMD），依次执行下面命令。这会生成 package.json 并安装 iconv-lite。

npm init -y
npm install iconv-lite

安装完成后，把下面整段保存为 01-hello.js，在同一目录执行 node 01-hello.js，应看到两行相同的中文输出。

// 引入已安装的 iconv-lite
const iconv = require('iconv-lite');

// 一段要在内存里处理的 UTF-8 字符串（源码里写的汉字）
const text = '你好，iconv-lite！';

// 把字符串按 GBK 规则编成字节 Buffer
const gbkBuffer = iconv.encode(text, 'gbk');

// 再把同一份 GBK 字节解码回 JS 字符串
const back = iconv.decode(gbkBuffer, 'gbk');

// 打印原始字符串
console.log('原文:', text);
// 打印解码结果，应与原文一致
console.log('往返:', back);

说明： 这个例子没有读写文件，只为了确认「安装成功 + 编解码往返正确」。

4. encode：字符串 → Buffer #

iconv.encode(字符串, 编码名) 返回一个 Buffer，里面是目标编码下的字节，可写入文件或发给只认 GBK 的旧系统。

下面示例会把 GBK 字节写入当前目录的 demo-gbk.txt，并打印 Buffer 长度。保存为 02-encode.js 后运行。

// 引入 iconv-lite
const iconv = require('iconv-lite');
// 引入文件系统模块
const fs = require('fs');
// 引入路径模块，方便拼文件名
const path = require('path');

// 要转换的中文内容
const text = '你好，世界！';

// 编码为 GBK 字节
const gbkBuffer = iconv.encode(text, 'gbk');

// 目标文件路径（与脚本同目录）
const outPath = path.join(__dirname, 'demo-gbk.txt');

// 把 GBK 字节原样写入文件（不要再用 utf8 去写）
fs.writeFileSync(outPath, gbkBuffer);

// 输出字节长度，便于感受「一个汉字在 GBK 里通常 2 字节」
console.log('已写入:', outPath);
// 打印 Buffer 字节数
console.log('GBK 字节长度:', gbkBuffer.length);

用记事本打开 demo-gbk.txt 时，若编码选 ANSI/GBK，应能正常看到「你好，世界！」；若用 UTF-8 方式打开可能显示乱码，这是正常现象，说明文件确实是按 GBK 存的。

5. decode：Buffer → 字符串 #

iconv.decode(buffer, 编码名) 把已知编码的字节解释成 JavaScript 字符串。读 GBK 文件时，应使用 fs.readFile 不要带 encoding: 'utf8'（否则 Node 会先按 UTF-8 误解一遍）。

下面脚本会先写入再读取同一个 GBK 文件，保证你复制即可运行。保存为 03-decode.js。

// 引入 iconv-lite
const iconv = require('iconv-lite');
// 引入 fs
const fs = require('fs');
// 引入 path
const path = require('path');

// 演示文件路径
const filePath = path.join(__dirname, 'read-gbk-demo.txt');

// 先用 iconv 生成 GBK 内容并写入（模拟「别人给你的 GBK 文件」）
const original = '这是 GBK 文件里的句子。';
// 写成 GBK 字节
fs.writeFileSync(filePath, iconv.encode(original, 'gbk'));

// 以二进制方式读入，得到 Buffer（不要 encoding: 'utf8'）
const rawBuffer = fs.readFileSync(filePath);

// 按 GBK 解码为字符串
const text = iconv.decode(rawBuffer, 'gbk');

// 打印读到的文字
console.log('解码结果:', text);
// 与原文对比
console.log('是否一致:', text === original);

常见错误： 对 GBK 文件使用 fs.readFileSync(path, 'utf8')，或在 decode 之前已经对 Buffer 做过错误的 toString('utf8')。

6. encodingExists：检查编码名是否支持 #

在转换前，可以用 iconv.encodingExists('编码名') 判断当前安装的 iconv-lite 是否认识该名称（返回 true / false）。名称不区分大小写的情况较多，但建议与文档一致，例如 'gbk'、'big5'。

保存为 04-encoding-exists.js 可直接运行。

// 引入 iconv-lite
const iconv = require('iconv-lite');

// 国内常见的 GBK，一般支持
const hasGbk = iconv.encodingExists('gbk');
// 故意写一个不存在的名字
const hasFoo = iconv.encodingExists('not-a-real-encoding');

// 打印 GBK 是否存在
console.log('gbk 支持吗?', hasGbk);
// 打印假编码是否存在
console.log('假编码支持吗?', hasFoo);

// 根据结果决定是否继续业务逻辑
if (!hasGbk) {
  // 若不支持则提前退出（极少见）
  console.error('当前环境不支持 gbk');
  // 非 0 退出码
  process.exit(1);
}

// 支持则正常编码一行字
const buf = iconv.encode('测试', 'gbk');
// 打印字节长度
console.log('encode 成功，字节数:', buf.length);

7. GBK 文件读写 #

把「编码写入 → 二进制读取 → 解码打印」合成一个脚本，最接近真实业务。保存为 05-roundtrip-file.js。

// 引入 iconv-lite
const iconv = require('iconv-lite');
// 引入 fs
const fs = require('fs');
// 引入 path
const path = require('path');

// 本次练习用的文件路径
const filePath = path.join(__dirname, 'roundtrip-gbk.txt');

// 业务上要保存的中文
const message = '一条龙：写入 GBK，再读回来。';

// 第一步：encode 后写入磁盘
fs.writeFileSync(filePath, iconv.encode(message, 'gbk'));
// 提示写入完成
console.log('[写] 已保存 GBK 文件:', filePath);

// 第二步：按二进制读回 Buffer
const buf = fs.readFileSync(filePath);
// 第三步：decode 成字符串
const read = iconv.decode(buf, 'gbk');
// 打印读到的内容
console.log('[读] 内容:', read);
// 验证与原文一致
console.log('[验] 一致:', read === message);

8. 新手常用编码（简表） #

不必背全表，遇到再查即可。下表覆盖国内脚本里最常见的几项。

编码名 典型用途
utf8 现代文本、API、JSON（Node 默认思维）
gbk Windows 简体环境导出的 txt、部分老接口
gb2312 更老的简体系统，字符集比 GBK 少
big5 繁体中文（台湾地区常见）

若 encodingExists 返回 false，请检查拼写；不要用自创名字。

9. 注意事项 #

9.1 目标编码里不存在的字符 #

若某个字在目标编码（例如 GBK）里没有对应字形，iconv-lite 往往会用 ? 或 （替换字符） 代替，而不会像人工翻译那样「音译」。写文件前若内容很生僻，建议先在小样本上 encode 再 decode 看是否丢字。

9.2 不要混用错误的 fs 编码选项 #

操作 推荐做法
读 GBK 文件 fs.readFileSync(path) 得到 Buffer → iconv.decode(buf, 'gbk')
写 GBK 文件 iconv.encode(str, 'gbk') → fs.writeFileSync(path, buffer)
避免 读文件时 encoding: 'utf8'，或对已是乱码的字符串再次 decode

9.3 与 Node 内置 buffer.toString('utf8') 的分工 #

UTF-8 文件：直接用 fs.readFileSync(path, 'utf8') 即可，不必上 iconv-lite。明确是 GBK 等其它编码 时，才用本库。

10. 知识点速查 #

主题 记住这一句
安装 项目目录内 npm install iconv-lite
字符串 → 字节 iconv.encode(str, 'gbk') 得到 Buffer
字节 → 字符串 iconv.decode(buffer, 'gbk')
是否支持某编码 iconv.encodingExists('gbk')
读 GBK 文件 二进制读 Buffer，再 decode，不要先当 UTF-8 读

建议按顺序运行 01-hello.js～05-roundtrip-file.js，每改一行观察输出，比只读文档更快建立直觉。若你之后需要处理超大文件或网络流，再查阅官方文档中的 decodeStream / encodeStream（本入门教程未展开）。

← 上一节 2.claudecode 下一节 readline →

访问验证

请输入访问令牌

Token不正确，请重新输入