Python 定时任务报 UnicodeEncodeError：定位标准输出编码并修复

交互终端能打印中文，定时任务一重定向日志却报 UnicodeEncodeError: 'ascii' codec can't encode characters。先检查失败进程实际使用的标准输出编码，再为入口明确设置 UTF-8，可以保留中文日志并验证写出的字节。

本文面向初中级读者，专门处理 Linux 上的标准流编码。解释器和工作目录也可能不同，先按定时任务路径排障核对入口。

1. 准备：区分三种编码

使用 Linux、Bash 和 Python 3.11 或更新版本，无需安装第三方包。本文示例在 Linux、Python 3.11.4 上验证。重复练习时换一个新目录名：

python3 --version
mkdir unicode-stdio-demo
cd unicode-stdio-demo

不要仅凭 LANG 推断结果：Python 的 UTF-8 模式、标准流覆盖设置也会影响行为。下面分别检查终端输出、普通文本文件和输入数据；改变其中一项不会自动修复另外两项。

根据 Python 3.15 官方变更说明，3.15 已默认启用 UTF-8 模式。旧解释器和显式覆盖仍可能使用其他编码，因此以下复现主动禁用自动模式，不代表每个定时任务都会失败。

2. 定位：打印实际标准流设置

将下面代码保存为 encoding_probe.py：

import json
import locale
import os
import sys

print(json.dumps({
    "python": sys.executable,
    "utf8_mode": sys.flags.utf8_mode,
    "locale_encoding": locale.getencoding(),
    "stdout_encoding": sys.stdout.encoding,
    "stdout_errors": sys.stdout.errors,
    "stderr_encoding": sys.stderr.encoding,
    "LC_ALL": os.environ.get("LC_ALL"),
    "LANG": os.environ.get("LANG"),
    "PYTHONIOENCODING": os.environ.get("PYTHONIOENCODING"),
}, ensure_ascii=True))

分别在终端和重定向下运行；生产排障时，也让失败任务的现有入口执行同一个探针：

python3 encoding_probe.py
python3 encoding_probe.py > encoding.json
cat encoding.json

JSON 使用 ensure_ascii=True，中文路径会转义，避免诊断消息本身因 ASCII 输出失败。重点比较 python、utf8_mode 和 stdout_encoding；locale_encoding 来自系统 locale，启用 UTF-8 模式后它也可能仍显示 ASCII。标准流的编码属性见 Python sys 文档。

保存最小复现为 hello.py。源码使用 Unicode 转义，避免把文件保存编码引入实验：

print("\u5b8c\u6210: 2 rows")

仅为这一次命令设置 ASCII 环境，不修改系统 locale 或调度器：

env LC_ALL=C PYTHONCOERCECLOCALE=0 PYTHONUTF8=0 \
  PYTHONIOENCODING=ascii:strict python3 encoding_probe.py
if env LC_ALL=C PYTHONCOERCECLOCALE=0 PYTHONUTF8=0 \
  PYTHONIOENCODING=ascii:strict python3 hello.py > bad.log; then
  printf 'Unexpected success\n'
else
  printf 'exit=%s\n' "$?"
fi

探针应显示 stdout_encoding: "ascii"、utf8_mode: 0；随后 traceback 含 UnicodeEncodeError，最后输出 exit=1，bad.log 为空。这里用 if 接住预期失败，便于在启用 set -e 的入口中观察结果。

3. 方法一：为标准流设置 UTF-8

日志接收端约定使用 UTF-8 时，给 Python 启动命令加上覆盖值：

env LC_ALL=C PYTHONCOERCECLOCALE=0 PYTHONUTF8=0 \
  PYTHONIOENCODING=utf-8:strict python3 hello.py > stdio.log

成功时退出码为 0，stdio.log 保存 完成: 2 rows 和换行。以 UTF-8 打开日志查看；显示器或查看工具解码错误，仍可能显示乱码。

PYTHONIOENCODING在解释器启动前设置标准输入、输出和错误流的编码。示例中的 strict 让标准输入/输出的无效转换报错；stderr 的错误处理仍使用 backslashreplace。它不会设置普通 open() 的文件编码；-E、-I 会忽略这些 Python 环境变量，排障时也要检查启动参数。

不要用 errors="ignore" 去掉报错，它可能直接丢掉业务文字。也不要在脚本启动后仅写 os.environ["PYTHONIOENCODING"]，已经建立的标准流不会因此重建。

4. 方法二：启动 UTF-8 模式，并明确文件编码

希望整个 Python 入口采用 UTF-8 默认值时，使用 -X utf8。先移除可能冲突的标准流覆盖：

env -u PYTHONIOENCODING LC_ALL=C PYTHONCOERCECLOCALE=0 \
  python3 -X utf8 hello.py > mode.log

Python UTF-8 模式也影响默认文本文件编码和文件系统编码。它只能在启动时配置；PYTHONIOENCODING=ascii 仍能覆盖标准流，因此只加 -X utf8 不足以抵消这项冲突。启用它也不会改变外部命令或日志查看器的编码。

对业务文件，按数据约定显式指定编码。保存为 report.py：

from pathlib import Path

source = Path("input.txt")
with source.open("r", encoding="utf-8", errors="strict") as handle:
    rows = sum(1 for line in handle if line.strip())
message = f"\u5b8c\u6210: {rows} rows\n"
Path("report.txt").write_text(message, encoding="utf-8", errors="strict")
print(message, end="")

创建两行 UTF-8 输入并运行：

python3 - <<'PY_INPUT'
from pathlib import Path
Path("input.txt").write_bytes("\u7532\n\u4e59\n".encode("utf-8"))
PY_INPUT
env LC_ALL=C PYTHONCOERCECLOCALE=0 PYTHONUTF8=0 \
  PYTHONIOENCODING=utf-8:strict python3 report.py > report.log

这里故意关闭 UTF-8 模式，只修复标准流；文件读写依然成功，因为代码明确写了 encoding="utf-8"。open() 文档说明未指定编码时的默认规则。实际来源是 GB18030、UTF-16 或带 BOM 的 CSV 时，应按CSV 编码排障教程确认格式，不能把所有字节都强行当 UTF-8。

5. 验证：检查退出码和真实字节

完成前面的文件创建与运行后，在演示目录执行自检。测试通过当前解释器启动子进程，以字节捕获输出，避免父进程的文本解码设置干扰断言：

python3 - <<'PY_CHECK'
import json
import os
from pathlib import Path
import subprocess
import sys

base = os.environ.copy()
base.update(LC_ALL="C", PYTHONCOERCECLOCALE="0", PYTHONUTF8="0",
            PYTHONIOENCODING="ascii:strict")
expected = "\u5b8c\u6210: 2 rows\n".encode("utf-8")

def run(args, env):
    return subprocess.run([sys.executable, *args], env=env,
                          capture_output=True, check=False, timeout=10)

probe = run(["encoding_probe.py"], base)
assert probe.returncode == 0, probe.stderr
info = json.loads(probe.stdout)
assert info["stdout_encoding"] == "ascii" and info["utf8_mode"] == 0, info
bad = run(["hello.py"], base)
assert bad.returncode != 0 and b"UnicodeEncodeError" in bad.stderr, bad
assert bad.stdout == b"", bad.stdout
stdio = dict(base, PYTHONIOENCODING="utf-8:strict")
fixed = run(["hello.py"], stdio)
assert fixed.returncode == 0 and fixed.stdout == expected, fixed
mode_env = base.copy()
mode_env.pop("PYTHONIOENCODING")
mode = run(["-X", "utf8", "hello.py"], mode_env)
assert mode.returncode == 0 and mode.stdout == expected, mode
override = run(["-X", "utf8", "hello.py"], base)
assert override.returncode != 0 and b"UnicodeEncodeError" in override.stderr
file_default = run(["-c", "from pathlib import Path; Path('input.txt').read_text()"], stdio)
assert file_default.returncode != 0 and b"UnicodeDecodeError" in file_default.stderr
report = run(["report.py"], stdio)
assert report.returncode == 0 and report.stdout == expected, report
assert Path("report.txt").read_bytes() == expected
for filename in ("stdio.log", "mode.log", "report.log"):
    assert Path(filename).read_bytes() == expected, filename
print("PASS: ASCII failure, both fixes, override precedence, file encoding, UTF-8 bytes")
PY_CHECK

预期打印最后一行 PASS: ...。测试覆盖 ASCII 输出失败、两种修复、冲突环境变量优先级，以及“标准流修好但默认文件解码仍失败”的分支，还逐字节核对三个日志和报表。它只使用演示目录的文件，不改生产任务。

6. 接入入口与排错

确认输出接收端接受 UTF-8 后，把选定的启动方式用于已有任务入口，并继续固定解释器和工作目录。文件日志若由 logging.FileHandler 创建，应独立设置 encoding="utf-8"；它不受标准流覆盖控制，参数见 FileHandler 官方文档。

现象	处理方式
`print()` 报 ASCII `UnicodeEncodeError`	在同一入口运行探针，检查 stdout，并在启动前设置 UTF-8 标准流。
加 `-X utf8` 后仍报 ASCII	查找并移除或修正冲突的 `PYTHONIOENCODING`，重新启动进程。
读文件报 `UnicodeDecodeError`	核对输入来源编码，为 `open()` 指定真实编码；标准流设置不能修复输入字节。
写日志不报错但显示乱码	检查日志字节和查看工具的解码设置，确保双方约定一致。
使用 `-E` 或 `-I`，环境设置无效	调整可控入口的启动选项，或使用 `-X utf8`；不要假定被忽略的变量仍会生效。
中文正确但日志迟迟不出现	继续排查输出缓冲和 pipefail，编码设置不负责刷新缓冲。

源码开头的 # coding: utf-8 只描述源码文件，不决定 print() 的编码。此教程也不修改系统 locale；若其他非 Python 工具依赖 locale，应单独核对其运行条件。

7. 小结

先在失败入口检查标准流的实际编码，再选用 PYTHONIOENCODING 或 -X utf8，并排除冲突设置。业务文件继续显式声明真实编码，用退出码和输出字节验证结果，避免仅凭日志看起来正常就判断修复成功。