告别 Python 路径地狱：从“商店版”陷阱到标准版 Poetry 的踩坑实录

在跑一个基于 MCP (Model Context Protocol) 架构的前沿 AI4S (AI for Science) 项目 chemvcs 时，我遇到了一次非常典型的 Python 环境变量与依赖路径“连环翻车”事件。

如果你在执行 pip install --user 或者安装全局包（比如 Poetry）后，命令行疯狂提示：

WARNING: The script ... is installed in 'C:\Users\...\AppData\Local\Packages\PythonSoftwareFoundation...\LocalCache\local-packages\...\Scripts' which is not on PATH.

那么恭喜你，你很可能和我一样，掉进了 Windows 平台上特有的“微软商店版 Python 陷阱”。

这篇博客记录了我如何排查这个问题，并最终彻底推翻旧环境，使用 winget 和独立脚本搭建起干净、规范的 Python + Poetry 运行环境的全过程。

故障现场：找不到的 poetry.exe

故事的起因是我准备将一个项目的依赖管理从原始的 pip + venv 迁移到现代化的 Poetry。

按照常规流程，我运行了 pip install --user poetry。安装虽然显示“成功”，但紧接着控制台就刷出了一大片刺眼的黄色 WARNING。警告信息非常长，核心意思就是：你安装的包被放到了一个极深的隐藏目录下，而且这个目录不在系统的环境变量中。

当我满怀信心地输入 poetry install 准备启动项目时，PowerShell 无情地嘲笑了我：

poetry : 无法将“poetry”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

为什么会这样？

罪魁祸首是我当时使用的是 微软商店版 (Microsoft Store) 的 Python。

为了所谓的“安全性”和“沙盒化”，商店版的 Python 机制非常特殊。当你使用 pip install --user 安装可执行脚本时，它不会放在常规的用户目录下，而是被丢进了一个由 Windows 严格管控的沙盒缓存目录（LocalCache）。
这个路径不仅长得离谱，包含一堆随机字符串，更致命的是，它默认不会被添加到系统的 PATH 环境变量中。

破局：修补还是重建？

面对这个问题，通常有两个选择：

1. 修补法：手动把那个长达百个字符的 LocalCache 路径添加到系统环境变量里。
2. 重建法：卸载商店版 Python，安装官方标准版。

我一开始尝试了修补法，通过 PowerShell 的 [Environment]::SetEnvironmentVariable 强行把路径塞了进去。虽然勉强能跑，但我立刻意识到，这只是一时爽。未来安装的任何全局工具，都有可能在这个幽暗的沙盒路径里继续报错或者互相冲突。

果断决定：长痛不如短痛，直接推翻重建！

彻底解决：拥抱标准版与独立 Poetry

为了确保环境彻底干净，我执行了以下“破旧立新”的三步走战略。

第一步：卸载“半吊子”环境

打开 Windows 设置 -> 应用，搜索 Python，把所有带有“Microsoft Store”字样或之前安装的 Python 全部卸载干净。不要留恋。

第二步：使用 winget 安装官方标准版 Python

微软的包管理器 winget 现在已经非常好用了。打开一个全新的 PowerShell 窗口，运行：

winget install -e --id Python.Python.3.13

（如果你需要其他版本，修改结尾的版本号即可，例如 3.12。加上 -e 参数是为了精确匹配官方安装包，防止再次拉取到商店版。）

官方安装包会自动帮你处理好环境变量的问题，直接治愈“路径地狱”。

第三步：使用官方脚本独立安装 Poetry

不要再用 pip 去全局安装 Poetry 了，这会将项目依赖管理工具和特定的 Python 环境绑定，以后升降级 Python 版本时容易产生灾难。

业界最推荐的做法是使用官方的独立安装脚本。在 PowerShell 中运行：

# 先把安装脚本下载到本地
Invoke-WebRequest -Uri https://install.python-poetry.org -OutFile install-poetry.py -UseBasicParsing

# 运行脚本进行独立安装
python install-poetry.py

安装完成后，Poetry 会被放置在一个独立且规范的漫游目录中。最后，只需要将这个专属路径加入环境变量即可：

[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\你的用户名\AppData\Roaming\pypoetry\venv\Scripts", "User")

最后的关键一步：重启终端

在 Windows 上搞环境变量，最容易犯的低级错误就是忘了重启窗口。

所有的安装和配置完成后，必须关闭当前所有的命令行窗口。重新打开一个新的终端，输入：

poetry --version

看到亲切的 Poetry (version 2.x.x) 打印出来的那一刻，世界终于清静了。

总结

如果你在 Windows 下做 Python 开发：

1. 永远不要使用微软商店里的 Python。
2. 尽量不要用 pip install 全局安装像 Poetry、Pipenv 这种环境管理工具。
3. 遇到环境变量问题配置完后，第一件事就是重启终端。

从“路径地狱”里爬出来后，我终于可以切进 chemvcs 目录，舒舒服服地敲下 poetry install，看着依赖项流畅地跑完了。

---

希望这篇踩坑记录能帮到同样被 Windows 路径折磨的你。