Python脚本中文注释报错或乱码怎么解决

一、现象分流：是解释器语法报错，还是环境显示乱码？

排查问题的第一步是区分具体表现。许多开发者容易把“终端报 SyntaxError 终止执行”与“代码能跑但字形显示为问号或乱码”混为一谈，而两者的成因与修复切入点完全不同。

1. 语法解析期报错（SyntaxError）

当执行 python script.py 命令后，程序根本没有启动，控制台直接抛出语法错误并中断。最典型的两种错误信息如下：

# 典型报错示例 1（多见于 Python 2 或未声明编码环境）
SyntaxError: Non-ASCII character 'ä' in file test.py on line 3, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details

# 典型报错示例 2（多见于 Python 3 读取了 GBK/ANSI 保存的脚本）
SyntaxError: (unicode error) 'utf-8' codec can't decode byte 0xd6 in position 12: invalid start byte

这类问题的核心在于词法分析受阻：Python 解释器在编译代码生成字节码阶段，读取了超出其预期编码范围的字节序列，因此拒绝继续向下执行。

2. 视图与终端乱码（Garbled Text）

另一种情况是脚本本身可以正常运行，但在编辑器中打开源文件时，中文注释变成了 # 锟斤拷锟斤拷、# 测试；或者在 Windows 命令行执行 print() 输出中文内容时，打印结果变成了生僻符号或问号。

这属于视图渲染与输出流重定向问题。源文件在磁盘上记录的字节本身可能没有损坏，但由于打开文件的软件或接收打印流的控制台使用了错误的字符集映射表，导致字符还原失败。

二、底层机制：Python 2 与 Python 3 的编码处理差异

理解 Python 解析源码的机制，有助于我们在遇到问题时迅速作出准确判断，而不是盲目尝试各种命令。

1. Python 2 的默认 ASCII 机制与 PEP 263

在 Python 2.x 体系中，解释器默认的源码解析编码是标准的 7 位 ASCII 码（编码范围为 0x00 至 0x7F）。汉字在 UTF-8 编码下通常占用 3 个字节，在 GBK 编码下占用 2 个字节，其字节值均大于 127（0x7F）。当 Python 2 词法分析器在扫描文件时，一旦遇到大于 127 的字节，且文件开头没有指定编码规范，就会无条件触发 PEP 263 规范拦截并抛出错误。

2. Python 3 的默认 UTF-8 机制与物理格式冲突

Python 3.x 将源码默认解析编码改为了全平台通用的 UTF-8。这意味着如果脚本是以 UTF-8 格式存储的，即使不写首行编码声明，解释器也能直接识别中文注释与中文字符串。

然而，在 Windows 操作系统中，若使用系统自带的“记事本”或某些老旧开发工具新建 .py 文件，系统默认会以 ANSI 编码（简体中文 Windows 下即 GBK/CP936 编码）进行物理磁盘写入。当 Python 3 解释器默认启动 UTF-8 解码器去解析一段 GBK 编码的中文注释字节序列时，遇到非法的 UTF-8 前导码，便会直接爆出 'utf-8' codec can't decode byte 错误。

三、标准解决步骤与操作指南

针对上述原理，解决中文注释报错与乱码应严格按照以下四个步骤逐步落实：

第一步：在源码文件首行添加 PEP 263 规范声明

无论当前使用的是 Python 2 还是 Python 3，在包含中文注释的脚本文件头部显式声明编码是业界通用的最佳防御性编程规范。PEP 263 明确规定，编码声明必须放置在脚本的第 1 行；如果第 1 行存在 Unix 系统的 Shebang 解释器声明（如 #!/usr/bin/env python），则必须紧随其后放置在第 2 行，放在第 3 行及之后将完全失效。

标准声明推荐采用 Emacs/Vim 兼容格式，示例如下：

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

# 这是一个中文测试注释：此时解释器已获知本文件采用 UTF-8 字符集
def calculate_sum(a, b):
    # 计算两数之和并返回
    return a + b

if __name__ == "__main__":
    print(calculate_sum(10, 20))

第二步：统一文件物理存储编码为 UTF-8（无 BOM）

仅仅在代码首行写上 # -*- coding: utf-8 -*- 并不能改变文件在磁盘上的实际二进制字节。如果文件物理上是 GBK 格式，首行写 UTF-8 反而会导致解释器按 UTF-8 去解码 GBK 字节，引发更严重的崩溃。必须确保编辑器保存的物理编码与声明一致：

• VS Code 操作：
  1. 观察编辑器右下角状态栏的编码标识（如显示 GBK 或 UTF-8）。
  2. 如果中文显示正常但运行报错，点击状态栏编码，选择 “Save with Encoding”（通过编码保存），输入并选择 UTF-8。
  3. 如果中文在编辑器里本身就是乱码，先点击状态栏选择 “Reopen with Encoding”（通过编码重新打开），尝试选择 GBK 或 GB18030 恢复中文显示，确认文字恢复正常后再选择“Save with Encoding”转存为 UTF-8。
• PyCharm 操作：
  1. 进入菜单 File -> Settings（macOS 为 Preferences）-> Editor -> File Encodings。
  2. 将 Global Encoding、Project Encoding 以及 Default encoding for properties files 全部统一修改为 UTF-8。
  3. 在下方勾选 Transparent native-to-ascii conversion（可选），并将“Create UTF-8 files”设置为 with NO BOM。
• Notepad++ 操作：
  1. 点击顶部菜单栏的 编码 (Encoding)。
  2. 选择 “转为 UTF-8 编码 (Convert to UTF-8)”（切勿选择“转为 UTF-8-BOM”），随后按 Ctrl + S 保存文件。

第三步：校准运行终端与控制台环境

在 Windows 环境下，命令提示符（CMD）和老版本 PowerShell 的默认代码页通常是 936（即 GBK 编码）。即使 Python 脚本本身已完全符合 UTF-8 规范，终端打印中文时仍可能因为代码页转换失败而乱码。解决方法如下：

方法 A：临时切换当前命令提示符代码页

# 在执行 python 脚本前，先切换控制台为 UTF-8 代码页（示例命令）
chcp 65001

# 随后执行脚本
python test.py

方法 B：设置环境变量强制 Python 标准流编码

通过设置 PYTHONIOENCODING 环境变量，强制 Python 的 sys.stdout 和 sys.stderr 以 UTF-8 格式输出数据：

# Windows CMD 临时设置
set PYTHONIOENCODING=utf-8

# Windows PowerShell 临时设置
$env:PYTHONIOENCODING="utf-8"

# Linux / macOS 终端设置
export PYTHONIOENCODING=utf-8

四、关键细节与避坑要点

1. 警惕 UTF-8 BOM 签名头

Windows 自带的记事本在保存 UTF-8 文件时，历史上曾默认在文件最开头写入 3 个隐藏字节：0xEF, 0xBB, 0xBF（即 Byte Order Mark，BOM 签名）。虽然 Python 3 后期版本已能识别并跳过部分 UTF-8-BOM，但若结合特定的打包工具、旧版本 Python 解释器或跨平台执行时，开头的 BOM 标记可能导致解释器无法正确匹配第 1 行的 Shebang 或 PEP 263 声明，从而诱发 SyntaxError: invalid character in identifier 偶发异常。因此，所有脚本务必保存为UTF-8 无 BOM (UTF-8 without BOM)。

2. 避免“虚假声明”引发二次错误

绝不能在物理为 GBK 编码的文件首行声明 # -*- coding: utf-8 -*-，同样也不要在物理为 UTF-8 的文件首行声明 # -*- coding: gbk -*-。声明的本质是告诉解释器“请按此规则读取磁盘字节”，如果实际物理存储编码与声明自相矛盾，解释器必然在遇到第一个非匹配字符时抛出解码崩溃。

五、总结：排查决策树与环境自检

遇到中文注释报错或乱码时，按照以下决策树即可在 1 分钟内完成故障定位与消除：

环境快速自检命令

在排查疑难环境时，可在目标系统上运行以下单行命令，打印当前 Python 环境的内部编码状态：

# 执行自检命令
python -c "import sys; print('默认编码:', sys.getdefaultencoding()); print('文件系统编码:', sys.getfilesystemencoding()); print('标准输出编码:', sys.stdout.encoding)"

正常输出示例（UTF-8 理想状态）：

默认编码: utf-8
文件系统编码: utf-8
标准输出编码: utf-8

如果输出结果中的 标准输出编码 为 cp936 或 None，说明当前终端或重定向环境未开启 UTF-8 流处理，此时通过配置环境变量 PYTHONIOENCODING=utf-8 或执行 chcp 65001 即可确保中文注释、中文日志与输出的完全一致与通畅。