Python 2的str是字节序列（同Py3的bytes），unicode才是文本（同Py3的str）；源码编码声明仅影响读取源文件，不改变运行时编码行为；文件读写必须显式指定encoding="utf-8"；跨版本转换需先判断类型再decode/encode。
Python 2 和 Python 3 的 str 类型本质不同
Python 2 的 str 是字节序列，等价于 Python 3 的 bytes；而 Python 2 的 unicode 才是真正的文本，对应 Python 3 的 str。这意味着同一段代码在两个版本中行为可能完全相反："中文".decode("utf-8") 在 Python 2 中合法，在 Python 3 中直接抛出 AttributeError；反过来，b"\xe4\xb8\xad".encode("utf-8") 在 Python 3 中会报错 AttributeError: 'bytes' object has no attribute 'encode'。
这种类型语义翻转是绝大多数迁移报错的根源，不是“写法不对”，而是“对象身份变了”。
文件开头声明 # -*- coding: utf-8 -*- 只解决一部分问题
这个声明只影响 Python 解释器如何读取源码文件本身（比如中文字符串字面量、中文注释），它不改变运行时字符串的类型或编码行为。
- 对 Python 2：必须加，否则含中文的
str字面量会按 ASCII 解析，直接 SyntaxError - 对 Python 3：可加可不加（默认已是 UTF-8），但加了更明确，尤其当团队混用编辑器时能避免保存编码不一致
- 它完全不管从文件、网络、数据库读进来的数据——那些数据的编码由你显式指定或依赖系统默认值
读写文件必须显式传 encoding="utf-8"
Python 3 默认用系统编码（Windows 常为 gbk）打开文本文件，一旦文件实际是 UTF-8 编码，就会触发 UnicodeDecodeError；反之，若用默认编码写入中文到文件，再被其他工具（如 VS Code、浏览器）以 UTF-8 打开，就显示乱码。
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
正确做法始终是：
with open("data.txt", "r", encoding="utf-8") as f:
content = f.read()
<p>with open("out.txt", "w", encoding="utf-8") as f:
f.write("你好")
注意：encoding 参数仅对文本模式（"r"/"w"）有效；二进制模式（"rb"/"wb"）下禁止使用该参数，且返回/接收的永远是 bytes。
跨版本安全的 str/bytes 转换要先判断类型
当你不确定输入是 str 还是 bytes（例如处理 HTTP 响应体、lmdb 键值、socket 接收数据），不能硬写 .decode() 或 .encode()。必须做类型检查：
def to_str(data):
if isinstance(data, bytes):
return data.decode("utf-8")
elif isinstance(data, str):
return data
else:
raise TypeError(f"expected bytes or str, got {type(data).__name__}")
<p>def to_bytes(data):
if isinstance(data, str):
return data.encode("utf-8")
elif isinstance(data, bytes):
return data
else:
raise TypeError(f"expected bytes or str, got {type(data).<strong>name</strong>}")
这种判断不是“过度防御”，而是 Python 2/3 兼容层（如 six 或 future）内部真实采用的逻辑。忽略它，AttributeError 和 UnicodeDecodeError 就会在最意想不到的地方冒出来。
真正容易被忽略的点是：终端输出和日志也受环境编码限制，即使你的字符串全是 str，print() 仍可能因 sys.stdout.encoding 不是 UTF-8 而失败——这时需要重定向或设置环境变量，而不是改代码逻辑。
