如何利用PDM工具管理Python项目_体验基于PEP 582的新型包管理

先说几个关键点：PDM 默认走的是 PEP 582 模式，项目依赖直接装进 __pypackages__ 目录，压根不建虚拟环境。这和 pipenv 或 poetry 那套“换壳 venv”的思路完全不同——它是在 Python 导入机制层面做文章：把 __pypackages__/X.Y/lib 塞进 sys.path 最前面，优先级高于系统 site-packages。但这个机制有个硬前提：Python 解释器得支持 -I（isolated）模式，或者通过 python -m pdm run 启动，否则 __pypackages__ 不会被自动识别。很多新手直接 python main.py 失败，就是因为没走 pdm run 这一层。

为什么 python main.py 找不到安装的包？

这是最常踩的坑：PDM 安装的包在 __pypackages__/3.11/lib 下，但直接调用系统 Python 时，sys.path 根本不含该路径。说白了，你安装的依赖和运行环境之间缺了一座桥。

• pdm run python main.py ✅ 自动注入 __pypackages__ 路径
• python main.py ❌ 纯系统解释器，完全无视 PDM 项目结构
• IDE（如 VS Code、PyCharm）得手动配置解释器为 pdm python list 返回的路径，再把 __pypackages__/X.Y/lib 加进 PYTHONPATH 或设为 Sources Root

pdm add 和 pdm install 的行为差异

这两个命令容易混淆。注意：pdm add 只写 pyproject.toml 并更新 pdm.lock，并不实际装包；pdm install 才真正解压包到 __pypackages__。这种分离是 PEP 621 + lockfile 模式的标准做法，类比 npm install vs npm add 就很好理解了。

• pdm add requests → 修改 pyproject.toml 中 [project.dependencies]，生成/更新 pdm.lock
• pdm install → 读 pdm.lock，将锁定版本装入 __pypackages__
• pdm install --prod → 跳过 [project.optional-dependencies.dev]，只装生产依赖
• CI 环境更推荐用 pdm sync 替代 install，它跳过解析直接按 lockfile 安装，更快更确定

如何让非 PDM 命令（如 pytest、mypy）正常工作？

这类工具默认不走 pdm run，所以会找不到本地包或 dev 依赖。正确做法不是改 PATH，而是用 pdm run 包一层：

• pdm run pytest tests/ ✅ 自动加载 __pypackages__ 和 dev 依赖（如 pytest）
• pdm run mypy src/ ✅ 同理
• 也可以在 pyproject.toml 的 [tool.pdm.scripts] 里定义别名：test = "pytest tests/"，然后 pdm run test
• 注意：有些工具（如 black）如果通过 pdm add --dev 安装，它本身就是可执行脚本，pdm run black . 就能直接调用，无需全局安装

迁移老项目时 pdm init 容易忽略的关键点

对于已有 requirements.txt 或 setup.py 的项目执行 pdm init，它不会自动导入依赖——只会生成空的 pyproject.toml。必须手动补全或用插件转换。

• pdm import requirements.txt ✅ 支持标准格式，但不处理注释或条件行（如 pkg; sys_platform == "win32"）
• pdm import setup.py ✅ 仅提取 install_requires，忽略 extras_require
• requires-python 字段必须显式写进 pyproject.toml，否则 pdm python install 不知道该装哪个 Python 版本
• __pypackages__ 是 Git 未跟踪目录，首次 pdm install 后记得 git add pyproject.toml pdm.lock，别漏了 lock 文件——它是复现环境的唯一依据

说到底，PEP 582 的威力不在“省掉 venv 命令”，而在于让 Python 解释器原生理解“当前项目专属依赖”。但这也意味着所有外部调用都得经由 pdm run 或显式配置 PYTHONPATH，否则就断联。这点和 Node.js 的 node_modules 行为一致，但 Python 开发者习惯性直呼 python，反而最容易在这里卡住。