uv Preview 特性机制详解启用方式、优先级顺序与全部 Preview Feature 列表【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv本文以官方文档 docs/concepts/preview.md 为主体完整讲解 uv 的 preview预览特性机制如何通过命令行、环境变量和配置文件启用或禁用预览功能当前版本支持的全部 preview feature 名称与用途以及从源码层面crates/uv-preview/src/lib.rs、crates/uv/src/settings.rs理解特性的解析优先级、未知特性的容错行为和配置加载前生效等特殊限制帮助你在安全尝鲜新特性的同时准确理解其生效边界。什么是 Preview 特性uv 包含一组需要显式开启的 opt-in preview 特性。其设计目标是在某个行为变更正式对所有用户默认开启之前先向社区提供反馈机会并在充分验证该变更总体是净收益之后再全量放开。因此 preview 特性通常处于行为可能随时变化的状态官方文档在 CLI 帮助中也明确提示 Preview features may change without warning。从源码结构看每个 preview 特性都是 crates/uv-preview/src/lib.rs 中PreviewFeature位标记枚举#[bitflags]repr(u64)的一个变体例如Pylock、JsonOutput、FormatCommand等运行时所有已启用特性被打包进一个Preview结构体内部是BitFlagsPreviewFeature并通过is_enabled(flag)进行判断。启用 Preview 特性的四种方式1.--preview标志一次性开启全部要开启所有preview 特性使用--preview全局标志$ uv run --preview ...2.UV_PREVIEW环境变量或者设置UV_PREVIEW环境变量等价于布尔开关$ UV_PREVIEW1 uv run ...在 CLI 定义中见 crates/uv-cli/src/lib.rs--preview使用BoolishValueParser即接受1、true等布尔值写法且通过overrides_with(no_preview)与--no-preview互斥覆盖。3.--preview-features标志按名称精确启用要只启用特定的 preview 特性使用--preview-features标志$ uv run --preview-features foo ...该标志可以重复出现以启用多个特性$ uv run --preview-features foo --preview-features bar ...也可以写成逗号分隔列表$ uv run --preview-features foo,bar ...逗号分隔在 crates/uv-cli/src/lib.rs 中通过value_delimiter ,实现该标志还有别名--preview-feature并且每个名称在解析时会先trim掉首尾空白单元测试 crates/uv-preview/src/lib.rs 验证了pylock , add-bounds这样的写法也能正确解析。4.UV_PREVIEW_FEATURES环境变量与配置文件UV_PREVIEW_FEATURES环境变量用法相同例如$ UV_PREVIEW_FEATURESfoo,bar uv run ...preview 特性也可以在uv.toml、pyproject.toml的[tool.uv]表或 PEP 723 元数据# /// script块中启用preview-features [foo, bar]设置preview-features true则等价于开启全部preview 特性。配置项的定义见 crates/uv-settings/src/settings.rs其中preview-features既可接受布尔值true表示全部开启也可接受特性名称列表。两个重要限制配置加载前生效的特性无法从配置文件启用少数 preview 特性在读取任何配置文件之前就已经影响行为例如target-workspace-discovery决定项目发现从哪个目录起步、project-directory-must-exist决定是否在发现阶段拒绝非法--project路径它们只能由--preview/--preview-features标志或环境变量开启写在uv.toml里不会生效。同时写preview与preview-features会报错PreviewOption::try_from在两者同时为Some时返回错误 cannot specify bothpreviewandpreview-features见 crates/uv-settings/src/settings.rs。旧版布尔配置键preview已标记为 deprecated建议统一使用preview-features。解析优先级多种来源冲突时谁说了算文档只列举了各种启用方式但没说清它们之间的优先级。crates/uv/src/settings.rs 中的resolve_preview函数给出了明确的裁决顺序显式的--preview/--no-preview标志优先级最高直接返回Preview::all()或Preview::default()UV_PREVIEWtrue环境变量布尔为真开启全部配置文件中的布尔全开preview true或preview-features true命令行显式指定的特性名称--preview-features非空时优先于配置文件中声明的名称列表其余情况回退到工作区配置uv.toml/pyproject.toml/ PEP 723 元数据中的preview-features列表。值得注意的一点是命令行的具名特性与配置文件的具名特性之间是覆盖而非合并关系只要命令行提供了--preview-features配置文件中的名称列表即被整体忽略。此外crates/uv/src/lib.rs 显示 uv 会在配置发现之前先执行一次早期预览解析此时 workspace 配置还不可用只取 CLI 标志与环境变量把结果写入全局uv_preview::set(...)这正是配置加载前生效的特性能够起作用的机制在后续完整配置解析完成后uv_preview::set再次更新并调用uv_preview::finalize()将状态锁定crates/uv/src/lib.rs。uv-preview内部用OnceLock 状态机Provisional→Final保证finalize之后不可再修改防止运行时出现不一致的预览状态见 crates/uv-preview/src/lib.rs。无需显式启用也能顺带使用的特性官方文档特别指出如果一个 preview 特性的行为变化是由某种用户交互自然门控的那么你可以在不改任何 preview 设置的情况下直接使用该行为。典型例子是pylock.toml支持在pylock特性仍处于 preview 期间你直接用uv pip install指向一个pylock.toml文件即可安装因为显式指定了pylock.toml文件本身就表明你希望使用这个特性——但 uv 会打印一条该特性处于 preview的警告显式开启 preview 特性可以消除该警告。类似的门控逻辑也出现在源码中例如--index按名称引用已配置索引时若未开启index-by-name特性会提示 Referencing an index by name is experimental and may change without warning. Pass--preview-features ...to disable this warning见 crates/uv-cli/src/lib.rs。未知特性名称警告但不报错文档明确出于向后兼容启用一个不存在的 preview 特性只会产生警告而不会报错无论该名称来自哪个来源。对应实现是MaybePreviewFeature枚举crates/uv-preview/src/lib.rs解析成功则为Known(PreviewFeature)失败则保留原始字符串为Unknown(String)随后Preview::from_feature_namescrates/uv-preview/src/lib.rs对每个未知名称调用warn_user_once!输出Unknown preview feature: \{name}并跳过。这样做的意义在于当用户配置了下一个版本才引入的特性名称时旧版本不会直接崩掉整个命令。配套的单测 [crates/uv-preview/src/lib.rs](https://link.gitcode.com/i/2cd6129f4aa19c1c72b761043d381bc5#L562-L565) 验证了unknown-feature,pylock只启用pylock一个特性。另外完全空白的特性名称如--preview-features 或列表中的空项会报preview feature name cannot be empty 错误。部分特性还定义了别名PreviewFeature上的#[preview(alias ...)]属性让旧名称继续可用例如format→format-command、audit→audit-command、check→check-command见 crates/uv-preview/src/lib.rs。当前可用的 Preview 特性列表文档中Available preview features一节的内容是由代码生成的cargo dev generate-preview-features-reference会读取PreviewFeature枚举的元数据PreviewMetadata宏并按名称排序渲染成 Markdown生成器见 crates/uv-dev/src/generate_preview_features_reference.rs生成产物为构建期文件docs/reference/.preview-features.md。以生成器内置的完整快照为准确当前仓库包含以下特性kebab-case 名称 用途特性名称说明add-bounds允许配置uv add调用的默认版本边界adjust-ulimit在 Unix 上于启动时把进程软打开文件数上限提升到硬上限artifact-hash-filtering将生成的依赖哈希限制在二进制与构建策略允许的构件范围内audit-command允许使用uv audit和uv tool audit别名auditauth-helper允许将uv auth helper作为外部工具的凭据助手使用azure-endpoint允许使用 Azure 凭据对配置的 Azure Blob Storage 端点签名请求cache-physical-space报告缓存清理实际回收的物理磁盘空间计入硬链接与写时复制克隆cache-size允许使用uv cache sizecentralized-project-envs将项目虚拟环境集中存储在 uv 缓存中check-command允许使用uv check别名checkcontent-addressed-cache在缓存中启用内容寻址的 wheel 归档detect-module-conflicts当多个包会把冲突的 Python 模块装入同一环境时发出警告extra-build-dependencies允许为包构建指定额外依赖format-command允许使用uv format别名formatgcs-endpoint允许对配置的 Google Cloud Storage 端点签名请求index-by-name允许用--index和--default-index按名称选择已配置的索引index-exclude-newer允许为已配置的包索引设置exclude-newerindex-hash-algorithm允许为已配置的包索引强制要求某种哈希算法init-project-flag拒绝uv init中已废弃的--project选项json-output为多个 uv 命令启用--output-format jsonlock-without-metadata在uv.lock中省略package.metadata表lockfile-format-check使用--locked或--check时拒绝非规范化的 lockfile 格式malware-check允许uv sync等命令在安装前通过 OSV 检查恶意软件metadata-json在构建的 wheel 中包含 JSON 元数据文件native-auth启用将凭据存储到系统原生位置如 keyringno-distutils-patch对 Python 3.10 不再向虚拟环境安装_virtualenv.py/_virtualenv.pth的 distutils 补丁package-conflicts允许在包级别定义 workspace conflictspackaged-init让uv init默认创建带src/布局、构建系统和脚本入口的打包应用project-directory-must-exist拒绝非法的--project路径除uv init外必须已存在。在配置加载前生效publish-require-normalized发布时要求规范化的发行文件名跳过未规范化的文件pylock允许从pylock.toml文件安装python-install-default允许安装python/python3可执行文件到系统relocatable-envs-default默认创建可重定位relocatable的虚拟环境s3-endpoint允许对配置的 S3 兼容端点签名请求sbom-export允许使用uv export --formatcyclonedx1.5special-conda-env-names不再把名为base或root的 Conda 环境视为特殊tar-codec使用新的tar-codec编解码后端替代astral-tokio-tartarget-workspace-discoveryuv run的本地目标所在目录而非 CWD作为项目发现起点。在配置加载前生效toml-backwards-compatibility构建 sdist 时将pyproject.toml重写为 TOML 1.0并将原文件保留为pyproject.toml.origtool-install-locks为每个已安装工具保存uv.lock用于可复现的安装、升级与审计venv-safe-clear除非提供--force否则uv venv --clear不会清空不含pyvenv.cfg的目录workspace-dir允许使用uv workspace dirworkspace-list允许使用uv workspace listworkspace-list-scripts允许使用uv workspace list --scriptsworkspace-metadata允许使用uv workspace metadata使用示例开启最常用的几个$ uv run --preview-features json-output,pylock ...禁用 Preview 特性--no-preview选项可以禁用 preview 特性。从 crates/uv/src/settings.rs 可见它返回Preview::default()即关闭全部特性并且由于--preview与--no-preview相互overrides_with二者中最后出现的那个决定最终状态——这意味着可以用--preview-features pylock --no-preview之类的组合在单条命令中整体关掉预览行为例如在 CI 中临时回归稳定行为。小结与使用建议尝鲜单个特性时用--preview-features name或UV_PREVIEW_FEATURES精确开启避免无差别打开全部实验性行为在uv.toml/pyproject.toml的preview-features中固化项目级配置但注意配置加载前生效的特性target-workspace-discovery、project-directory-must-exist必须走 CLI 或环境变量遇到 This option is in preview and may change in any future release 提示时说明该命令/选项仍属实验阶段行为与接口都可能调整特性列表随版本演进最新清单以生成器cargo dev generate-preview-features-reference产物和 crates/uv-preview/src/lib.rs 中PreviewFeature枚举为准本文表格对应当前仓库快照。【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考