根本原因是Python解释器未显式指定UTF-8编码读取含中文路径的文件，导致GBK解码失败；应设置PYTHONUTF8=1、确保源文件为UTF-8无BOM编码，并避免中文路径参与解析。
pytest 运行时报 UnicodeDecodeError: 'gbk' codec can't decode byte
这是 Windows 下最典型的中文路径问题：pytest 默认用系统默认编码（如 gbk）读取测试文件或 conftest.py，一旦路径含中文（比如 D:\我的项目\test_demo.py），就可能在解析源码、加载插件或读取配置时崩掉。
根本原因不是 pytest 本身不支持中文，而是 Python 解释器在打开文件时没显式指定 encoding='utf-8'，且 Windows 的 locale.getpreferredencoding() 返回 gbk，导致误解码。
实操建议：
- 确保所有 Python 源文件（
test_*.py、conftest.py、pyproject.toml）本身以 UTF-8 无 BOM 编码保存（VS Code / PyCharm 默认即可，记事本需手动选“UTF-8”） - 不要依赖文件系统路径自动解码——改用环境变量强制 Python 使用 UTF-8 模式
- 在运行 pytest 前，设置环境变量
PYTHONIOENCODING=utf-8和PYTHONUTF8=1（Python 3.7+ 支持）
PyCharm 或命令行中设置 PYTHONUTF8=1 不生效？
常见于 PyCharm 终端未继承环境变量，或 Windows 系统级变量未刷新。注意：PYTHONUTF8=1 必须在 Python 进程启动前生效，不是在 Python 里 os.environ['PYTHONUTF8'] = '1' 就能补救的。
立即学习“Python免费学习笔记（深入）”；
实操建议：
- 命令行中运行前先执行：
set PYTHONUTF8=1（Windows CMD）或$env:PYTHONUTF8="1"（PowerShell） - PyCharm：进入
Run → Edit Configurations → Environment variables，添加PYTHONUTF8=1；同时勾选Add content root to PYTHONPATH - 若用 Git Bash，需加
export PYTHONUTF8=1到~/.bashrc，并确认终端已重载 - 验证是否生效：运行
python -c "import sys; print(sys.getfilesystemencoding())"，输出应为utf-8
pyproject.toml 中配置 addopts 能绕过路径编码问题吗？
不能。像 addopts = ["-s", "--tb=short"] 这类选项只影响 pytest 行为，不改变 Python 解释器读取文件时的编码逻辑。但配合 testpaths 可间接规避部分路径解析场景。
实操建议：
- 在
pyproject.toml中显式指定测试入口，避免 pytest 自动递归扫描含中文的父目录：[tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"]
- 确保
tests/目录路径本身不含中文（哪怕项目根目录有中文，只要tests是英文名且位于盘符根下，风险大幅降低） - 禁用可能触发路径遍历的插件，例如某些自定义收集器或旧版
pytest-cov在 Windows 上对中文路径处理不稳
为什么改了环境变量还是报错？检查这三处硬编码路径
即使环境变量和文件编码都正确，仍有三个地方可能埋着隐性 gbk 强制解码逻辑：
-
conftest.py里手动用了open(path)且没写encoding参数（尤其在pytest_configure中读取本地配置文件时） - 第三方插件（如
pytest-html生成报告时写入report.html路径含中文，旧版本会崩）——升级到pytest-html>=3.2.0后已修复 - Windows 用户名含中文（如
C:\Users\张三\AppData\Local\Temp），pytest 临时缓存目录出问题。可临时覆盖：pytest --cache-dir=D:/temp/pytest_cache
最稳妥的做法是：开发阶段把项目放在纯英文路径下（如 D:/proj/myapp），CI/CD 流水线也统一约定路径命名规则。中文路径不是不能跑，而是每多一层路径参与解析，就多一个没显式指定 encoding 的潜在爆点。
