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

# 第 2 AWS CLI 版的遷移指南
<a name="cliv2-migration"></a>

本節包含將第 1 AWS CLI 版更新為第 2 AWS CLI 版的說明。 AWS CLI 第 2 版以第 1 AWS CLI 版為基礎，包含以社群意見回饋為基礎的功能和增強功能。 AWS CLI 第 2 版是 的最新主要版本， AWS CLI 並支援所有最新的功能。在第 2 版中推出的某些功能無法回溯至第 1 版，因此您必須升級才能存取這些功能。

為了避免意外問題，在您遷移至第 2 版之前，[請先了解版本之間的差異](cliv2-migration-changes.md)。第 2 AWS CLI 版包含可能需要您更新指令碼或命令才能回溯相容性的新功能和變更。

AWS CLI 第 1 版和第 2 版使用相同的`aws`命令名稱。如果您已安裝兩個版本，您的電腦會使用搜尋路徑中找到的第一個版本。這可能會導致您的`aws`命令名稱呼叫舊 AWS CLI 版本，即使您已安裝新的版本。

若要更新到第 2 AWS CLI 版，請遵循下列其中一個指示：
+ 如果您先前已安裝 第 1 AWS CLI 版，請遵循 中的指示[從第 1 AWS CLI 版安裝第 2 AWS CLI 版](cliv2-migration-instructions.md)。
+ 如果您先前尚未安裝第 1 AWS CLI 版，請遵循 中的指示[AWS CLI入門](cli-chap-getting-started.md)。

## 使用 AWS CLI 遷移工具來緩解中斷
<a name="using-migration-tools"></a>

CLI AWS 第 1 版與 AWS CLI 第 2 版之間的行為有所變更，可能需要您更新指令碼或命令。升級至 AWS CLI 第 2 版，而不驗證您現有的指令碼在使用 CLI 第 2 AWS 版執行指令碼時，遇到意外效果的安全遷移風險，例如對 AWS 帳戶上的資源進行意外變更。

您可以使用兩個 AWS擁有的工具來引導遷移。無論您使用哪種工具，建議您在[第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)指南[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中參考 。

### 升級偵錯模式
<a name="cliv2-migration-upgrade-debug-mode"></a>

升級偵錯模式是 AWS CLI 版本 1 中的一項功能，可在版本 `1.44.0` 和更高版本中使用。啟用此功能時，會檢查您執行的每個 AWS CLI AWS 命令，以判斷它在 CLI 第 2 版中是否可能有不同的行為，假設執行環境保持不變。如果執行的命令在 CLI AWS 第 2 版中會有不同的行為，則會在命令輸出旁邊顯示警告，其中包含可採取的建議動作，以在 AWS CLI 第 2 版中保留 AWS CLI 第 1 版行為。

使用升級偵錯模式引導遷移的主要原因是，它在偵測命令是否會面臨行為變更方面具有很高的涵蓋範圍。 中所述的 15 個重大變更中，有 14 個[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)可以使用升級偵錯模式進行偵測，如需此功能的限制[使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-upgrade-debug-mode.md)，請參閱 [限制](cli-upgrade-debug-mode.md#upgrade-mode-limitations) 中的 。另一方面，使用升級偵錯模式的主要缺點是其輸出僅與其執行環境相關；如果遷移至 AWS CLI 第 2 版後，環境中有任何 AWS CLI 組態設定變更，則仍可能發生重大變更，您應該在更新的環境中使用升級偵錯模式重新驗證。

### AWS CLI v1 到 v2 遷移工具
<a name="cliv2-migration-migration-tool"></a>

 AWS CLI v1 到 v2 遷移工具是一種獨立工具，可與 Python 3.9 及更高版本搭配使用。此工具是獨立於 CLI AWS 執行的靜態 linter。它會內嵌包含 CLI AWS 第 1 版命令的 bash 指令碼，這些命令在 CLI AWS 第 2 版中可能有不同的行為。對於它偵測到在 CLI AWS 第 2 版中可能具有不同行為的大多數命令，它可以自動更新指令碼中的命令，以在 AWS CLI 第 2 版中保留 AWS CLI 第 1 版行為。

使用 AWS CLI v1 到 v2 遷移工具來引導遷移的主要原因是它可以自動更新您的指令碼，以保留 AWS CLI 第 2 版中的 AWS CLI 第 1 版行為，節省您自行進行更新的時間和精力。另一方面，使用遷移工具的主要缺點是，它在偵測命令是否會面臨行為變更方面具有較低的涵蓋範圍。作為靜態工具，它不會檢查執行時間決定的行為變更。

## 在升級偵錯模式和 AWS CLI v1 到 v2 遷移工具之間進行選擇
<a name="cliv2-migration-choosing-migration-tool"></a>

下表重點介紹升級偵錯模式與 AWS CLI v1 至 v2 遷移工具之間的主要差異，並可用來協助引導您為使用案例選擇正確的工具。


| 升級偵錯模式 | AWS CLI v1 到 v2 遷移工具 | 
| --- | --- | 
| 偵測 CLI 第 1 版與 AWS CLI 第 2 版之間 15 個重大變更中的 14 AWS 個。 | 偵測 CLI 第 1 版與 AWS AWS CLI 第 2 版之間 15 個重大變更中的 7 個。 | 
| 相容於可執行 CLI AWS 的任何終端機程式。 | 僅支援內嵌 bash 指令碼。 | 
| 需要 AWS CLI 第 1 版、版本1.44.0或更高版本。 | 獨立於 AWS CLI 執行；不需要安裝 AWS CLI。 | 
| 必須進行手動修正，才能在 AWS CLI 第 2 版中保留 AWS CLI 第 1 版行為。 | 自動修正大多數 CLI AWS 第 1 版命令，它在 CLI AWS 第 2 版中偵測到的行為可能不同。 | 
| 偵測和建議的修正僅與其執行所在的執行環境 （即 AWS CLI 組態） 相關。 | 偵測和建議的修正與環境無關。 | 
| 需要執行每個測試中的 AWS CLI 命令，以變更行為。 | 不需要執行任何 AWS CLI 命令。每個 bash 指令碼只需要執行一次。 | 
| 恰好有 5 個已知案例會輸出誤報偵測。 | 剛好有 3 個已知案例，其將輸出誤報偵測。 | 

下表顯示這兩種遷移工具各[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)支援哪些 。


| 重大變更 | 透過升級偵錯模式偵測 | 由 AWS CLI v1-to-v2 遷移工具偵測 | 
| --- | --- | --- | 
| [已新增環境變數以設定文字檔案編碼](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 是 | 否 | 
| [預設情況下，會以 base64 編碼字串的格式傳遞二進位參數](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 是 | 是 | 
| [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 是 | 是 | 
| [不會為參數自動擷取 `http://` 或 `https://` URL](cliv2-migration-changes.md#cliv2-migration-paramfile) | 是 | 否 | 
| [預設情況下，對於所有輸出使用的分頁程式](cliv2-migration-changes.md#cliv2-migration-output-pager) | 是 | 是 | 
| [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 是 | 否 | 
| [改善未造成任何變更的 CloudFormation 部署處理](cliv2-migration-changes.md#cliv2-migration-cfn) | 是 | 是 | 
| [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 是 | 否 | 
| [變更區域 AWS STS 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | 是 | 否 | 
| [已移除 `ecr get-login` 並替換為 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | 是 | 是 | 
| [AWS CLI 外掛程式的第 2 版支援正在變更](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 是 | 否 | 
| [已移除隱藏別名支援](cliv2-migration-changes.md#cliv2-migration-aliases) | 是 | 是 | 
| [不支援 `api_versions` 組態檔案設定](cliv2-migration-changes.md#cliv2-migration-api-versions) | 是 | 否 | 
| [AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求](cliv2-migration-changes.md#cliv2-migration-sigv4) | 是 | 否 | 
| [AWS CLI 第 2 版與分頁參數更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 是 | 是 | 
| [AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](cliv2-migration-changes.md#cliv2-migration-return-codes) | 否 | 否 | 

## 本區段的其他主題
<a name="migrate-topics"></a>
+ [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)
+ [從第 1 AWS CLI 版安裝第 2 AWS CLI 版](cliv2-migration-instructions.md)
+ [使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-upgrade-debug-mode.md)
+ [使用 AWS CLI v1 到 v2 遷移工具將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-migration-tool.md)