核心解法是设环境变量PYTHONUTF8=1，强制Python 3.7+全程用UTF-8处理路径；同时确保所有源文件（含pyproject.toml）为UTF-8无BOM编码，并避免pip构建时经过中文路径。
Python 在中文路径下安装或运行时报编码错误（比如 UnicodeDecodeError: 'gbk' codec can't decode byte 或 ModuleNotFoundError），不是路径写错了，而是 Python 进程启动时没用 UTF-8 解析文件系统路径——关键动作必须发生在 python 命令执行前，而不是在脚本里补救。
设置 PYTHONUTF8=1 环境变量（最核心一步）
这是 Python 3.7+ 原生支持的开关，它强制解释器全程用 UTF-8 处理路径、命令行参数和环境变量。不设这个，其他操作都可能晚了一步。
- Windows CMD：运行
set PYTHONUTF8=1后再执行pip install .或python main.py - PowerShell：
$env:PYTHONUTF8="1"，然后运行命令 - PyCharm：Run → Edit Configurations → Environment variables，添加
PYTHONUTF8=1；同时勾选Add content root to PYTHONPATH - Git Bash：在
~/.bashrc中加export PYTHONUTF8=1，重启终端
验证是否生效：python -c "import sys; print(sys.getfilesystemencoding())" 输出必须是 utf-8，不是 mbcs 或 cp936。
确保所有源文件是 UTF-8 无 BOM 编码
哪怕环境变量设对了，如果 setup.py、pyproject.toml 或某个 __init__.py 是 GBK 或带 BOM 的 UTF-8，pip 安装时就会在读取阶段崩掉——这不是路径问题，是文件内容解析失败。
SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、
立即学习“Python免费学习笔记（深入）”；
- VS Code：右下角点击编码名 → “Save with Encoding” → 选
UTF-8（不是UTF-8 with BOM） - PyCharm：File → Settings → Editor → File Encodings → 全部设为
UTF-8，且取消勾选Transparent native-to-ascii conversion - 记事本：另存为时手动选
UTF-8（别选ANSI或Unicode） -
pyproject.toml若含中文注释或值（如requires = ["requests", "我的私有包"]），也必须是 UTF-8 无 BOM
pip install 时避开中文路径参与解析
pip 在构建源码包时会递归扫描当前目录及其父目录（比如 C:\Users\张三\AppData\Local\Temp\pip-build-xxx），一旦中间某层路径含中文且未被 UTF-8 正确解码，就直接报错。
- 不要在中文路径下直接运行
pip install .；先cd到一个纯英文路径（如D:\tmp），再用绝对路径调用：pip install D:\我的项目\ - 若用
pyproject.toml，确认[build-system]部分没有引用中文路径的脚本或钩子 - 临时编译目录可指定：
pip install --build-dir D:\build .，确保D:\build是英文路径
pandas / open() 等库读中文路径要单独处理
像 pandas.read_csv() 报路径相关 UnicodeDecodeError，往往不是 Python 解释器的问题，而是底层 C 引擎硬编码 UTF-8 解码路径字符串导致的——这时 PYTHONUTF8=1 不起作用。
- 对
pandas.read_csv()，显式加engine='python'：pd.read_csv(r'D:\测试数据\用户.csv', engine='python') - 对
open()，始终显式传encoding参数：with open(r'D:\日志\2026-07.txt', encoding='utf-8') as f: - 用
pathlib.Path替代字符串拼接：Path(r'D:\配置').joinpath('app.json').read_text(encoding='utf-8')
最容易被忽略的是：环境变量必须在 Python 进程启动前生效。在脚本里写 os.environ['PYTHONUTF8'] = '1' 完全无效，因为路径解析早已完成。还有就是 pyproject.toml 和 setup.py 这类构建期文件，哪怕你运行时一切正常，它们只要有一个是 GBK 编码，pip 就会在安装阶段直接失败。
