Poetry 可编辑安装后 Python 无法启动，检查 Windows 中文路径的 pth 编码

Poetry 后端的可编辑安装刚完成，虚拟环境里的 Python 连简单命令都无法启动，报 Fatal Python error: init_import_site: Failed to import the site module，堆栈末尾是 site.py 读取 .pth 时的 UnicodeDecodeError。如果项目位于 Windows 中文路径，先检查写入与读取 .pth 的编码是否一致。

明确触发环境包括 poetry-core 2.5.0、Windows 11 的 CP936、Python 3.11.15，以及包含中文字符的项目绝对路径。安装前端可以是 uv；.pth 是后端生成的，不应只因错误出现在 uv sync 后就认定是 uv 写错文件。

编码错误发生在业务代码运行之前

poetry-core 2.5.0 的 editable wheel 会将源码绝对路径写入 .pth，统一使用 UTF-8。Python 3.11 和 3.12 的 site 则按 locale 编码读取；当 UTF-8 字节不能作为 CP936 解码时，解释器在初始化阶段便退出。

项目路径含非 ASCII 字符、旧 Python 的读取规则、非 UTF-8 系统编码，需要共同核对。不是每一个中文路径都会在同一字节报错，也不能把所有 init_import_site 错误都归为这项问题。先看 traceback 是否明确经过 .pth 文件读取和解码。

可以用编辑器或健康的外部工具只读检查该环境 Lib/site-packages 中对应的 .pth，确认其中指向的源码路径与字节编码。不要让已经启动不了的解释器反复执行诊断脚本，也不要批量删除所有 .pth；其他包可能依赖它们。

用普通安装或兼容解释器恢复环境

不要求源码修改立即生效时，可以改用非 editable 安装。它不靠这条源码路径 .pth 映射，但之后每次源码修改都需要重新构建或安装，开发流程应明确接受这个区别。

若使用已有 uv 项目且锁文件完整，可以在选定的新环境中采用 uv sync --locked --no-editable。先按原项目的环境配置选择一个尚不存在的位置，保留损坏环境用于核对；不要在没有确认目标目录时覆盖旧环境。项目采用其他安装前端时，使用对应的普通安装方式，不必仅为这项故障切换工具。

项目支持 Python 3.13 或更高时，也可以创建匹配的新环境。3.13 起的 site 会先尝试 UTF-8，再回退 locale；同一 CP936 条件下的 3.14.3 有成功读取记录。升级解释器仍需满足项目和依赖的支持范围，不能只为 .pth 强行跨版本。

使用只含 ASCII 的源码路径也能避开这组编码冲突，但移动项目会改变 editable 中的绝对路径，必须重新安装映射。复制源码后沿用旧环境，不会自动更新它指向的位置。

截至 2026 年 10 月 26 日，正式 poetry-core 仍是 2.5.0。不建议每次安装后手工转码 .pth：它可能在重建时被覆盖，路径也未必都能用系统编码表示。

恢复后先确认目标解释器能正常启动，再从项目目录之外导入目标包，核对普通安装或 editable 实际指向的位置。只在源码目录里导入成功，可能绕过了安装映射。最后运行项目原有测试，保留环境、锁文件与源码路径的一致记录。