Node.js 执行 JS 文件输出中文乱码的解决方法
针对 Windows 终端下使用 Node.js 执行 JS 脚本输出中文乱码的典型问题,深入解析字符集编码与活动代码页错位的底层机理,提供修改文件保存格式、切换终端代码页、读取外部 GBK 文件等全流程排查方法与实战方案。
console.log('你好,世界') 经常变成一串看不懂的方块、问号或“浣犲ソ”等乱码。造成这一现象的根本原因只有两处:一是 JS 源码文件本身的物理保存编码不是 UTF-8,导致 Node.js 引擎在语法解析阶段即按错误编码取值;二是命令行控制台的当前活动代码页不是 UTF-8(代码页 65001),导致终端无法正确解码 Node.js 输出的标准 UTF-8 字节流。只要按照“统一源码保存格式”与“切换终端活动代码页”两步操作,就能彻底解决乱码。
一、中文乱码的底层成因:字节流与代码页不匹配
在深入具体操作之前,需要理清字符在计算机中的流转链路。JavaScript 规范在语言层面对字符串统一使用 Unicode(UTF-16)表示,而在 Node.js 运行时执行脚本时,会将源码中的字面量序列化为 UTF-8 字节流推向标准输出接口(process.stdout)。UTF-8 是一种变长编码,一个标准的汉字通常占用 3 个字节(例如“你”字的 UTF-8 编码为 0xE4 0xBD 0xA0)。
然而,中文版 Windows 系统的经典命令提示符(cmd.exe)默认采用 CP936 代码页(即扩展的 GBK 编码)。GBK 采用双字节编码,即每个汉字由 2 个字节 构成。当 Node.js 的 3 字节 UTF-8 二进制流推送到 CMD 终端时,CMD 依然按照每 2 个字节为一个单元去强行截断并检索 GBK 码表。这种字节边界的错位,直接导致了经典的“乱码字符对”(如常见的“锟斤拷”或“浣犲ソ”)。
由此可见,解决输出乱码的核心原则是保证输入与输出链路编码对齐:既要让 Node.js 读到干净的 UTF-8 源码,又要让运行终端按 UTF-8 规则进行双向解码渲染。
二、解决步骤一:确认并转换 JS 源码文件编码为 UTF-8
排查的第一步是检查源文件。如果编写代码时使用了 Windows 记事本、某些旧版文本编辑器,或从外部压缩包解压了历史代码,文件很容易被自动保存为 ANSI 或 GBK 格式。当 Node.js 引擎读取此类文件时,首层语法分析就会将错误的字节当作字符串,即便后续终端配置正确也无法挽回。
1. 在 VS Code 中检查与转换编码
以现代主流编辑器 VS Code 为例,确认与修改编码的标准流程如下:
- 使用 VS Code 打开出现乱码的
.js文件。 - 观察编辑器右下角状态栏。正常情况下应显示
UTF-8。如果显示为GBK、GB2312、CP936或Windows-1252,说明文件编码异常。 - 单击右下角显示的编码名称,顶部居中会弹出操作面板,提供两个选项:“通过编码重新打开 (Reopen with Encoding)” 和 “通过编码保存 (Save with Encoding)”。
- 如果编辑器内此时中文看起来已经是乱码,先选“通过编码重新打开”,输入
GBK,确认文字恢复清晰;随后再次点击编码,选择“通过编码保存”,在列表中选择 UTF-8(切记不要选择 UTF-8 with BOM)。
部分 Windows 工具保存 UTF-8 时会默认附带 BOM(字节顺序标记,即文件头部的
0xEF 0xBB 0xBF 三个字节)。Node.js 在处理带 BOM 的源码时可能会引起部分打包工具或语法解析器的隐形异常,务必选择纯净的 UTF-8。
2. 编写测试验证文件
完成保存后,在工作目录下新建或修改为最基础的验证脚本,排除业务代码干扰。创建名为 test-encoding.js 的文件:
// test-encoding.js
// 简单的中文与符号打印测试
const message = "中文编码测试:你好,世界!";
console.log(message);
console.log("包含中文字符与标点:【提示】Node.js 执行正常。");
三、解决步骤二:切换命令行终端的活动代码页为 UTF-8
当确认源码文件已经是标准的无 BOM UTF-8 之后,如果在 Windows 终端运行仍然出现乱码,那么问题 100% 集中在终端环境的活动代码页上。
1. 经典命令提示符(CMD)快速修复
在 CMD 中,使用内置的 chcp(Change Code Page,修改代码页)命令切换为 UTF-8:
chcp 65001
执行命令后的控制台返回示例:
此时再次执行 node test-encoding.js,中文字符即可恢复清晰正常的显示。
关于 CMD 的作用域限制:通过 chcp 65001 修改代码页只在当前打开的 CMD 窗口会话中生效。一旦关闭并重新打开 CMD,代码页会恢复为默认的 936。如果不希望每次手动输入,可在 package.json 中把启动命令进行组合封装:
{
"scripts": {
"start": "chcp 65001 >nul && node test-encoding.js"
}
}
2. PowerShell 终端环境修复与持久化
如果日常使用的是 Windows PowerShell,在遇到中文乱码时,可通过调整控制台输出编码对象来解决:
# 临时为当前 PowerShell 会话设置输出编码为 UTF-8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
若要永久生效,无需每次开机手动输入,可将上述指令写入 PowerShell 用户配置文件中:
- 在 PowerShell 中执行命令查看配置文件路径:
$PROFILE。 - 如果文件不存在,执行命令自动创建:
New-Item -Type File -Path $PROFILE -Force。 - 用文本编辑器打开该文件,将上面两行代码粘贴并保存。以后每次启动 PowerShell,终端都会默认以 UTF-8 运行。
3. 使用现代终端(Windows Terminal / VS Code 内置终端)
微软官方推出的 Windows Terminal 以及 VS Code 的内置集成终端采用了现代化的虚拟终端仿真(ConPTY)引擎。只要系统的区域和编辑器环境规范,它们默认即全面支持 UTF-8 字节渲染,并且在文字等宽排版、表情符号渲染上比老旧的 conhost.exe 健壮得多。对于长期从事 Node.js 开发的用户,推荐以 Windows Terminal 作为默认控制台。
四、进阶场景:Node.js 读取外部 GBK 文本时的乱码处理
在实际项目开发中,还有一种经常被误判为“控制台乱码”的情况:脚本内部直接写的 console.log('测试') 正常,但通过 fs.readFileSync() 读取政府系统、金融机构或传统 Excel 导出的 .csv 或 .txt 文件时,控制台输出全为乱码。
这是因为 Node.js 原生的 fs 模块仅内置支持 utf8、utf16le、latin1、base64、hex 和 ascii,并不支持直接将 encoding: 'gbk' 作为参数传给读取方法。如果盲目传入 fs.readFileSync('data.csv', 'utf-8'),Node.js 会强行用 UTF-8 解析 GBK 字节,导致数据从读取阶段就彻底损坏。
方法 1:使用现代 Node.js 原生内置的 TextDecoder(推荐,无需第三方包)
在现代 Node.js(Node.js 11+ 及所有主流 LTS 版本)中,全局内置了 Web 标准的 TextDecoder API,原生支持 gbk / gb18030 解码:
// read-gbk-native.js
const fs = require('fs');
// 1. 读取为原始的 Buffer 二进制数据,切勿指定 'utf-8' 字符串
const rawBuffer = fs.readFileSync('legacy-gbk-file.txt');
// 2. 实例化 GBK 解码器
const gbkDecoder = new TextDecoder('gbk');
// 3. 将 Buffer 精确解码为 JavaScript 内存字符串
const textContent = gbkDecoder.decode(rawBuffer);
console.log("读取解析结果:");
console.log(textContent);
方法 2:使用成熟第三方生态库 iconv-lite(适合复杂或老旧环境)
在需要双向转码(既需要读取 GBK,又需要将数据打包输出为 GBK 文件)的工程项目中,推荐使用广泛应用的 iconv-lite 库:
# 依赖安装
npm install iconv-lite
// read-gbk-iconv.js
const fs = require('fs');
const iconv = require('iconv-lite');
// 读取原始二进制字节
const buf = fs.readFileSync('legacy-gbk-file.txt');
// 通过 iconv 解码
const str = iconv.decode(buf, 'gbk');
console.log(str);
// 若需要向外部回写 GBK 编码数据
const outputBuffer = iconv.encode("需要写回的原生中文", 'gbk');
fs.writeFileSync('output-gbk.txt', outputBuffer);
五、全链路排查诊断决策树与工程防范
为了让排查过程条理清晰,面对任何 Node.js 中文乱码情况,均可依照下图决策路径定位问题层级:
团队协同中的工程化防范建议
在多人协作跨平台(Windows / macOS / Linux)开发时,为了杜绝某位成员使用默认编辑器创建了非 UTF-8 文件提交到代码仓库,建议在项目根目录下放置标准 .editorconfig 配置文件:
# .editorconfig 统一团队编码规范
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
主流现代 IDE(VS Code、WebStorm 等)均原生支持或可通过插件读取该配置,在新建或保存任何文件时强制将其限定为无 BOM 的 utf-8,从源头消灭跨环境编码分歧。
- 先查源码:检查编辑器右下角是否显示 UTF-8,杜绝 GBK 源码。
- 再调终端:CMD 下敲入
chcp 65001,确认活动代码页为 65001。 - 外源数据:读写外部 GBK 文件时,先读 Buffer,再用
TextDecoder('gbk')解码。 - 规范工具:推荐使用 Windows Terminal,并配置
.editorconfig统一团队标准。
怎么在Electron应用中集成Python环境供JS调用
2026-11-18 09:54:26
前端开发中怎么判断当前JS运行环境是浏览器还是Node.js
2026-11-17 21:01:18
OpenBot v1.1.0 正式版为什么会让部分旧接口返回 404?
2026-11-17 19:07:31
JDK 17移除Nashorn后,Java怎么执行JS脚本?
2026-11-17 11:59:41
如何用Node.js区分Claude Microsoft 365连接器与其他故障事件
2026-11-15 01:54:56








