uv 0.3.x 变更日志解读：project / tool / script / python 统一接口的正式稳定化
uv 0.3.x 变更日志解读project / tool / script / python 统一接口的正式稳定化【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv本文基于 uv 仓库中的 changelogs/0.3.x.md完整梳理 uv 0.3.0 至 0.3.5 这一版本区间的核心变化四大统一接口项目、工具、脚本、Python 管理如何从 preview 状态转正为生产可用以及随之而来的破坏性变更、新增环境变量与重要缺陷修复。读完本文你可以对照源码理解 0.3.x 各条目的实现落点并据此完成从 0.2.x 到 0.3.x 的升级评估。0.3.0 里程碑四大接口脱离 preview0.3.0 是 uv 的标志性版本。此前隐藏在 preview 标志之后的uvproject、tool、script 与 python 接口在该版本正式稳定进入生产可用状态。这意味着项目接口uv init/uv add/uv remove/uv sync/uv lock不再需要预览开关工具接口uv tool install/uv tool run即uvx的前身用法成为官方推荐的单命令运行 CLI 工具方案PEP 723 内联元数据脚本可通过uv run script.py直接执行Python 解释器生命周期由 uv 全权接管安装、发现、固定。与此同时uv venv中原本处于 preview 的 Python 版本行为被一并稳定uv venv --python version在找不到匹配解释器时会自动下载所需的 Python 版本uv venv会读取.python-version文件或pyproject.toml中声明的 Python 版本要求。官方同时明确uv pip接口在本版本不受任何破坏性变更影响。完整的特性列表可参考仓库文档 docs/getting-started/features.md 与 docs/concepts/python-versions.md由于新特性是作为 preview 功能增量加入的0.3.0 的 changelog 条目并不包含全部新增内容。0.3.0 破坏性变更逐条对照源码理解1. 目录策略迁移到 XDG 标准含 macOS这是 0.3.0 最影响部署的变更Migrate to XDG and Linux strategy for macOS directories。迁移前macOS 使用~/Library/Application Support/uv等原生路径迁移后所有 Unix 平台统一遵循 XDG Base Directory 规范。仓库源码 crates/uv-dirs/src/lib.rs 完整体现了这一策略。以工具可执行文件目录为例user_executable_directory的解析优先级为$OVERRIDE_VARIABLE即用户自定义覆盖变量如UV_TOOL_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin缓存与状态目录则分别对应$XDG_CACHE_HOME/uvuser_cache_dir见 lib.rs与$XDG_DATA_HOME/uvuser_state_dir见 lib.rs。源码中保留了legacy_user_cache_dir/legacy_user_state_dir两个旧策略函数lib.rs用于迁移场景下兼容旧路径。一个实现细节值得注意parse_xdg_path会拒绝相对路径lib.rs——这遵循 XDG 规范环境变量中的路径必须是绝对路径的要求而 uv 自有覆盖变量则通过parse_path允许相对与绝对路径两种形式。升级影响如果你的脚本或 CI 中硬编码了~/Library/Caches/uv、~/Library/Application Support/uv这类旧 macOS 路径升级到 0.3.x 后需要改为 XDG 路径或显式设置UV_CACHE_DIR等覆盖变量。2. 并发设置提升到顶层Move concurrency settings to top-level--concurrency相关配置项从uv pip子命令层级提升至全局顶层配置使 pip 接口与项目接口共享同一套并发控制。3. 系统 Python 过滤同样作用于可执行名请求Apply system Python filtering to executable name requests当以可执行文件名而非版本号请求 Python 时--only-system/--no-python-downloads等过滤条件现在同样生效行为与版本号请求保持一致。4. 移除--legacy-setup-py参数该 CLI 参数被彻底删除[#4255]。0.2.x 中依赖此参数回退旧版setup.py行为的脚本需要改用构建隔离相关选项。5. 稳定化 preview 特性Stabilize preview features移除 preview 开关上述接口默认启用。0.3.0 新特性与解析器改进python_version in ...标记支持0.3.0 新增了对python_version in ...这类成员关系标记的支持。这一能力落在 uv 的 PEP 508 标记求值器中in与contains运算符在代数化表示中被当作布尔变量单独处理见 crates/uv-pep508/src/marker/algebra.rs而树形标记的求值与简化逻辑在 crates/uv-pep508/src/marker/tree.rs 中实现其单元测试直接覆盖了python_version in 2.7 3.2 3.3、python_version in 3.9, 3.10、python_version in 3.9.*等典型表达式tree.rs。约束锁定的环境矩阵Allow user to constrain supported lock environments用户可通过tool.uv.environments显式限定 lock 时覆盖的环境组合而不是让 uv 穷举所有 marker 组合。uv add -r requirements.txtuv add现在支持直接从 requirements 文件批量导入依赖[#6005]为从 pip 生态迁入项目接口提供了便利。解析器错误信息的大规模优化本版本集中改进了无解unsatisfiable场景的可读性any of 与 all of 的措辞修正[#6222]折叠枚举可用版本的冗余依赖条款[#6160]、折叠不可用包信息[#6154]区间为复数时修正不可用包的消息[#6221]--offline模式下改进解析器错误提示[#6156]名称含 marker 或 extras 时简化可用版本区间[#6162]。其他值得注意的条目条目说明32-bit Windows 目标新增发布目标[#6252].egg-info文件名放宽不再要求文件名必须包含版本号[#6179]uv add不再覆盖带不同 marker 的依赖避免同名不同 marker 的依赖被相互覆盖[#6010]environment-markers更名为resolution-markers术语统一[#6240]关于最后一条更名内部实现中的对应函数即resolution_markers定义在 crates/uv/src/commands/pip/mod.rs被pip compile、pip install、pip sync、pip check等命令统一调用用于将--python-version/--python-platform等 CLI 选项转换为标记环境。0.3.2 的pip compile --universal也补上了对tool.uv.environments的尊重[#6663]。配置与环境变量0.3.x 期间新增的可调项0.3.x 区间内新增的四个环境变量在源码中均可找到定义全部声明于 crates/uv-cli/src/lib.rs环境变量引入版本作用源码位置UV_TOOL_BIN_DIR0.3.0自定义uv tool安装可执行文件的目录lib.rsuv tool dir帮助文本中列出完整优先级链UV_TOOL_BIN_DIR→XDG_BIN_HOME→XDG_DATA_HOME/../bin→HOME/.local/binUV_PYTHON_DOWNLOADS0.3.2控制 Python 自动下载取值auto/neverlib.rs对应 CLI 选项--allow-python-downloads/--no-python-downloadsUV_PYTHON_PREFERENCE0.3.2控制 managed / system / only-managed 等解释器选择偏好lib.rs全局选项python_preferenceUV_COMPILE_BYTECODE0.3.3控制安装时是否编译.pyc字节码lib.rs性能方面0.3.0 在uv-auth中启用了FxHash哈希算法[#6149]见 crates/uv-auth/src/lib.rs。0.3.1围绕uv run与缓存稳定性的集中修复0.3.1 的条目以缺陷修复为主几个高价值条目uv run --with-editable允许以可编辑模式注入本地包.python-version尊重范围扩大uv python find、项目外的uv run均会读取.python-version[#6369]、[#6361]uvx的 Ctrl-C 处理正确响应中断信号[#6346]pip compile输出改为原子写[#6274]并避免覆盖符号链接0.3.2 的 [#6487] 进一步加固虚拟工作区的dev-dependencies变化时正确使uv.lock失效[#6291]缓存对已删除归档的鲁棒性[#6284]manylinux兼容性可通过_manylinux模块覆盖[#6039]为自托管 Linux 发行版上的本地 wheel 安装提供了逃生通道uv run python始终调用找到的解释器[#6363]uv run使用sys_executable[#6354]保证解释器一致SSH 依赖保留 Git 用户名[#6335]。0.3.2JSON Schema 修复与缓存路径回归修复两个 Python 行为环境变量UV_PYTHON_DOWNLOADS、UV_PYTHON_PREFERENCE在此版本落地见上表workspace 配置 schema 拒绝非法 members[#6450]移除 JSON Schema 中的uri类型[#6449]修正 uv.schema.json 的校验类型编辑器补全与校验工具可正确工作性能优化当远端不支持 range 请求且已发现METADATA时停止流式读取 wheel[#6470]修复 Windows 缓存路径丢失cache后缀的问题[#6482]这是对 0.3.0 XDG 迁移的一个回归修复Windows 下.pyw文件被识别为脚本[#6453]无效 extras 在标记求值中按false处理[#6395]。0.3.3uv sync的安装粒度控制0.3.3 最重要的增强是三个uv sync跳过开关为 monorepo 与特殊部署场景提供了精确控制uv sync --no-install-project不安装当前项目本身仅同步依赖uv sync --no-install-workspace跳过所有 workspace 成员的安装uv sync --no-install-package name按包名跳过特定成员。配套的重要修复与增强uv run会设置VIRTUAL_ENV[#6543]脚本内依赖VIRTUAL_ENV判断环境的代码恢复正常uv add期间 sync 失败时回滚pyproject.toml的变更[#6526]避免留下半成品配置uv python find将虚拟环境中的解释器纳入搜索结果[#6521]uv run支持-从 stdin 读取脚本[#6481]uv python pin --no-workspace新增--no-project别名[#6514]--no-config时忽略.python-version[#6513]。0.3.4构建隔离与 wheel 元数据解析加固setup.py项目支持按依赖的构建隔离[#6517]并修复了默认 strict 同步导致构建隔离环境被过度同步的问题[#6606]uv sync尊重--no-build-isolation-package[#6605]wheel 的WHEEL与METADATA文件改为按 email 消息格式解析[#6616]提高对非规范元数据的容错--find-links及 HTML 源支持未加引号的 href[#6622]PEP 723 脚本支持扩展到 GUI 文件[#6611]uv add设置最低版本界后同步更新锁文件[#6618]--find-links与本地注册表使用相对路径[#6566]标记类型区分 raw 与 resolver 两种表示[#6646]减少两类标记混用引发的 bug。0.3.5信任主机与requires.txt--allow-insecure-host别名--trusted-host与 pip 对齐允许对自签名证书的内部仓库跳过 TLS 校验[#6591]存在requires.txt时自动读取[#6655]兼容部分包将运行依赖与构建依赖分文件声明的惯例uv add默认写入相对路径[#6686]提升pyproject.toml的可移植性空求解/空安装场景的信息提示改进[#6588]检测 musl 环境并对 musl Python 构建报错[#6643]——uv 托管的 Python 构建面向 glibc混用 musl 构建会破坏 wheel 标签兼容性工具升级时避免跨版本复用状态[#6660]。升级检查清单若你正从 0.2.x 升级到 0.3.x建议按以下顺序核对路径检查 CI/脚本中是否有硬编码的旧版 macOS 缓存/状态路径迁移至 XDG 路径或显式设置UV_CACHE_DIR等覆盖变量策略实现见 crates/uv-dirs/src/lib.rs参数确认没有使用已移除的--legacy-setup-py--concurrency相关选项需迁移到顶层配置如依赖旧的environment-markers命名改为resolution-markers术语确认tool.uv.environments的旧写法environment-markers配置键已更新行为uv venv会自动下载缺失的 Python 版本离线环境请显式加--no-python-downloads对应UV_PYTHON_DOWNLOADSneveruv run现在会设置VIRTUAL_ENV0.3.3 起注意对依赖该变量判定的脚本的影响uv pip接口官方确认不受破坏性变更影响可原样保留。小结0.3.x 区间是 uv 从pip 兼容工具走向统一 Python 项目管理器的关键阶段0.3.0 完成四大接口转正并统一目录策略0.3.1–0.3.5 则围绕uv run/uvx/uv sync的行为正确性、缓存稳定性、构建隔离与元数据容错做了密集的加固。该区间的全部条目以 changelogs/0.3.x.md 为准文中涉及的实现细节分别可在 crates/uv-dirs/src/lib.rs、crates/uv-cli/src/lib.rs、crates/uv/src/commands/pip/mod.rs 与 crates/uv-pep508/src/marker/tree.rs 中追溯验证。【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考