Mac终端运行Python脚本出现中文编码错误的处理方法

在 macOS 终端中运行 Python 脚本时，如果涉及中文输出或文件读写，最常遇到的两类编码问题是直接抛出 UnicodeEncodeError / UnicodeDecodeError 异常，或者终端正常退出却显示为“\xe4\xbd\xa0\xe5\xa5\xbd”或乱码问号。解决这一问题的核心路径非常明确：排查并统一终端环境语言配置（Locale）、Python 脚本文件自身的存储编码，以及脚本内部文件 I/O 显式声明的编码格式。绝大多数情况下，只要确保这三个环节均处于明确的 UTF-8 规范下，中文编码问题即可彻底解决。

一、编码错误的核心表现与常见原因

Python 处理字符串时区分内部抽象文本类型（str）与底层字节序列（bytes）。当 Python 需要将中文文本打印至终端窗口、重定向至外部文件，或从磁盘读取数据流时，必须依赖特定的字符编码表进行编解码转换。在 macOS 环境下，报错通常由以下三类常见原因引发：

• 标准输出流环境编码回退（ASCII 兜底）：当终端环境未正确导出 LANG 或 LC_CTYPE 时，Python 解释器会将标准流 sys.stdout.encoding 误判为受限的 US-ASCII。此时一旦使用 print() 输出中文字符，便会触发 UnicodeEncodeError: 'ascii' codec can't encode characters...。
• 文件读取未指定显式编码：使用内置函数 open('data.txt', 'r') 时若省略 encoding 参数，Python 将采用系统的默认区域设置。若外部文本是 GBK、GB2312 格式或本地默认环境偏离 UTF-8，便会触发 UnicodeDecodeError。
• Python 源码文件本身编码混淆：在 Python 3 中，源码默认以 UTF-8 解析；但若代码文件被部分编辑器意外保存为 GBK/ANSI 格式，且内部含有中文字面量或注释，编译执行瞬间即告失败。

二、分步排查与具体解决步骤

解决 Mac 终端编码问题需要从系统终端环境与代码逻辑两个层面逐一落实。按照由外向内的顺序执行以下步骤，能够快速定位并消除故障源。

第一步：检查当前终端的 Locale 配置

在 Mac 终端（默认通常为 zsh）中输入以下命令，查看当前的语言与区域设置：

locale

如果输出结果中的 LANG、LC_CTYPE 或 LC_ALL 处于未设置状态，或者显示为 "C" 或 "POSIX"，Python 启动时将无法识别系统的现代字符集，从而直接回退至最基础的 US-ASCII。

# 异常环境示例：
LANG=""
LC_COLLATE="C"
LC_CTYPE="UTF-8"
LC_ALL=

# 规范健康环境示例：
LANG="zh_CN.UTF-8" 或 LANG="en_US.UTF-8"
LC_ALL="en_US.UTF-8"

第二步：持久化写入环境变量到 Shell 配置文件

macOS 从 Catalina (10.15) 开始将默认 Shell 更替为 zsh。为了使所有新建终端窗口均具备正确的字符环境，需将变量写入用户的 shell 初始化脚本中。

使用文本编辑器编辑用户主目录下的 ~/.zshrc（如果使用原生 bash 则编辑 ~/.bash_profile）：

# 打开终端配置文件进行编辑
nano ~/.zshrc

在文件末尾追加以下环境变量导出指令：

export LANG="en_US.UTF-8"
export LC_ALL="en_US.UTF-8"
export PYTHONIOENCODING="utf-8"

保存文件后，在当前终端执行以下命令使其立即生效，或者关闭终端窗口重新打开：

source ~/.zshrc

第三步：在 Python 源码中规范文件读写与标准流

很多初学者在写文件读写操作时习惯简写，如下面的传统写法在跨系统移植时极易引发报错：

# 存在隐患的读写方式：依赖系统运行期推导
with open("data.txt", "r") as f:
    content = f.read()

规范的代码必须显式为 open 注入 encoding="utf-8" 参数：

# 健壮的标准做法：
with open("data.txt", "r", encoding="utf-8") as f:
    content = f.read()

with open("output.txt", "w", encoding="utf-8") as f:
    f.write("输出中文内容")

如果读取的文件可能来自 Windows 遗留系统（如带有 BOM 头的 UTF-8 文本），则推荐使用 encoding="utf-8-sig"，以自动滤除文件起始位置不可见的 \ufeff 字节标记，避免 JSON 解析或字符串匹配失效。

三、环境参数与重定向场景的差异对照

在 Mac 终端中直接运行命令，与将其放入 Crontab、Launchd 后台守护任务，或通过管道进行数据分流时，Python 面临的输出通道特性截然不同。了解两者的差异有助于读者理解为什么“有时候在交互终端能跑，自动化脚本就报错”。

四、解决效果的快速验证

完成上述配置后，需要验证改动是否已经彻底在 Python 运行环境中生效。可以在终端中直接调用 Python 单行代码输出当前的系统编解码指标：

python3 -c "import sys; print('默认编码:', sys.getdefaultencoding()); print('标准输出编码:', sys.stdout.encoding)"

在配置健全的 Mac 环境下，控制台将输出如下内容：

默认编码: utf-8
标准输出编码: utf-8

随后编写一个微型测试脚本 verify_chinese.py 进行端到端验证：

# -*- coding: utf-8 -*-
import sys

def run_test():
    chinese_text = "你好，世界！这是一段用于测试 Mac 终端编码的中文内容。"
    print(f"当前标准输出编码为: {sys.stdout.encoding}")
    print(f"测试打印中文字符串: {chinese_text}")

    # 测试文件写入与读取
    test_filename = "test_io.txt"
    with open(test_filename, "w", encoding="utf-8") as f:
        f.write(chinese_text)
    
    with open(test_filename, "r", encoding="utf-8") as f:
        read_back = f.read()
    
    assert read_back == chinese_text, "文件读写内容校验失败！"
    print("文件 UTF-8 读写闭环验证成功。")

if __name__ == "__main__":
    run_test()

在 Mac 终端中运行：

python3 verify_chinese.py

如果终端能够准确打印中文字样且没有抛出任何编码异常，即代表整个系统配置与代码读写规范已经能够完全消除中文编码故障。

五、常见衍生问题与排查清单

只要读者按照由外向内的顺序，确保终端仿真器配置、Shell 导出变量、脚本启动解释器以及文件 I/O 显式编码四个节点全部统一对齐，在 Mac 终端中运行 Python 脚本时的中文编码报错与乱码问题将完全不复存在。