VS Code中Python中文注释显示乱码怎么办

在 VS Code 中打开 Python 代码时，中文注释若显示为问号方块（）、“锟斤拷”或无法辨认的乱符，其本质原因是文件的底层存储编码与 VS Code 打开时采用的解码字符集不匹配。最直接的解决路径是：点击编辑器右下角状态栏中的编码格式标签（通常默认为 UTF-8），选择“通过编码重新打开 (Reopen with Encoding)”并指定为 GBK；待中文注释恢复正常后，再次点击该标签并选择“通过编码保存 (Save with Encoding)”为 UTF-8。完成这两步操作后，文件即被永久转换为跨平台通用的标准编码。

一、为什么中文注释会出现乱码：字符集与字节流不匹配

计算机在磁盘上保存文本文件时，本质上只记录一连串二进制字节。当编辑器打开文件时，必须按照某种字符映射表（编码表）将这些字节还原为字符。如果写入文件和读取文件时采用的编码表不一致，文本解释就会产生偏差，从而呈现乱码。

在 Windows 环境下，许多历史项目、自带记事本或早期编辑器默认采用简体中文代码页 GBK / CP936（每个汉字占用 2 个字节）。而现代跨平台开发工具（包括 VS Code 与 Python 3 解释器）默认均推荐并采用 UTF-8 编码（常见汉字占用 3 个字节）。当 VS Code 尝试用 UTF-8 规则去解析 GBK 生成的字节序列时，如果遇到不符合 UTF-8 规范的字节组合，就会替换为 ；反之，若用 GBK 打开 UTF-8 文件，则可能拼接出类似“锟斤拷”的错位汉字。

二、核心操作：通过状态栏重新读取并转换为标准 UTF-8

当发现文件注释乱码时，切勿在乱码状态下按 Ctrl+S 直接保存或编辑代码。如果直接保存，VS Code 会把用于替代未知字符的占位符（如 \ufffd）写回磁盘，导致原始汉字字节被永久冲刷损毁。

正确的恢复步骤分为两阶段：先以正确的编码（通常是 GBK）重新解析并读入内存，确认字符显示正常后，再以通用的 UTF-8 编码写回磁盘。

步骤 1：通过编码重新打开 (Reopen with Encoding)

1. 打开包含乱码注释的 .py 文件。
2. 查看 VS Code 界面最下方的状态栏，右下侧通常会显示当前的编码名称（如 UTF-8）。
3. 单击该编码名称（或者按下快捷键 Ctrl+Shift+P / Cmd+Shift+P，搜索并执行 Change File Encoding）。
4. 在弹出的顶部下拉菜单中，选择 “通过编码重新打开” (Reopen with Encoding)。
5. 在搜索框中键入 GBK 或 Simplified Chinese (GBK)，回车选中。此时编辑器会刷新文本，中文注释将恢复为正常汉字。

步骤 2：通过编码保存 (Save with Encoding)

1. 确认中文注释已经清晰可读后，再次点击右下角状态栏的编码名称（此时显示为 GBK）。
2. 在弹出菜单中，选择 “通过编码保存” (Save with Encoding)。
3. 在搜索框中键入 UTF-8 并回车确认。
4. 此时文件在磁盘上的物理字节已经被重写为标准的 UTF-8 格式，后续无论在 Linux、macOS 还是 Windows 上再次打开，均不会发生乱码。

三、精准分流：区分“编辑器显示乱码”与“终端运行输出乱码”

很多开发者在排查乱码时容易将两个不同的环节混为一谈：

• 场景 A：编辑器代码区乱码。代码文件刚刚打开，窗口中的注释或中文文字就是乱符。这属于纯粹的文件读取字符集问题，按照上节在状态栏中调整编码即可解决。
• 场景 B：编辑器内显示完全正常，但在集成终端中运行 python script.py 时输出乱码。这属于终端控制台输出流编码不一致。

在 Windows 环境中，PowerShell 或 CMD 终端默认的代码页往往是 936（GBK），而 Python 3 在运行输出 UTF-8 字符流时，两者产生冲突便会输出乱码。针对场景 B，解决办法并不需要修改源码文件的保存编码，而是配置运行环境：

1. 临时切换终端代码页：在 VS Code 集成终端中运行 chcp 65001 命令，将当前终端活动代码页切换为 UTF-8。
2. 设置 Python I/O 环境变量：在终端中执行 set PYTHONIOENCODING=utf-8（PowerShell 下为 $env:PYTHONIOENCODING="utf-8"），强制 Python 标准输出流使用 UTF-8 编码。

四、一劳永逸：预防乱码的长效配置与团队规范

单次手动重新打开并保存能修复已存在的乱码文件。但在日常开发或接收外部同事代码时，若频繁遇到编码不一致，可以通过以下全局或项目级配置进行自动化防范。

1. 开启 VS Code 自动推测编码 (autoGuessEncoding)

VS Code 具备内置的字符编码探测算法。开启该功能后，在打开未知编码文件时，编辑器会自动猜测其字符集并以匹配模式载入：

1. 按 Ctrl+,（macOS 为 Cmd+,）打开“设置”。
2. 在顶部搜索框中输入 autoGuessEncoding。
3. 勾选 Files: Auto Guess Encoding（对应设置项为 "files.autoGuessEncoding": true）。

2. 在工作区配置中锁定 UTF-8 编码

为了防止团队成员在不同操作系统上保存出不兼容编码的文件，推荐在项目根目录下的 .vscode/settings.json 中强制指定编码：

{
  "files.encoding": "utf8",
  "files.autoGuessEncoding": true
}

3. 理解 Python 源码头部声明的作用边界

在 Python 2 或历史遗留工程中，经常会在文件第一行或第二行看到如下声明：

# -*- coding: utf-8 -*-

需要明确的是：该声明的作用对象是 Python 解释器，而不是文本编辑器。它告知 Python 解释器在编译当前 .py 脚本时使用 UTF-8 解析源码；但如果文件在物理磁盘上是 GBK 编码，仅仅在头部写上 # -*- coding: utf-8 -*- 并不能阻止 VS Code 或解释器产生解析冲突。最稳妥的实践始终是保持“物理存储编码”与“解释器声明”全部统一为 UTF-8。

五、常见问题排查清单