本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 套件概觀
<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 支援 [Cargo](using-cargo.md)、 [generic](using-generic.md)、[Maven](using-maven.md)、[npm](using-npm.md)、[NuGet](using-nuget.md)、[PyPI](using-python.md)、[Ruby](using-ruby.md)、[Swift](using-swift.md) 套件格式。

## 套件發佈
<a name="package-publishing"></a>

 您可以使用 `npm`、、`twine`、、 `Maven``Gradle``nuget`和 等工具，將任何[支援套件格式](#supported-package-formats)的新版本發佈至 CodeArtifact 儲存庫`dotnet`。

### 發佈許可
<a name="package-publishing-permissions"></a>

您的 AWS Identity and Access Management (IAM) 使用者或角色必須具有發佈至目的地儲存庫的許可。發佈套件需要下列許可：
+ **貨物：** `codeartifact:PublishPackageVersion`
+ **一般：** `codeartifact:PublishPackageVersion`
+ **Maven：** `codeartifact:PublishPackageVersion` 和 `codeartifact:PutPackageMetadata`
+ **npm：** `codeartifact:PublishPackageVersion`
+ **NuGet：** `codeartifact:PublishPackageVersion` 和 `codeartifact:ReadFromRepository`
+ **Python：**`codeartifact:PublishPackageVersion`
+ **Ruby：** `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 資產 的 Maven 套件`mypackage-1.0.jar`。只有在舊資產和新資產的檢查總和相同時，您才能再次發佈該資產。若要使用新內容重新發佈相同的資產，請先使用 **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 會防止您在 CodeArtifact 儲存庫`mydep 1.1`中發佈。

若要解決此問題，請將套件版本發佈至無法存取公有儲存庫的不同 CodeArtifact 儲存庫。然後使用 `copy-package-versions` API 將 的修補版本複製到您要使用它的 `mydep 1.1` CodeArtifact 儲存庫。

### 發佈的資產大小限制
<a name="package-publishing-asset-size-limits"></a>

可發佈的套件資產大小上限受限於 中顯示的**資產檔案大小上限**配額[配額 in AWS CodeArtifact](service-limits.md)。例如，您無法發佈大於目前資產檔案大小最大配額的 Maven JAR 或 Python 輪。如果您需要在 CodeArtifact 中存放較大的資產，請請求增加配額。

除了資產檔案大小配額上限之外，npm 套件的發佈請求大小上限為 2 GB。此限制與資產檔案大小最大配額無關，且無法隨著配額增加而提高。在 npm 發佈請求 (HTTP PUT) 中，套件中繼資料和 npm 套件 tar 封存的內容會綁定在一起。因此，可發佈的 npm 套件實際大小上限會有所不同，取決於包含中繼資料的大小。

**注意**  
發佈的 npm 套件的大小上限為小於 2 GB。

### 發佈延遲
<a name="package-publishing-latency"></a>

發佈至 CodeArtifact 儲存庫的套件版本通常可在一秒內下載。例如，如果您使用 將 npm 套件版本發佈至 CodeArtifact`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`。
+  **已封存** – 無法再下載套件版本的資產。套件版本不會包含在傳回給套件管理員的版本清單中。由於資產無法使用，用戶端對套件版本的使用會遭到封鎖。如果您的應用程式建置取決於更新為**已封存**的版本，則建置會中斷，假設套件版本尚未在本機快取。您無法使用套件管理員或建置工具來重新發佈**封存套件**版本，因為它仍存在於儲存庫中，但您可以使用 [UpdatePackageVersionsStatus API](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdatePackageVersionsStatus.html) 將套件版本的狀態變更回**未列出**或**已發佈**。
+  **已處置** – 套件版本不會顯示在清單中，且資產無法從儲存庫下載。**Disposed **和 **Archived** 之間的主要區別在於，狀態為 **Disposed** 時，CodeArtifact 會永久刪除套件版本的資產。因此，您無法將套件版本從**處置**移至**已封存**、**未列出**或**已發佈**。由於資產已刪除，因此無法再使用套件版本。套件版本標示為**已處置**後，您將不再支付套件資產的儲存費用。

呼叫 list-package-versions 時，預設會傳回所有狀態的套件版本，沒有`--status`參數。

 除了先前列出的狀態之外，也可以使用 [DeletePackageVersions API](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 不會在其他套件格式上執行標準化。