Python代码中怎么正确声明和使用中文字符

听雨眠

发布时间：2026-10-26 | 5人浏览过

原创

很多开发者在刚开始用 Python 编写程序时，都经历过类似的场景：明明只是在脚本中加了一行包含“你好，世界”的注释或打印语句，一执行却抛出 SyntaxError: Non-UTF-8 code present 报错；或者从外部读取文本文件时，终端窗口里蹦出一串形如 \xe4\xbd\xa0\xe5\xa5\xbd 的十六进制乱码。要彻底消除这些困扰，核心并不在于死记各种参数，而在于搞清 Python 源码文件、内存字符串对象与外部输入输出三个层面的编码逻辑。

一、源码层：源文件编码与头部声明规范

在 Python 中使用中文字符，第一道关卡是让解释器正确读取你的 .py 脚本文件。Python 解释器在执行代码前，必须将磁盘上的源码字节序列解析为抽象语法树（AST）。如果源码文件中包含了中文字符（无论是中文变量名、字符串字面量还是注释），解释器就必须预先知晓该脚本使用的文本编码。

1. Python 3 的默认编码行为

根据 Python 官方规范 PEP 3120，Python 3 默认源文件编码统一为 UTF-8。这意味着在绝大多数现代编辑器（如 VS Code、PyCharm）中，只要新建的文件默认以 UTF-8 编码格式保存，即使不显式写出任何编码声明，也可以直接在源码中编写中文注释和字符串。

2. PEP 263 编码声明的正确写法

为了保证跨平台、跨环境运行的兼容性，或者团队项目中明确代码规范，推荐在脚本头部显式声明编码。根据 PEP 263 规范，编码声明必须放置在源码的第一行或第二行。最标准且通用的声明格式如下：

# -*- coding: utf-8 -*-
# 或者更简短的写法：
# coding=utf-8

如果脚本中还需要指定解释器路径（Shebang），编码声明则顺延放置在第二行：

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

def greet(name: str):
    """向指定用户输出中文问候语"""
    print(f"你好，{name}！")

greet("张伟")

注意位置限制： 如果在声明语句前出现了其他可执行语句、空行或普通注释（除第一行 shebang 外），解释器在扫描前两行未发现声明，就会直接启用默认行为。此时如果文件实际保存格式不是 UTF-8，便会直接抛出语法解析异常。

Python代码中怎么正确声明和使用中文字符 — 图 1：Python 源码文件编码识别、校验与语法树构建流程

二、内存层：理解 Python 3 中的中文字符模型

很多初学者会混淆“中文字符”和“字符的二进制字节”。在 Python 3 中，这两者有严格的类型边界：

str 类型（文本）：表示抽象的 Unicode 字符序列。每个字符就是一个独立的 Unicode 码点，例如汉字“中”对应码点 U+4E2D。在 Python 3 中，len("中文字符") 的结果是 4，代表有 4 个文本字符。
bytes 类型（字节）：表示原始的 8 位字节序列。当需要把中文存入硬盘、发送到网络套接字或传递给 C 库时，必须通过编码将 str 转化为 bytes。

字符与字节的相互转换

在代码中处理中文字符时，涉及边界交互最核心的两个方法是 encode() 和 decode()：

# 1. 文本字符串（str）
text = "你好"
print(type(text), len(text))  # 输出: <class 'str'> 2

# 2. 编码（Encode）：将 Unicode 字符串转化为指定编码的字节流
byte_data = text.encode("utf-8")
print(byte_data)             # 输出: b'\xe4\xbd\xa0\xe5\xa5\xbd'
print(len(byte_data))        # 输出: 6（UTF-8 中一个常用汉字占 3 字节）

# 3. 解码（Decode）：将接收到的字节流还原为 Unicode 字符串
recovered_text = byte_data.decode("utf-8")
print(recovered_text)        # 输出: 你好

三、场景层：中文字符输入输出的最佳实践

了解了内存模型后，在实际项目中处理中文字符时，最容易出现问题的地方往往是**文件读写**和**终端输出**。必须遵循明确的标准步骤来避免隐式编码冲突。

1. 外部文本文件读写：务必显式指定 `encoding='utf-8'`

很多开发者习惯直接调用 open("data.txt", "r")，这在 macOS 和 Linux 上通常工作正常，但在 Windows 系统上会隐蔽报错。因为如果不传 encoding 参数，Python 会调用系统默认的本地编码（Windows 下通常是 cp936/gbk）。当文件包含特殊汉字或 UTF-8 多字节字符时，就会触发 UnicodeDecodeError。

# 正确规范：无论读写，均显式指定 encoding="utf-8"
file_path = "chinese_demo.txt"

# 1. 写入中文
with open(file_path, mode="w", encoding="utf-8") as f:
    f.write("第一行：用户配置信息\n")
    f.write("第二行：系统状态正常\n")

# 2. 读取中文
with open(file_path, mode="r", encoding="utf-8") as f:
    content = f.read()
    print(content)

2. 控制台与终端输出中文

在部分受限环境（如 Windows 早期 CMD、Docker 轻量容器、或重定向日志到文件）中，标准输出流 sys.stdout 的编码可能不是 UTF-8，从而导致 print("中文") 时抛出 UnicodeEncodeError。可以通过以下两种稳妥方式解决：

代码内重配置流编码（推荐）：在 Python 3.7+ 中，直接调用 sys.stdout.reconfigure(encoding='utf-8')。
设置环境变量：在执行脚本前设置系统环境变量 PYTHONIOENCODING=utf-8。

import sys

# 确保在任意控制台环境下都能正确输出中文
if hasattr(sys.stdout, "reconfigure"):
    sys.stdout.reconfigure(encoding="utf-8")

print("当前标准输出编码已确认支持中文。")

四、排查篇：常见报错与乱码速查

在开发过程中，中文相关的报错主要集中在以下三种类型。掌握其发生机理，能够帮助你在几秒钟内准确定位并排除问题。

错误类型 / 现象	触发原因	针对性解决方案
`SyntaxError: Non-UTF-8 code present...`	源码保存编码与头部声明不符，或包含了非 UTF-8 编码的汉字字符。	在脚本首行添加 `# -- coding: utf-8 --`，并在代码编辑器右下角将文件重新以 UTF-8 格式保存。
`UnicodeDecodeError: 'utf-8' codec can't decode byte...`	尝试用 UTF-8 读取一个实际以 GBK/ANSI 保存的外部文本文件。	将读取语句改为 `encoding='gbk'`，或使用编码探测工具将原文件转码为标准 UTF-8。
`UnicodeEncodeError: 'gbk' codec can't encode character...`	运行环境（如 Windows 控制台）强制使用 GBK 编码输出某些不在 GBK 字符集内的特殊汉字或符号。	使用 `sys.stdout.reconfigure(encoding='utf-8')` 或将输出转为 UTF-8 格式持久化到日志文件。

五、总结与规范清单

要在日常开发中彻底避免中文字符问题，只需在团队或个人编码中坚持以下四条规范：

源码保存规范：所有编辑器（VS Code、PyCharm、Sublime 等）统一配置默认文件保存格式为 UTF-8 无 BOM。
头部显式声明：在涉及中文字符的源码文件第一行或第二行，统一添加 # -*- coding: utf-8 -*-。
IO 操作必须带编码参数：无论是 open()、pandas.read_csv() 还是第三方文件写入方法，坚决显式传入 encoding="utf-8"，不依赖操作系统的隐式默认值。
明确 str 与 bytes 边界：应用内部逻辑全部处理 str（Unicode 文本），仅在网络传输、本地序列化落盘等物理接触点进行 encode() 和 decode()。