Poetry 本身不控制模块查找顺序，真正起作用的是 Python 解释器对 PYTHONPATH 环境变量的默认行为：它会无条件将 PYTHONPATH 目录优先插入 sys.path 开头，导致全局包覆盖 Poetry 虚拟环境中的同名包，引发版本冲突与 ModuleNotFoundError。
poetry 本身不控制模块查找顺序，真正起作用的是 python 解释器对 pythonpath 环境变量的默认行为：它会无条件将 pythonpath 目录优先插入 sys.path 开头，导致全局包覆盖 poetry 虚拟环境中的同名包，引发版本冲突与 modulenotfounderror。
Python 的模块导入机制严格遵循 sys.path 的搜索顺序。根据 官方文档，当 PYTHONPATH 环境变量被设置时，其指定的路径会被自动、无条件地 prepend 到 sys.path[0] —— 即最优先位置。这意味着，无论你使用 poetry run python script.py 还是 poetry shell 激活环境，只要 PYTHONPATH 存在，Python 解释器就会先尝试从该路径加载模块，而非 Poetry 创建的隔离虚拟环境（如 venv/lib/python3.12/site-packages）。
这正是你复现问题的核心原因：
-
PYTHONPATH=C:\...\Python38\Lib\site-packages使 Python 3.12 解释器在启动时立即将该路径置顶； -
import numpy触发查找，解释器首先命中 Python 3.8 安装的numpy（位于PYTHONPATH）； - 但该
numpy是为 Python 3.8 编译的 C 扩展（如_multiarray_umath），与 Python 3.12 不兼容 → 报错； -
keyboard无报错，是因为它纯 Python 实现、无 C 扩展依赖，且未在PYTHONPATH中存在，故回退到 Poetry VE 中的正确版本。
✅ 正确做法不是“让 Poetry 忽略 PYTHONPATH”，而是尊重 Python 的设计契约，隔离环境变量影响：
✅ 推荐解决方案（按优先级排序）
1. 移除或局部化 PYTHONPATH（首选）
PYTHONPATH 是全局污染源，违背现代 Python 工程实践。应彻底避免设为系统/用户级环境变量：
# Windows PowerShell：临时清除（当前会话有效） $env:PYTHONPATH = $null # 或在 poetry 命令前显式清空（推荐用于 CI/脚本） poetry run $env:PYTHONPATH=''; python test.py # Linux/macOS 等效写法 PYTHONPATH= poetry run python test.py
⚠️ 注意：不要在
.bashrc/profile/ 系统属性中永久设置PYTHONPATH。若第三方软件（如你的 Python 插件）强依赖它，请改用更安全的方式：
- 将插件所需路径通过
sys.path.insert(0, ...)在插件入口脚本中动态添加；- 或为该插件单独配置一个仅含必要包的最小 Python 环境（如
venv），避免污染主系统。
2. 验证 sys.path 实际顺序（调试必备）
在 test.py 开头加入诊断代码，确认问题根源：
# test.py
import sys
print("=== sys.path (first 5 entries) ===")
for i, p in enumerate(sys.path[:5]):
print(f"{i}: {p}")
print("\n=== PYTHONPATH env var ===")
print(repr(sys.environ.get("PYTHONPATH")))
import keyboard
import numpy
print("✓ All imports succeeded")
运行 poetry run python test.py，你会清晰看到 PYTHONPATH 路径位于 sys.path[0]，而 Poetry VE 路径（如 .../Lib/site-packages）排在其后。
3. （进阶）在 Poetry 配置中强制重置 PYTHONPATH
若无法修改外部环境（如受限 CI 环境），可利用 Poetry 的 scripts 或 virtualenvs.create 行为间接干预：
# pyproject.toml [tool.poetry.scripts] debug-path = "test:print_sys_path" # 指向自定义诊断函数 # 或在 CI 脚本中统一前置清理 # .github/workflows/ci.yml - run: PYTHONPATH= poetry install - run: PYTHONPATH= poetry run python test.py
❌ 不推荐的误区
-
试图用
poetry config修改此行为：Poetry 无相关配置项，因PYTHONPATH是 Python 解释器原生机制，Poetry 无法也不应覆盖； -
在
pyproject.toml中 hackscripts添加os.environ.pop("PYTHONPATH")：虽可行但属权宜之计，掩盖了根本问题； -
降级使用
pip install poetry：如知识库所述，这反而加剧全局依赖冲突，与 Poetry 的隔离初衷背道而驰。
总结
PYTHONPATH 是 Python 解释器的“全局开关”，它的存在即意味着放弃环境隔离。Poetry 的价值恰恰在于构建干净、可重现的依赖边界——而 PYTHONPATH 会单方面撕开这个边界。真正的工程规范不是绕过它，而是根除它。 清理 PYTHONPATH 后，poetry run 将严格使用虚拟环境中的包，所有依赖解析、C 扩展兼容性、import 行为均回归预期。对于必须共存多 Python 版本的场景（如你的 Python 3.8 插件），请始终采用进程级隔离（独立 venv / py -3.8 -m venv），而非全局环境变量污染。
? 提示：在 PyCharm 中，若已配置 Poetry 解释器但仍遇到导入问题，请检查
Settings > Project > Python Interpreter是否显示正确的 Poetry 环境路径，并确保PYTHONPATH未在Run Configuration > Environment variables中被意外继承。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
