MiNiKou的博客

1.1 检查 VS Code 文件编码#

VS Code 窗口右下角会显示当前文件编码，例如 UTF-8。单击它可以选择：

• Reopen with Encoding（通过编码重新打开）：不修改文件，只换一种编码解释现有字节。适合找回已经存在的中文内容。
• Save with Encoding（通过编码保存）：按照新编码重新写入文件。确认内容显示正常后，再用它转换编码。

不要在内容仍是乱码时直接“以 UTF-8 保存”，否则可能把错误解码后的文字再次写入文件，使恢复更加困难。

新项目建议统一使用 UTF-8。可以在 VS Code 的 settings.json 中设置：

1
{
2
  "files.encoding": "utf8",
3
  "files.autoGuessEncoding": true
4
}

files.autoGuessEncoding 只能进行推测，并不能保证准确。项目已经明确编码时，应以项目约定为准。

1.2 检查 Windows 终端代码页#

在 VS Code 的 PowerShell 或 CMD 终端中运行：

1
chcp

常见结果如下：

如果程序输出 UTF-8，而当前代码页不是 UTF-8，可以在当前终端会话中执行：

1
chcp 65001

这只改变当前终端会话，不会修改源文件，也不能修复已经损坏的文本。如果项目中的旧程序固定输出 GBK，则把终端统一改成 UTF-8 反而可能产生乱码，需要让程序和终端使用一致的编码。

1.3 Python 输出或文件读取乱码#

先检查 Python 正在使用的标准输入输出编码：

1
import sys
2

3
print(sys.stdin.encoding)
4
print(sys.stdout.encoding)
5
print(sys.stderr.encoding)

可以临时使用 UTF-8 模式运行程序：

1
python -X utf8 main.py

读写文本文件时应明确指定编码，不要依赖不同操作系统可能不同的默认值：

1
from pathlib import Path
2

3
path = Path("message.txt")
4
path.write_text("你好，世界！", encoding="utf-8")
5
text = path.read_text(encoding="utf-8")
6
print(text)

如果读取旧的 GBK 文件，应使用实际编码：

1
with open("legacy.txt", "r", encoding="gbk") as file:
2
    text = file.read()

不要为了“消除报错”就随意添加 errors="ignore"。它会静默丢弃无法解码的数据。排查阶段使用默认的 errors="strict" 更容易发现编码不匹配。

1.4 C 和 C++ 中文输出乱码#

C/C++ 需要同时考虑源文件编码、编译器执行字符集和终端编码。MSVC 可以使用 /utf-8，让源字符集和执行字符集采用 UTF-8：

1
cl /utf-8 main.cpp

GCC 和 Clang 通常把 UTF-8 作为源文件编码；需要明确指定时可以使用：

1
g++ -finput-charset=UTF-8 -fexec-charset=UTF-8 main.cpp -o main.exe

同时确认终端代码页为 65001。在 Windows 上，涉及系统 API 的正式程序还应优先使用 Unicode 版本的 API 和宽字符接口，而不是依赖当前系统代码页。

1.5 字符显示成方框#

如果英文正常、中文或 emoji 显示成空白方框，编码可能没有问题，而是字体缺少对应字形。可以在 VS Code 中选择覆盖范围更完整的等宽字体：

1
{
2
  "terminal.integrated.fontFamily": "Cascadia Mono, Microsoft YaHei UI"
3
}

字体名称需要与本机已安装字体一致。emoji 的显示还会受到终端渲染能力和操作系统版本影响。

1.6 “输出”面板正常，但终端乱码，或情况相反#

VS Code 的“终端”和“输出”是两个不同区域。调试器、构建任务以及 Code Runner 等扩展可能把内容写到“输出”面板，也可能启动独立进程，它们不一定继承集成终端中的 chcp 设置。

排查时先确认内容实际出现在哪里：

• 在“终端”中直接运行程序，观察是否仍然乱码。
• 查看 .vscode/tasks.json 中实际执行的命令和所用 shell。
• 查看相关扩展是否提供“在终端中运行”的选项。
• 如果只有某个扩展乱码，优先检查该扩展的编码或运行方式，而不是修改整个项目的文件编码。

例如，使用 Code Runner 时可以让代码在集成终端中执行：

1
{
2
  "code-runner.runInTerminal": true
3
}

修改设置后应新建一个终端，因为已经运行的终端进程不会自动获得所有新配置。

4.1 ASCII#

ASCII 使用 7 位表示 128 个字符，包括英文字母、数字、标点和控制字符。例如：

1
A -> 65 -> 0x41
2
0 -> 48 -> 0x30

ASCII 不能表示中文。UTF-8 的前 128 个字符与 ASCII 完全兼容，因此纯 ASCII 文本也是合法的 UTF-8 文本。

4.2 ISO-8859-1 与 Windows-1252#

ISO-8859-1 又称 Latin-1，使用一个字节表示西欧字符。Windows-1252 与它相近，但在 0x80 到 0x9F 范围定义了不同字符。

它们都不能完整表示中文。由于 Latin-1 能把任意字节映射到字符，有时会被程序用于“无报错地读取字节”，但这并不代表文本被正确解码。

4.3 Unicode#

Unicode 是统一字符标准，为世界各地的字符分配码点。它解决的是“每个字符对应哪个编号”，不是“这些编号如何存成字节”。

UTF-8、UTF-16 和 UTF-32 才是 Unicode 的具体编码方式。同一个字符的码点相同，但在不同 UTF 编码中的字节表示不同。

4.4 UTF-8#

UTF-8 是目前最常用的 Unicode 编码，具有以下特点：

• 使用 1 到 4 个字节表示一个码点。
• ASCII 字符只占 1 个字节，与 ASCII 兼容。
• 常用汉字通常占 3 个字节。
• 不依赖字节序，适合网页、配置文件、源代码和网络传输。

1
for char in ["A", "中", "😀"]:
2
    data = char.encode("utf-8")
3
    print(char, data.hex(" "), len(data))
4

5
# A 41 1
6
# 中 e4 b8 ad 3
7
# 😀 f0 9f 98 80 4

没有历史兼容要求时，文本文件通常优先选择 UTF-8（无 BOM）。

4.5 UTF-16 与 UTF-32#

UTF-16 通常使用 2 个或 4 个字节表示一个码点，UTF-32 固定使用 4 个字节。多字节数值需要区分字节序：

• UTF-16 LE：低位字节在前。
• UTF-16 BE：高位字节在前。
• UTF-32 同样有 LE 和 BE。

UTF-16 常见于 Windows API、Java 和一些旧式文本格式；UTF-32 便于按固定宽度处理码点，但空间开销较大。注意：即使使用 UTF-16，一个用户眼中的字符也不一定恰好等于一个 16 位代码单元。

4.6 GB2312、GBK 与 GB18030#

这三种编码主要用于中文环境，关系可以粗略理解为逐步扩展：

新项目通常仍应优先选择 UTF-8；只有对接旧文件、旧数据库或特定系统时，才使用它们实际要求的中文编码。

4.7 一张对比表#

6.1 CSV 在 Excel 中打开乱码#

某些版本或配置下的 Excel 不能自动识别无 BOM 的 UTF-8 CSV。可以按使用对象选择方案：

• 仅供程序读取：优先使用标准 UTF-8。
• 主要供 Windows Excel 双击打开：可尝试 UTF-8 with BOM，即 Python 中的 utf-8-sig。
• 对方系统明确要求 GBK：按接口约定导出 GBK，并确认字符不会丢失。

1
import csv
2

3
with open("users.csv", "w", encoding="utf-8-sig", newline="") as file:
4
    writer = csv.writer(file)
5
    writer.writerow(["姓名", "城市"])
6
    writer.writerow(["小明", "上海"])

6.2 网页中文乱码#

HTML 页面应尽早声明 UTF-8：

1
<meta charset="UTF-8">

HTTP 响应也应提供正确的 Content-Type：

1
Content-Type: text/html; charset=utf-8

HTTP 头的优先级通常高于 HTML 内的声明。页面文件、服务端响应头和数据库连接应采用一致或可正确转换的编码。

6.3 数据库出现乱码或 emoji 写入失败#

数据库需要同时检查：

1. 数据库、表和字段使用的字符集。
2. 客户端与数据库连接使用的字符集。
3. 驱动程序发送和接收字符串的方式。

MySQL 中应优先使用真正覆盖完整 Unicode 的 utf8mb4。历史上的 utf8 别名可能只支持最多 3 字节的 UTF-8，无法存储部分 emoji 和扩展字符。

6.4 Git 显示中文文件名异常#

文件内容编码、文件名的显示方式和换行符是三个不同问题。Git 中可按需检查：

1
git config --get core.quotepath
2
git config --get core.autocrlf

core.quotepath=false 可以让 Git 更直接地显示非 ASCII 文件名；core.autocrlf 管理的是换行符转换，并不负责字符编码。