本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 程序包概览
<a name="packages-overview"></a>

*程序包* 是解析依赖关系和安装软件所需的软件和元数据的捆绑包。在中 CodeArtifact，软件包由软件包名称、可选[命名空间](codeartifact-concepts.md#welcome-concepts-package-namespace)（如`@types`在）`@types/node`、一组软件包版本以及包级元数据（例如 npm 标签）组成。

**Contents**
+ [支持的软件包格式](#supported-package-formats)
+ [程序包发布](#package-publishing)
  + [发布权限](#package-publishing-permissions)
  + [覆盖程序包资产](#package-publishing-overwrite-assets)
  + [私有程序包和公有存储库](#package-publishing-upstreams-direct)
  + [发布经过修补的程序包版本](#package-publishing-patched-versions)
  + [发布的资产大小限制](#package-publishing-asset-size-limits)
  + [发布延迟](#package-publishing-latency)
+ [程序包版本状态](#package-version-status)
+ [程序包名称、程序包版本和资产名称规范化](#package-name-normalization)

## 支持的软件包格式
<a name="supported-package-formats"></a>

AWS CodeArtifact [[支持 C [argo、g](using-cargo.md) enerial、[Maven](using-maven.md)、[npm](using-npm.md)、、[NuGet](using-nuget.md)p [yPI、[Ruby](using-ruby.md)、Sw](using-python.md) ift 包格式。](using-swift.md)](using-generic.md)

## 程序包发布
<a name="package-publishing"></a>

 您可以使用诸如`npm`、、、、`twine`和之类的工具将任何[支持的软件包格式](#supported-package-formats)的新版本发布到 CodeArtifact 存储库`dotnet`。`Maven` `Gradle` `nuget`

### 发布权限
<a name="package-publishing-permissions"></a>

您的 AWS Identity and Access Management (IAM) 用户或角色必须具有发布到目标存储库的权限。发布程序包需要以下权限：
+ **Cargo：**`codeartifact:PublishPackageVersion`
+ **通用：**`codeartifact:PublishPackageVersion`
+ **Maven：**`codeartifact:PublishPackageVersion` 和 `codeartifact:PutPackageMetadata`
+ **npm：**`codeartifact:PublishPackageVersion`
+ **NuGet:** `codeartifact:PublishPackageVersion` 和 `codeartifact:ReadFromRepository`
+ **Python：**`codeartifact:PublishPackageVersion`
+ **红宝石：**`codeartifact:PublishPackageVersion`
+ **Swift：**`codeartifact:PublishPackageVersion`

在前面的权限列表中，IAM 策略必须为 `codeartifact:PublishPackageVersion` 和 `codeartifact:PutPackageMetadata` 权限指定 `package` 资源。还必须指定 `codeartifact:ReadFromRepository` 权限的 `repository` 资源。

有关中权限的更多信息 CodeArtifact，请参阅[AWS CodeArtifact 权限参考](auth-and-access-control-permissions-reference.md)。

### 覆盖程序包资产
<a name="package-publishing-overwrite-assets"></a>

 您无法重新发布已存在且包含不同内容的程序包资产。例如，假定您已经发布了一个具有 JAR 资产 `mypackage-1.0.jar` 的 Maven 程序包。仅当新旧资产的校验和完全相同时，您才能再次发布该资产。要重新发布包含新内容的相同资产，请先使用 **delete-package-versions** 命令删除该程序包版本。尝试重新发布具有不同内容但名称相同的资产会导致出现 HTTP 409 冲突错误。

 对于支持多种资产（通用、PyPI 和 Maven）的程序包格式，您可以向现有程序包版本添加使用不同名称的新资产，前提是您拥有所需的权限。对于通用程序包，只要程序包版本处于 `Unfinished` 状态，就可以添加新资产。由于 npm 的每个程序包版本仅支持单个资产，因此若要以任何方式修改已发布的程序包版本，都必须先使用 **delete-package-versions** 删除版本。

 如果您尝试重新发布已存在的资产（例如 `mypackage-1.0.jar`），并且已发布资产和新资产的内容相同，则因为该操作具有幂等性，所以操作会成功。

### 私有程序包和公有存储库
<a name="package-publishing-upstreams-direct"></a>

 CodeArtifact 不会将存储在存储 CodeArtifact 库中的软件包发布到公共存储库，例如 npmjs.com 或 Maven Central。 CodeArtifact 将软件包从公共存储库导入 CodeArtifact 存储库，但它从不向另一个方向移动包。您发布到 CodeArtifact 存储库的软件包将保持私密状态，并且仅供您授予访问权限的 AWS 账户、角色和用户使用。

### 发布经过修补的程序包版本
<a name="package-publishing-patched-versions"></a>

 有时，您可能想要发布修改后的程序包版本，可能是在公有存储库中可用的版本。例如，您可能在名为 `mydep 1.1` 的关键应用程序依赖项中发现了一个错误，您需要在程序包供应商审查和接受更改之前尽快修复该错误。如前所述，如果可以通过上游 CodeArtifact存储库和外部连接从您的存储库访问公共 CodeArtifact 存储库，则 CodeArtifact 禁止您在存储库中发布`mydep 1.1`。

要解决此问题，请将软件包版本发布到无法访问公共存储库的其他存储库。 CodeArtifact 然后使用 `copy-package-versions` API 将的修补版本复制`mydep 1.1`到您要从中使用它的 CodeArtifact 存储库。

### 发布的资产大小限制
<a name="package-publishing-asset-size-limits"></a>

可以发布的程序包资产的最大大小受**资产文件大小最大配额**的限制，如[中的配额 AWS CodeArtifact](service-limits.md)中所示。例如，您发布的 Maven JAR 或 Python Wheel 不能超过当前资产文件大小的最大配额。如果您需要在中存储更大的资产 CodeArtifact，请申请增加配额。

除了资产文件大小的最大配额外，npm 程序包发布请求的最大大小为 2 GB。此限制与资产文件大小的最大配额无关，不能随着配额的增加而提高。在 npm 发布请求 (HTTP PUT) 中，程序包元数据和 npm 程序包 tar 存档的内容捆绑在一起。因此，可以发布的 npm 程序包的实际最大大小会有所不同，具体取决于所包含元数据的大小。

**注意**  
已发布的 npm 包的最大大小限制为小于 2 GB。

### 发布延迟
<a name="package-publishing-latency"></a>

发布到 CodeArtifact 存储库的 Package 版本通常可以在不到一秒钟的时间内下载。例如，如果您将 npm 包版本发布到 wit CodeArtifact h`npm publish`，则该版本应在不到一秒钟的时间内可供`npm install`命令使用。但是，发布可能不一致，有时可能需要更长的时间。如果您必须在发布后立即使用程序包版本，请使用重试来确保下载可靠。例如，发布程序包版本后，如果第一次尝试下载时刚刚发布的程序包版本最初不可用，请重复下载最多三次。

**注意**  
从公有存储库导入程序包版本通常要花比发布更长的时间。有关更多信息，请参阅 [外部连接延迟](external-connection-requesting-packages.md#external-connection-latency)。

## 程序包版本状态
<a name="package-version-status"></a>

中的每个软件包版本都 CodeArtifact 有一个描述软件包版本的当前状态和可用性的状态。您可以使用 AWS CLI 和 SDK 来更改程序包版本状态。有关更多信息，请参阅 [更新程序包版本状态](update-package-version-status.md)。

程序包版本状态的可能值如下所示：
+  **已发布** - 已成功发布程序包版本，可以使用程序包管理器来请求版本。在返回给程序包管理器的程序包版本列表中将包括该程序包版本，例如，在 `npm view <package-name> versions` 的输出中。程序包版本的所有资产均可从存储库中获得。
+  **未完成** - 客户端已上传程序包版本的一个或多个资产，但尚未通过将其变为 `Published` 状态来最终完成上传。当前，只有通用程序包版本和 Maven 程序包版本可以处于 `Unfinished` 状态。对于 Maven 程序包，当客户端上传程序包版本的一个或多个资源但没有为包括该版本的程序包发布 `maven-metadata.xml` 文件时，就会发生这种情况。当 Maven 程序包版本是**未完成**时，向客户端（例如 `mvn` 或 `gradle`）返回的版本列表中不会包括该版本，因此在构建时不能使用该版本。通过在调用 [PublishPackageVersion](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_PublishPackageVersion.html)API 时提供`unfinished`标志，可以故意将通用包保持在`Unfinished`状态。可以通过省略`unfinished`标志或调用 [UpdatePackageVersionsStatus](https://docs.aws.amazon.com//codeartifact/latest/APIReference/API_UpdatePackageVersionsStatus.html)API 将通用包更改为`Published`状态。
+  **未列出** - 可以从存储库下载程序包版本的资产，但向程序包管理器返回的版本列表中未包括该程序包版本。例如，对于 npm 程序包，`npm view <package-name> versions` 的输出将不包括该程序包版本。因为在可用版本列表中未显示该版本，这意味着 npm 的依赖项解析逻辑不会选择该程序包版本。但是，如果 `npm package-lock.json` 文件中已经引用了**未列出的**程序包版本，则仍然可以下载和安装该版本，例如在运行 `npm ci` 时。
+  **已存档** - 无法再下载该程序包版本的资产。在返回给程序包管理器的版本列表中不会包括该程序包版本。由于资产不可用，因此会阻止客户端使用程序包版本。如果您的应用程序构建依赖于更新为**已存档**的版本，那么构建就会出问题，前提是该程序包版本尚未在本地缓存。[您不能使用包管理器或构建工具重新发布**存档**包版本，因为该版本仍存在于存储库中，但您可以使用 API 将包版本的状态更改回 “**未上市**” 或 “**UpdatePackageVersionsStatus 已发布**”。](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdatePackageVersionsStatus.html)
+  **已处置** - 程序包版本未出现在列表中，也无法从存储库下载资产。它们之间的主要区别在于**，**如果**处**置状态为 “已**处置**”，则软件包版本的资产将被永久删除 CodeArtifact。因此，您无法将程序包版本从**已处置**更改为**已存档**、**未列出**或**已发布**。由于已删除资产，因此无法再使用该程序包版本。将程序包版本标记为**已处置**后，我们将不再向您收取程序包资产的存储费用。

不 list-package-versions带`--status`参数调用时，将默认返回所有状态的 Package 版本。

 除了前面列出的状态外，还可以使用 [DeletePackageVersionsAPI](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeletePackageVersions.html) 删除软件包版本。删除程序包版本后，存储库中将不再存在该版本，您可以使用程序包管理器或构建工具随意地重新发布该程序包版本。删除程序包版本后，我们将不再向您收取程序包版本的资产的存储费用。

## 程序包名称、程序包版本和资产名称规范化
<a name="package-name-normalization"></a>

CodeArtifact 在存储软件包名称、软件包版本和资源名称之前对其进行标准化，这意味着中的名称或版本 CodeArtifact 可能与发布软件包时提供的名称或版本不同。有关如何标准化每种软件包类型的名称和版本 CodeArtifact 的更多信息，请参阅以下文档：
+ [Python 程序包名称规范化](python-name-normalization.md)
+ [NuGet 程序包名称、版本和资产名称规范化](nuget-name-normalization.md)

CodeArtifact 不对其他包格式执行标准化。