企业官网建设流程全解析

uv 如何接入 AWS CodeArtifact：安装与发布私有 Python 包

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

这篇文章解决一个具体的集成任务：让 uv 能够从 AWS CodeArtifact 私有仓库安装 Python 包，并把你自己构建的包发布回 CodeArtifact。完成配置后，pyproject.toml中声明的私有索引会参与依赖解析与安装，uv publish则负责上传构建产物。前提条件只有一条：机器上已安装并认证了awscli（文档原文如此说明）。整个操作路径以仓库中的 AWS CodeArtifact 集成指南为主，发布部分补充了 构建与发布指南的内容。

在 pyproject.toml 中声明 CodeArtifact 索引

uv 通过[[tool.uv.index]]配置项声明私有索引（机制见 索引文档）。将 CodeArtifact 仓库声明为如下形式：

[[tool.uv.index]] name = "private-registry" url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"

需要替换的占位符及含义：

• <DOMAIN>：你的 CodeArtifact domain 名称；
• <ACCOUNT_ID>：AWS 账户 ID；
• <REGION>：CodeArtifact 仓库所在区域；
• <REPOSITORY>：仓库名称。

name = "private-registry"中的索引名是后续所有环境变量命名的依据：uv 用索引名的大写形式（非字母数字字符替换为下划线）拼接凭据环境变量名，因此凭据变量会写作UV_INDEX_PRIVATE_REGISTRY_*。

安装前配置认证：两种可选方式

uv 支持从 CodeArtifact 安装包，认证有两条路径：AWS access token（Basic 认证）或keyring。二选一即可。

方式一：使用 AWS access token

凭据通过 Basic 认证传递：token 放在 URL 的密码字段，用户名必须是aws，否则认证会失败。

先用awscli生成 token：

export AWS_CODEARTIFACT_TOKEN="$( aws codeartifact get-authorization-token \ --domain <DOMAIN> \ --domain-owner <ACCOUNT_ID> \ --query authorizationToken \ --output text )"

这是一个基础示例，文档提示你可能需要额外参数（如--region）才能正确生成 token。

然后为索引设置凭据：

export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AWS_CODEARTIFACT_TOKEN"

PRIVATE_REGISTRY必须与pyproject.toml中定义的索引名一致（大写形式）。凭据来源与优先级规则可在 HTTP 认证文档中查阅。

方式二：使用 keyring 与 keyrings.codeartifact 插件

keyrings.codeartifact插件封装 boto3 生成短时效 access token，存入系统 keyring 并在过期时刷新。因为keyring与该插件本身就是认证依赖，它们必须从 CodeArtifact 以外的源（如公共 PyPI）预先安装：

# 从公共 PyPI 预装 keyring 和 AWS CodeArtifact 插件 uv tool install keyring --with keyrings.codeartifact # 启用 keyring 认证 export UV_KEYRING_PROVIDER=subprocess # 设置索引的用户名 export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws

使用此方式有两个硬限制：uv 只在 subprocess 模式下支持keyring包（pip的auto/import选项不受支持）；keyring可执行文件必须在PATH中（全局安装或安装在当前活跃环境）。

也可以不用环境变量，改为在uv.toml或pyproject.toml中写tool.uv.keyring-provider = "subprocess"，并把用户名直接写进索引 URL（文档中两种替代写法都给出了说明）。

从 CodeArtifact 安装私有包

索引声明和凭据环境变量就位后，uv 的解析与安装命令（如uv lock、uv sync）即会使用该索引：uv 按pyproject.toml中的声明顺序查询索引，索引上的包从 CodeArtifact 下载。安装是否成功，可用 发布指南给出的通用检查命令验证——确认包能装上且能导入：

$ uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"

其中<PACKAGE>替换为你要验证的包名；--no-project用于避免把包从本地项目目录安装进来。如果刚发布过包，可加--refresh-package <PACKAGE>避免命中缓存版本。

发布自己的包到 CodeArtifact

发布走uv publish，与发布到 PyPI 是同一套流程（见 构建与发布指南）。

先构建包，产物会落在dist/目录：

$ uv build

文档建议发布时运行uv build --no-sources，以确保在禁用tool.uv.sources的情况下（例如使用其他构建工具时）包仍能正确构建。

然后给要发布的索引添加publish-url：

[[tool.uv.index]] name = "private-registry" url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/" publish-url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/"

注意两条 URL 的差别：url以simple/结尾，用于解析和安装；publish-url以<REPOSITORY>/结尾，用于上传。

若未使用 keyring 方式，需配置发布凭据（token 沿用安装阶段生成的AWS_CODEARTIFACT_TOKEN）：

$ export UV_PUBLISH_USERNAME=aws $ export UV_PUBLISH_PASSWORD="$AWS_CODEARTIFACT_TOKEN"

最后执行发布：

$ uv publish --index private-registry

这里--index接的是索引名。使用uv publish --index <name>时项目必须存在pyproject.toml（例如发布 CI 中需要有 checkout 步骤），否则命令无法定位索引配置。

可选分支：不配置 publish-url，直接用 UV_PUBLISH_URL

如果不想改项目的pyproject.toml，可以改用环境变量指定发布地址：

$ export UV_PUBLISH_URL=https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/ $ uv publish

文档明确说明此方式不是首选：uv 无法在上传前检查包是否已经发布过。

发布失败与缓存相关的限制

• uv publish会重试失败的上传，但仍可能出现"部分文件已上传、部分缺失"的中断状态。PyPI 上可直接重跑同一命令（相同的已存在文件会被忽略）；对 CodeArtifact 这类其他 registry，文档给出的是配合索引 URL（不是 publish URL）使用--check-url <index url>：使用--index时会直接以该索引 URL 作为 check URL，uv 跳过与 registry 中完全一致的已传文件，并处理并行的重复上传。前提是现存文件与之前上传的内容完全一致。
• 认证不是跨调用缓存的：凭据在单次 uv 命令生命周期内有效，每次调用都需要环境变量或 keyring 可用。
• uv publish默认会尝试上传 attestation（PEP 740），但 uv 目前不生成 attestation，需要事先单独创建；如果第三方索引拒绝带 attestation 的上传，可用--no-attestations或UV_PUBLISH_NO_ATTESTATIONS关闭该默认行为。

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv