问题现象与定位
在自动化脚本、爬虫日志或API封装中,经常遇到这种情况:requests.get()或urllib.request.urlopen()本地测试能拿到响应,放到Linux服务器、crontab定时任务、SSH终端或Docker容器里执行时却抛出UnicodeEncodeError,例如:'ascii' codec can't encode character '\u4f60' in position 0: ordinal not in range(128)。同样的脚本在PyCharm里正常,在screen里执行就崩,或者只在打印中文日志那一行失败,HTTP请求本身并没有报错。
根因不在requests,也不一定是少写了encoding='utf-8',而是Python把Unicode字符串写入终端或标准输出流时,底层受系统locale和sys.stdout.encoding影响。Python启动时会读取LANG、LC_ALL,据此设置sys.stdout.encoding;如果变量为C或为空(常见于Docker容器、最小化安装系统、crontab环境),stdout编码可能变成ascii,print('你好')就会在编码转换时失败。可先用下面命令确认:
- python -c 'import sys; print(sys.stdout.encoding)'
复制代码
如果返回ascii,基本就是病根。requests返回的response.text本身是str(Python 3中即Unicode字符串),合法且可用;真正触发异常的是print()、logging.info()、str(obj)、repr(obj)等把Unicode转成字节流输出的动作。因此不要一上来给requests加encoding参数,而要先看traceback是否指向输出环节。典型场景包括:SSH非交互shell直接执行脚本、crontab定时任务、Docker容器内运行;它们通常只阻断输出或日志,不影响请求发送。还要注意,某些traceback指向requests/models.py的content getter,可能只是lazy decode的表象,真正崩在后续print()。
五种落地修复方案
1. 永久修复系统locale
这是最干净的做法。以Ubuntu/Debian为例:
- # 查看当前locale
- locale
- # 生成并启用UTF-8 locale(以en_US为例)
- sudo locale-gen en_US.UTF-8
- sudo update-locale LANG=en_US.UTF-8
- # 当前session立即生效
- export LANG=en_US.UTF-8
- export LC_ALL=en_US.UTF-8
- # 永久生效:写入/etc/environment
- echo 'LANG=en_US.UTF-8' | sudo tee -a /etc/environment
- echo 'LC_ALL=en_US.UTF-8' | sudo tee -a /etc/environment
复制代码
en_US.UTF-8兼容性最好;若需中文界面可用zh_CN.UTF-8,但要确认系统已生成该locale,可用locale -a | grep zh_CN检查。/etc/environment优于~/.bashrc,因为它会被cron、systemd等进程读取,且不执行shell命令。CentOS/RHEL可用localectl set-locale LANG=en_US.UTF-8,再用localectl status验证。Docker用户应在Dockerfile中显式设置locale,例如基于python:3.9-slim安装locales、执行locale-gen en_US.UTF-8、update-locale,并写入ENV LANG en_US.UTF-8与ENV LC_ALL en_US.UTF-8。
2. 代码层强制重置stdout/stderr编码
无法改环境或权限受限时,可在脚本最顶部、import requests之前重置输出流:
- import sys
- import io
- if sys.stdout.encoding != 'UTF-8':
- sys.stdout = io.TextIOWrapper(
- sys.stdout.buffer,
- encoding='utf-8',
- errors='backslashreplace',
- line_buffering=sys.stdout.line_buffering
- )
- if sys.stderr.encoding != 'UTF-8':
- sys.stderr = io.TextIOWrapper(
- sys.stderr.buffer,
- encoding='utf-8',
- errors='backslashreplace',
- line_buffering=sys.stderr.line_buffering
- )
- import requests
- r = requests.get('https://httpbin.org/get')
- print('响应状态:', r.status_code)
- print('中文内容:', r.json().get('args', {}).get('q', '默认查询'))
复制代码
原理是用io.TextIOWrapper重新包装sys.stdout.buffer和sys.stderr.buffer,并指定encoding='utf-8'。errors可选'backslashreplace'、'ignore'、'replace';生产环境推荐'backslashreplace',既不丢数据又可读。
3. requests层面精准规避输出
如果只关心response中的特定字段,没必要打印整个response.text。可直接操作response.content并用json.loads()指定编码:
- import requests
- import json
- r = requests.get('https://httpbin.org/get')
- data = json.loads(r.content.decode('utf-8'))
- query = data.get('args', {}).get('q', '无查询')
- print(f'Query: {query!r}')
- print('Query:', query.encode('unicode_escape').decode('ascii'))
复制代码
r.content.decode('utf-8')强制用UTF-8解码,避开r.text的自动编码逻辑;{query!r}使用repr格式化,会把中文转成ASCII转义形式,stdout.encoding即使是ascii也不容易崩。
4. logging模块的UTF-8安全配置
很多项目用logging替代print,但默认StreamHandler和FileHandler同样受stdout编码影响。应显式指定encoding:
- import logging
- file_handler = logging.FileHandler('app.log', encoding='utf-8')
- file_handler.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
- logger = logging.getLogger()
- logger.setLevel(logging.INFO)
- logger.addHandler(file_handler)
- logger.info('请求成功,参数:%s', {'q': '搜索关键词'})
复制代码
如果坚持用StreamHandler,可尝试handler.stream = open('/dev/stdout', 'w', encoding='utf-8'),但该方法在部分旧版Python(<3.7)可能报错,此时改用FileHandler写磁盘日志更普适。
5. 临时环境变量注入
CI/CD或单次调试可用env临时注入locale,无需root权限:
- env LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 python script.py
复制代码
Jenkins Pipeline可写成sh 'env LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 python3 main.py'。GitHub Actions可在run步骤中设置env: LANG: en_US.UTF-8、LC_ALL: en_US.UTF-8。缺点是每次都要加,不持久。
常见排查经验
1. locale显示LANG=en_US.UTF-8,但Python仍输出ascii:cron或systemd可能没继承shell环境。cron中显式写LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8;systemd service添加Environment;也可在脚本开头设置os.environ['LANG'],但要在import sys之后、print之前。
2. Docker内locale -a能看到UTF-8,Python仍是ascii:Alpine默认不带glibc locale数据,locale-gen无效,建议换python:3.9-slim等Debian基础镜像;Debian/Ubuntu镜像应在Dockerfile中ENV LANG=C.UTF-8,C.UTF-8比en_US.UTF-8更轻量可靠。
3. print('你好')不报错,print(含中文dict)报错:dict的__str__内部会调用repr,复合对象字符串化仍依赖stdout编码。不要直接print含中文的dict/list,改用json.dumps(obj, ensure_ascii=False, indent=2),或遍历后用f'{k}: {v!r}'输出。
4. 重置stdout后input()中文乱码或卡死:input()依赖sys.stdin,需同步重置sys.stdin,但非交互环境如cron无意义,仅适合需要input()的CLI工具。
5. subprocess.run()调用子脚本仍报错:子进程不继承父进程的sys.stdout重置,需在子脚本中同样处理,或用env={**os.environ, 'LANG': 'en_US.UTF-8', 'LC_ALL': 'en_US.UTF-8'}注入。
上线验证与pytest回归
部署含中文输出的脚本前,可按顺序检查四项:一是locale命令应显示LANG=en_US.UTF-8且LC_ALL非空;二是python -c 'import sys; print(sys.stdout.encoding)'应返回utf-8;三是requests请求含中文参数时能正确解码,并检查requests版本(≥2.25.0)及响应头Content-Type: application/json; charset=utf-8;四是logging输出中文正常,必要时启用FileHandler。把这几条命令写成healthcheck.sh放入CI流水线,可拦截大部分编码问题。
可用pytest模拟sys.stdout.encoding='ascii'的恶劣环境,验证修复是否生效:
- import io
- import sys
- def test_print_chinese_with_ascii_stdout():
- original_stdout = sys.stdout
- try:
- sys.stdout = io.TextIOWrapper(
- io.BytesIO(),
- encoding='ascii',
- errors='strict'
- )
- print('测试中文')
- except UnicodeEncodeError:
- assert False, 'UnicodeEncodeError 未被修复'
- finally:
- sys.stdout = original_stdout
复制代码
还可以在项目入口或__init__.py中放一段“编码保险丝”,作为低成本兜底:
- import sys
- import io
- if sys.stdout.encoding.lower() != 'utf-8':
- sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='backslashreplace')
- sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='backslashreplace')
复制代码
它不解决系统locale的根本问题,但在忘记配置环境、CI未注入变量时,能避免日志和调试输出直接失效。结合locale修复、代码层兜底、logging显式编码和pytest回归,才能把“请求发得出去、结果打不出来”的UnicodeEncodeError稳定压住。 |