pdm 不执行 setuptools.find_packages()，而是通过 pyproject.toml 中 tool.pdm.build.packages 显式声明包路径（如 {include = "mylib", from = "src"}）来确定打包内容，未正确配置会导致构建空包、import 失败及 ide 识别异常。
pdm 默认不读取 setup.py 或旧式 pyproject.toml 中的 [tool.setuptools] 配置，它使用自己的构建后端（pdm-backend），所以直接沿用传统 setuptools 写法会导致本地包构建失败、子包未被发现、可编辑安装后 import 报错。
为什么 find_packages() 在 PDM 里不生效
PDM 的构建逻辑绕过了 setuptools.find_packages() 的运行时调用——它在构建前就通过静态分析 pyproject.toml 中的 packages 字段或约定路径来确定要打包的模块。如果你只写 packages = ["mylib"]，但实际源码在 src/mylib/ 下，PDM 就会找不到任何 __init__.py，最终生成空包或报 No module named 'mylib'。
常见错误现象：
-
pdm build成功但生成的.whl里没有 Python 模块文件 -
pdm install -e后python -c "import mylib"报ModuleNotFoundError - IDE（如 PyCharm）识别不到包结构，补全失效
必须显式声明 packages 或启用 include 规则
PDM 不自动递归扫描 src/ 或项目根目录；它依赖明确的包路径声明。两种可靠方式：
- 用
packages列表直接写死路径：packages = [{include = "mylib", from = "src"}]（适用于src/mylib/结构） - 用
include+exclude模式匹配：include = ["src/**/*"]，再配合exclude = ["**/__pycache__/**", "**/*.pyc"] - 若坚持用传统布局（包名即目录名，无
src/），则写：packages = [{include = "mylib"}]，且确保mylib/__init__.py存在
示例（pyproject.toml 片段）：
[project]
name = "mylib"
version = "0.2.0"
# ... 其他元数据
<p>[tool.pdm]</p><h1>启用 pdm-backend（PDM 2.0+ 默认已启用，显式写更清晰）</h1><p>build-backend = "pdm.backend"</p><p>[tool.pdm.build]</p><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5288" title="提示词大师-python版"><img
src="https://img.php.cn/upload/skill/000/000/081/179042051830184.jpg" alt="提示词大师-python版" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill5288" title="提示词大师-python版" class="overflowclass">提示词大师-python版</a>
<p class="overflowclass">图片提示词生成器？不止如此。
马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。
用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。
用得越多，它越快：缓存机制让后续对话越来越省。
RAG进化：成功案例持续入库，越跑越聪明。
输入「新手指南」查看完整功能介绍</p>
</div>
<a rel="nofollow" href="/xiazai/skill5288" title="提示词大师-python版" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div><h1>✅ 正确：告诉 PDM 包物理位置</h1><p>packages = [{include = "mylib", from = "src"}]</p><h1>可选：额外包含非 Python 文件（如数据、schema）</h1><p>include = ["src/mylib/data/<strong>", "src/mylib/schemas/</strong>"]</p>
package-dir 映射在 PDM 中无效，别白费劲
你在 setup.py 里习惯写的 package_dir={"": "src"} 或 package_dir={"mylib": "src/mylib"}，对 PDM 完全不起作用。PDM 不解析 setup.py，也不支持该字段映射。试图保留 setup.py 并指望它影响 PDM 构建，只会让你陷入“明明写了却没用”的困惑。
真正起作用的是：
-
[tool.pdm.build].packages—— 控制哪些目录被打进 wheel -
[tool.pdm.build].includes—— 补充非模块文件 -
[tool.pdm.build].editable-verbose（布尔值）—— 开启后pdm install -e会打印详细符号链接路径，方便调试
如果你的项目用了 src/ 布局但没配 from = "src"，PDM 就默认从项目根找 mylib/，自然失败。
验证本地构建是否真生效
别只信 pdm build 不报错。检查生成物和运行时行为：
- 解压
dist/*.whl，确认mylib/目录及其下所有__init__.py都在mylib/路径下（不是顶层或嵌套错层） - 运行
pdm run python -c "import mylib; print(mylib.__file__)"，看路径是否指向__pypackages__/下的符号链接或已安装的 egg-link - 对子包（如
mylib.utils）执行导入测试，不能只测顶层包
最容易被忽略的一点：PDM 的可编辑安装（-e）依赖 pyproject.toml 中 [project].name 和实际包目录名严格一致。如果 name = "mylib"，但你的源码目录叫 mypkg，哪怕配了 from = "src"，也会因命名不匹配导致导入失败——PDM 不做重映射，只做路径搬运。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
