Node.js 执行 JS 文件输出中文乱码的解决方法

作者:夜航船

时间:2026-11-19

浏览:361

针对 Windows 终端下使用 Node.js 执行 JS 脚本输出中文乱码的典型问题,深入解析字符集编码与活动代码页错位的底层机理,提供修改文件保存格式、切换终端代码页、读取外部 GBK 文件等全流程排查方法与实战方案。

文章目录
Node.js 运行时 字符编码诊断 适用系统:Windows 10 / 11 / Server 阅读时长:约 7 分钟
Node.js 执行 JS 文件输出中文乱码的解决方法
在 Windows 命令提示符(CMD)或 PowerShell 中执行 Node.js 脚本时,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 执行 JS 文件输出中文乱码的解决方法
图1:Node.js 标准输出流与终端字符集解码机制对照(路径A展示字节错位乱码机理,路径B展示对齐UTF-8后的正常还原流程)

由此可见,解决输出乱码的核心原则是保证输入与输出链路编码对齐:既要让 Node.js 读到干净的 UTF-8 源码,又要让运行终端按 UTF-8 规则进行双向解码渲染。

二、解决步骤一:确认并转换 JS 源码文件编码为 UTF-8

排查的第一步是检查源文件。如果编写代码时使用了 Windows 记事本、某些旧版文本编辑器,或从外部压缩包解压了历史代码,文件很容易被自动保存为 ANSI 或 GBK 格式。当 Node.js 引擎读取此类文件时,首层语法分析就会将错误的字节当作字符串,即便后续终端配置正确也无法挽回。

1. 在 VS Code 中检查与转换编码

以现代主流编辑器 VS Code 为例,确认与修改编码的标准流程如下:

  1. 使用 VS Code 打开出现乱码的 .js 文件。
  2. 观察编辑器右下角状态栏。正常情况下应显示 UTF-8。如果显示为 GBK、GB2312、CP936 或 Windows-1252,说明文件编码异常。
  3. 单击右下角显示的编码名称,顶部居中会弹出操作面板,提供两个选项:“通过编码重新打开 (Reopen with Encoding)” 和 “通过编码保存 (Save with Encoding)”。
  4. 如果编辑器内此时中文看起来已经是乱码,先选“通过编码重新打开”,输入 GBK,确认文字恢复清晰;随后再次点击编码,选择“通过编码保存”,在列表中选择 UTF-8(切记不要选择 UTF-8 with BOM)。
Node.js 执行 JS 文件输出中文乱码的解决方法
图2:源码文件编码排查与格式转换操作流程(重点遵循“先识别当前编码、再执行安全重存、最后编写用例验证”的执行路径)
注意事项:避免使用带 BOM 的 UTF-8
部分 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

执行命令后的控制台返回示例:

CMD 执行输出示例
C:\Projects\demo> chcp 65001 Active code page: 65001 C:\Projects\demo> node test-encoding.js 中文编码测试:你好,世界! 包含中文字符与标点:【提示】Node.js 执行正常。

此时再次执行 node test-encoding.js,中文字符即可恢复清晰正常的显示。

关于 CMD 的作用域限制:通过 chcp 65001 修改代码页只在当前打开的 CMD 窗口会话中生效。一旦关闭并重新打开 CMD,代码页会恢复为默认的 936。如果不希望每次手动输入,可在 package.json 中把启动命令进行组合封装:

{
  "scripts": {
    "start": "chcp 65001 >nul && node test-encoding.js"
  }
}
Node.js 执行 JS 文件输出中文乱码的解决方法
图3:Windows 常见命令行终端环境代码页配置与生效机制对比(对比经典 CMD、PowerShell 与现代化终端的持久化方案)

2. PowerShell 终端环境修复与持久化

如果日常使用的是 Windows PowerShell,在遇到中文乱码时,可通过调整控制台输出编码对象来解决:

# 临时为当前 PowerShell 会话设置输出编码为 UTF-8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

若要永久生效,无需每次开机手动输入,可将上述指令写入 PowerShell 用户配置文件中:

  1. 在 PowerShell 中执行命令查看配置文件路径:$PROFILE。
  2. 如果文件不存在,执行命令自动创建:New-Item -Type File -Path $PROFILE -Force。
  3. 用文本编辑器打开该文件,将上面两行代码粘贴并保存。以后每次启动 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 中文乱码情况,均可依照下图决策路径定位问题层级:

Node.js 执行 JS 文件输出中文乱码的解决方法
图4: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,从源头消灭跨环境编码分歧。

排查要点速记清单:
  1. 先查源码:检查编辑器右下角是否显示 UTF-8,杜绝 GBK 源码。
  2. 再调终端:CMD 下敲入 chcp 65001,确认活动代码页为 65001。
  3. 外源数据:读写外部 GBK 文件时,先读 Buffer,再用 TextDecoder('gbk') 解码。
  4. 规范工具:推荐使用 Windows Terminal,并配置 .editorconfig 统一团队标准。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章