运行python代码为什么会出现“SyntaxError: Non-UTF-8 code starting with”

在 运行Python 代码中，我们有时会遇到

SyntaxError: Non-UTF-8 code starting with '\xbb' in file C:/first.py on line 2, but no encoding declared; see https://python.org/dev/peps/pep-0263/ for details

但是填上注释

# -*- coding: gbk -*-

就能解决问题，所以我在想这是为什么呢？故而我针对这个问题查找资料做出解释如下：

一、何为SyntaxError: Non-UTF-8 code starting with问题

出现 SyntaxError: Non-UTF-8 code starting with '\xxx' 错误的核心原因是：Python 解释器默认使用 UTF-8 编码解析源代码，但你的代码文件中包含了非 UTF-8 编码的字符（如中文、特殊符号等），且未声明正确的编码格式。

具体原因分析：

1. Python 的默认编码规则：

   • Python 3.x 解释器默认将源代码视为 UTF-8 编码。
   • 如果代码文件实际保存的编码不是 UTF-8（例如 GBK、GB2312、Latin-1 等），且包含了非 ASCII 字符（如中文 “你好”、日文 “こんにちは” 等），解释器会因无法识别这些字符而报错。

2. 常见触发场景：

   • 在 Windows 系统中，用记事本保存代码时默认使用 GBK 编码，而代码中包含中文，且未添加 # -*- coding: gbk -*- 声明。

   • 从其他来源复制的代码（如旧系统、不同编码的文件）包含非 UTF-8 字符，直接运行时未适配编码。

   • 编辑器保存文件时选择了非 UTF-8 编码（如 ISO-8859-1），但代码中存在中文等特殊字符。

二、何为# -- coding: gbk --

# -*- coding: gbk -*- 是一个编码声明注释，它的主要作用是指定当前 Python 源文件的字符编码格式。

1. 解决字符编码问题：
   当 Python 解释器读取源代码文件时，需要知道该文件使用的字符编码（如 UTF-8、GBK 等）才能正确解析文件中的字符（尤其是中文、日文等非 ASCII 字符）。
   如果代码中包含中文等特殊字符，且未指定正确的编码格式，Python 解释器可能会因无法识别而抛出SyntaxError（语法错误）。
2. 适用场景：
   • 当代码文件使用 GBK 编码保存时（常见于 Windows 系统的默认文本编码），需要添加该声明，告诉 Python 解释器用 GBK 编码来解析文件。
   • 如果文件使用 UTF-8 编码（现在更推荐的编码格式），则应使用 # -*- coding: utf-8 -*-。
3. 语法规则：
   • 该声明必须放在文件的第一行（如果文件有#!/usr/bin/env python之类的解释器路径声明，则编码声明放在第二行）。
   • 格式严格，coding: 后面的编码名称（如 gbk、utf-8）必须与文件实际保存的编码一致，否则会导致解码错误。

为什么需要它？

早期的 Python 2.x 版本默认使用 ASCII 编码解析源代码，当代码中出现非 ASCII 字符时必须显式声明编码，否则会报错。
虽然 Python 3.x 默认使用 UTF-8 编码，但如果文件实际保存为其他编码（如 GBK），仍需要通过该声明指定正确编码，否则会出现乱码或解析错误。

简单来说，这个声明是为了确保 Python 解释器能正确 “读懂” 文件中的字符，避免因编码不匹配导致的错误。

三、还有没有其他编码问题会出现这种情况。解决办法是什么

1. UTF-16 编码

• 问题：UTF-16 是双字节编码，与 Python 默认的 UTF-8 编码差异较大，直接运行会报错。
• 解决办法：
  • 在文件开头添加编码声明：# -*- coding: utf-16 -*-
  • 建议：尽量避免用 UTF-16 保存 Python 代码，因为很多编辑器和工具对 UTF-8 支持更好。

2. Latin-1（ISO-8859-1）

• 问题：Latin-1 主要支持西欧语言，无法正确解析中文等东亚字符，若代码含中文会报错。
• 解决办法：
  • 若文件确实用 Latin-1 编码保存，且必须保留该编码，需确保代码中无中文等非 Latin-1 字符。
  • 推荐：将文件重新保存为 UTF-8 编码，并添加声明 # -*- coding: utf-8 -*-。

3. GB2312/GB18030

• 问题：这两种是 GBK 的扩展编码（兼容 GBK），若代码用它们保存且含特殊字符，可能因编码不匹配报错。
• 解决办法：
  • 添加对应编码声明：# -*- coding: gb2312 -*- 或 # -*- coding: gb18030 -*-
  • 建议：统一使用 UTF-8 编码（现代开发的主流选择），减少跨平台兼容问题。

4. 无 BOM 的 UTF-8（Windows 环境下）

• 问题：Windows 记事本默认会给 UTF-8 文件添加 BOM（字节顺序标记），但部分编辑器保存的 UTF-8 文件可能无 BOM，在旧版 Python 中可能解析异常。
• 解决办法：
  • 添加 UTF-8 声明：# -*- coding: utf-8 -*-（即使文件无 BOM，该声明也能让解释器正确识别）。

通用解决原则：

1. 统一编码格式：优先使用 UTF-8 编码保存 Python 代码（几乎所有现代编辑器和编程语言都推荐），并在文件开头添加：

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

   （Python 3.4 + 已默认支持 UTF-8，但若代码需兼容旧版本，仍建议添加）

2. 检查文件实际编码：

   • 若不清楚文件当前编码，可通过编辑器查看（如 VS Code 右下角会显示编码格式）。
   • 若编码不匹配，用编辑器将文件重新保存为目标编码（如 UTF-8）。

3. 避免混合编码：同一项目中所有代码文件尽量使用同一种编码（推荐 UTF-8），减少协作和运行时的编码冲突。