Python中文注释乱码怎么解决？文件编码设置指南

在编写或运行 Python 脚本时，中文注释变成“锘匡豢”、“客户”等无规则乱码，甚至直接触发 SyntaxError: Non-UTF-8 code starting with... 报错，其核心原因通常只有一个：文件的磁盘物理存储编码与编辑器或 Python 解释器读取时采用的解码方式不一致。要从根本上解决这个问题，只需要统一源文件保存编码、规范文件头部编码声明，并在开发工具中将默认编码锁定为标准的 UTF-8 格式。

一、乱码产生的底层机理与典型表现

计算机本身只能存储由 0 和 1 构成的二进制字节。当我们在编辑器中输入中文字符时，编辑器会依据某种编码表（如 UTF-8 或 GBK）将字符转换为特定的字节序列保存在磁盘上。随后，当编辑器重新载入文件或 Python 解释器执行代码时，又必须依据某种规则将字节流还原为文字。

在中文 Windows 环境下，许多遗留软件和系统默认使用基于 GBK/CP936 的多字节编码，而现代软件工程与 Python 3 默认全面转向 UTF-8 编码。这种环境差异引发了两种典型的乱码与异常情境：

• 编辑器界面乱码：文件本身是用 GBK 编码保存的，但 VS Code 等现代编辑器默认以 UTF-8 方式打开解析，遇到不合法的 UTF-8 字节序便展示为占位问号或截断字符；反之，若用 GBK 解码 UTF-8 编码的文本，就会呈现为形如“开发”的混乱拉丁目。
• 解释器执行报错：Python 2 默认按 ASCII 编码解析源码，只要存在非 ASCII 字符（即使仅存在于注释中）就会报错；Python 3 默认按 UTF-8 解析，但如果文件是使用 Windows 记事本以 ANSI（GBK）保存的，解释器无法以 UTF-8 解码该字节，便会抛出 SyntaxError: Non-UTF-8 code starting with '\xd6' in file...。

图1：Python 源代码物理存储与解释器解码过程中的冲突成因

二、基础修复：在脚本头部显式声明编码规范

依据 Python 官方规范 PEP 263，当源文件中含有非 ASCII 字符（包括中文字符串和中文注释）时，建议在文件最上方显式声明字符编码格式。这是跨 Python 2 与 Python 3 维护脚本健壮性的经典方案。

1. 规范的书写格式

编码声明支持以下两种最为普遍的标准书写形式：

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

或者更为简洁的格式：

# coding=utf-8

2. 书写位置硬性要求

根据语法分析器的规则，该声明必须位于文件的第一行或第二行。如果你的脚本包含 Unix 环境下的 Shebang 解释器路径，编码声明必须放置在第二行，示例如下：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# 这是一个中文注释：说明后续函数功能
def calculate_metrics():
    pass

三、主流编辑器与 IDE 的文件编码统一配置

日常开发中最常见的中文乱码，往往源于编辑器的默认新建编码设置。下面介绍在 VS Code 与 PyCharm 中的标准化配置与已乱码文件的转换步骤。

1. Visual Studio Code 配置与转换

在 VS Code 中，当前打开文件的编码格式会在窗口右下角状态栏明确标出（通常显示为 UTF-8 或 GBK）：

1. 排查乱码：如果打开文件发现中文注释显示为乱码，点击右下角编码名称（或按快捷键 Ctrl+Shift+P / Cmd+Shift+P 搜索 Change File Encoding）。
2. 重新打开：点击 Reopen with Encoding（通过编码重新打开），选择 GBK 或 Simplified Chinese (GB2312)，此时中文通常会恢复正常显示。
3. 另存为标准编码：再次点击右下角编码，选择 Save with Encoding（通过编码保存），在列表中选择 UTF-8。此时文件在磁盘上的物理字节已被真正重写为 UTF-8。
4. 全局默认配置：进入 Settings（快捷键 Ctrl+,），搜索 files.encoding，确保值设为 utf8；并可勾选 files.autoGuessEncoding（自动猜测编码），帮助编辑器智能识别外部老旧脚本。

2. PyCharm 配置指南

JetBrains 家族的 PyCharm 提供了集中的字符集管理面板：

1. 打开菜单栏 File > Settings（macOS 为 PyCharm > Preferences）。
2. 在左侧导航进入 Editor > File Encodings。
3. 将 Global Encoding 与 Project Encoding 均设置为 UTF-8。
4. 将下方 Default encoding for properties files 设为 UTF-8。
5. 针对已有乱码文件，在编辑器右下角点击当前编码并选择 Convert 为 UTF-8。

图2：常见代码编辑器中的编码检测与无损重置四步法

四、运行与控制台输出中的中文乱码处理

有时脚本在编辑器中看中文完全正常，但执行 python script.py 输出包含中文字符的内容时，终端却输出了乱码。这主要是因为终端输出流与环境代码页不匹配。

1. Windows 命令提示符（CMD）代码页调整

在中文 Windows 系统中，CMD 终端默认活动代码页通常为 936（代表 GBK 编码）。当 Python 3 向标准输出打印 UTF-8 字符流时，便会产生错位。临时解决命令如下：

# 查看当前代码页
chcp

# 切换终端为 UTF-8 编码页（65001）
chcp 65001

2. 开启 Python UTF-8 模式（Python 3.7+）

Python 3.7 及以上版本引入了 PEP 540（UTF-8 Mode），允许忽略操作系统的区域设置强制使用 UTF-8。可以通过设置环境变量来生效：

• Windows 命令提示符：

  set PYTHONUTF8=1
  python script.py

• Windows PowerShell：

  $env:PYTHONUTF8="1"
  python script.py

• Linux / macOS：

  export PYTHONUTF8=1
  python3 script.py

3. 代码中读写外部文本文件时的防乱码写法

在 Python 代码中执行 open() 操作读写含有中文注释或数据的文件时，切忌依赖操作系统的默认编码。必须始终显式指定 encoding="utf-8" 参数：

# 推荐的标准文件读取写法
with open("data.txt", mode="r", encoding="utf-8") as f:
    content = f.read()

# 推荐的标准文件写入写法
with open("output.txt", mode="w", encoding="utf-8") as f:
    f.write("中文输出与统计记录")

图3：Python 中文相关异常与乱码现象分类排查决策树

五、规范化排查清单与团队工程化建议

为了让个人开发与团队协作彻底告别编码困扰，建议在项目生命周期中遵循以下四个维度的配置原则：

在多人协同项目中，还推荐在仓库根目录添加 .editorconfig 配置文件，以便各开发成员的 IDE 自动对齐编码规则：

# .editorconfig 示例
root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 4
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

图4：Python 编码配置与维护最佳实践全景图谱