uv run 下本地 Python 包为何会间歇性无法导入？

结论

这个案例的根因已经明确：PEP 660 editable 安装生成的 .pth 文件带有 macOS 隐藏文件标记 UF_HIDDEN，Python 因此跳过该文件，导致本地包 tfm_rag_municipal 无法导入。现有信息只指向 .pth 文件的隐藏标记问题，无法证明 pyproject.toml 缺少配置，也不足以说明这是 uv、uv_build 与 src 布局之间的普遍兼容问题。

为什么会出现导入失败

项目使用 uv init --package tfm-rag-municipal 创建，采用 src 布局，并通过 uv_build 构建。虽然 uv sync 显示本地项目已安装，Python 启动时仍需处理 editable 安装使用的 .pth 文件。如果文件带有 UF_HIDDEN 标记，Python 就会跳过它，源码路径也就不会按预期加入导入路径，最终可能出现：

ModuleNotFoundError: No module named 'tfm_rag_municipal'

删除 .venv 和 uv.lock 后重新运行 uv sync，故障可能暂时消失。这是因为新环境可能重新生成相关文件；如果隐藏标记再次出现，导入问题也可能复发。

检查并处理

先查看 Python 的详细启动输出，确认它是否跳过了 .pth 文件：

uv run python -v -c "import tfm_rag_municipal"

如果输出中出现类似提示，就与该案例确认的根因一致：

Skipping hidden .pth file: ...

可以尝试清除虚拟环境中的隐藏标记：

chflags -R nohidden .venv

另一种已报告的规避方式是将虚拟环境目录设为 venv/，而不是 .venv/。使用这种方式时，后续的 uv 命令也要指向该虚拟环境目录。

pyproject.toml 是否需要修改？

根据目前给出的根因，没有证据表明需要为此故障补充 uv 或 uv_build 配置。项目使用了 uv_build，问题则出在 Python 跳过带隐藏标记的 editable .pth 文件。现有材料也不足以断言这是 uv、uv_build 与 macOS src 布局之间的普遍已知问题。

备注：内容仅供参考。