Uv2nix使用中最可能踩的10个坑官方FAQ精华解读【免费下载链接】uv2nixUv2nix - Ingest uv workspaces using Nix [maintaineradisbladis]项目地址: https://gitcode.com/gh_mirrors/uv/uv2nixuv2nix 是什么uv2nix 是一个把 uv 工作区workspace用 Nix 确定性构建的工程化工具它读取你的pyproject.toml与uv.lock动态生成 Nix 派生项既能搭开发环境也能构建生产包。本文基于官方 FAQ 与文档整理出新手最容易踩的10 个坑帮你少走弯路。一分钟了解 uv2nix 的工作方式理解下面这条主线后面的坑就好理解了uv.lock只是依赖清单缺少构建元数据uv2nix 没有内置的包来源偏好wheel 还是 sdist 由你自己决定所有 Python 包都通过overlay动态生成开发 shell 和生产包建议用两套 overlay想解决的问题对应官方文档位置构建失败 / overridesdoc/src/FAQ.md、doc/src/overriding/index.md开发环境配置doc/src/usage/getting-started.mdMacOS / Linux 平台怪癖doc/src/platform-quirks.md旧版 nixpkgsdoc/src/old-nixpkgs.md冲突依赖doc/src/conflicts.md坑 1-4元数据与 overrides最核心的两难坑 1以为 uv.lock 里有完整元数据结果包构建失败这是官方 FAQ 的第一个问题My package $foo doesnt build!。原因是uv.lock元数据中明显缺失一些关键构建信息。官方 FAQ 的口径很直白uv2nix只能用手里有的东西。解决办法就是写 override详见doc/src/overriding/index.md里的 sdist 与 wheel 两种 override 示例。坑 2期待 uv2nix 自带 overrides 集合发现并没有从 poetry2nix 转过来的用户最常踩这个坑。官方 FAQ 的解释是uv2nix 只专注把pyproject.tomluv.lock正确翻译成 Nix不去掩盖元数据缺陷poetry2nix 的 override 负担很大程度来自它默认构建 sdist而 uv2nix 不强制默认来源维护 overrides 曾是 poetry2nix 维护者倦怠的最大来源所以你有两条路自己维护一套 overrides或直接用第三方 overrides 集合。坑 3没想清楚就选了 sourcePreference创建 overlay 时必须二选一overlay workspace.mkPyprojectOverlay { sourcePreference wheel; # 或 sdist };wheel优先下载二进制轮子大概率开箱即用sdist优先源码构建需要更多手动 override新手建议默认选 wheel。也支持按单个包粒度切换来源。坑 4MacOS 上该用 wheel 的包却悄悄走了 sdistNixpkgs 并不知道你实际的 MacOS 版本是多少。如果你发现明明有 wheel 却用了 sdist需要在创建包集时覆盖darwinSdkVersion例如设为15.1具体写法见doc/src/platform-quirks.md。Linux 侧同理可用environ.platform_release覆盖内核版本用于 PEP-508 标记求值。坑 5-8构建系统与开发环境坑 5忘记 uv 不锁定构建系统uv 官方目前不锁定从源码构建包所需的构建系统。uv2nix 不掩盖这个缺陷而是单独提供一个构建系统 overlaypyproject-build-systems它同样分 wheel/sdist 两版。忘了引入它sdist 构建就会莫名其妙失败。坑 6开发 shell 里顺手用了 uv run官方 Getting Started 里用 IMPORTANT 级别强调用 uv2nix 搭建开发 shell 时不要用uv run因为它会让 uv 自建一个虚拟环境与 Nix 管理的环境打架。正确的环境变量三件套UV_NO_SYNC1虚拟环境由 uv2nix 管理UV_PYTHON指向 Nix 里的解释器UV_PYTHON_DOWNLOADSnever禁止 uv 下载托管 Python另外 shell 中要unset PYTHONPATH并导出REPO_ROOT可编辑包的相对基准目录。坑 7在 workspace 根目录做 source filtering技术上可行但官方强烈不推荐uv2nix 在求值期读取 workspace 根根级过滤会导致 import-from-derivation还会和 editable 包冲突。正确姿势是在单个 Python 包级别过滤app prev.app.overrideAttrs (old: { src builtins.filterSource (_: _: true) old.src; })完整示例见doc/src/patterns/source-filtering.md。坑 8editable 包和生产包共用一套 overlay可编辑包开发时源码改完立即生效必须单独生成一套 overlay 和包集并指定root $REPO_ROOT普通生产 overlay 不能直接混用。建议只对需要的成员启用 editable并配合包级 source filtering 减少重建频率。坑 9-10版本与冲突依赖坑 9老版本 nixpkgs 没给 uv 打补丁uv2nix 支持 nixpkgs 22.11但 24.11 的旧渠道需要手动覆盖pyproject.nix的构建钩子要求uv 0.5.7旧渠道自带版本不够新。解法是用 uv2nix 自带的uv-bin包覆盖 nixpkgs 的uv写法见doc/src/old-nixpkgs.md。坑 10用了 conflicting dependencies 却没指定冲突解析uv 支持互斥依赖组conflicting dependencies但用 uv2nix 生成 overlay 时必须明确告诉它取哪一套解析否则求值或构建会出问题workspace.mkPyprojectOverlay { sourcePreference wheel; dependencies { hello-world [ extra1 ]; }; }避坑速查清单 构建失败 → 先想uv.lock元数据缺失写 overrideoverrides 要自己维护或找第三方集合拿不准就先sourcePreference wheelMacOS 上包来源不对 → 检查darwinSdkVersion从源码构建 → 记得叠加构建系统 overlay开发 shell 里禁用uv run设置UV_NO_SYNC等source filtering 只做在包级别不碰 workspace 根editable 用独立 overlay $REPO_ROOTnixpkgs 24.11 → 覆盖uv到 0.5.7conflicting dependencies → 在 overlay 中显式选边把这 10 条对照一遍uv2nix 的绝大多数玄学报错都能提前预防。【免费下载链接】uv2nixUv2nix - Ingest uv workspaces using Nix [maintaineradisbladis]项目地址: https://gitcode.com/gh_mirrors/uv/uv2nix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考