本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版
本主題說明 CLI 第 AWS 1 版中的升級偵錯模式。
我們建議 AWS CLI 第 1 版的使用者升級至 AWS CLI 第 2 版，以存取新功能和增強的效能。CLI AWS 第 1 版與 AWS CLI 第 2 版之間的行為有所變更，可能需要您更新指令碼或命令以取得相同的行為。當您使用 CLI AWS 第 2 版中行為不同的功能時， AWS CLI 第 1 版中的升級偵錯模式會輸出警告。此功能會自動偵測哪些 AWS CLI 第 1 版命令需要在升級至 CLI AWS 第 2 版之前修改，以防止意外問題，藉此改善升級體驗。
如需詳細資訊，請參閱 [中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中的 [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)。
## 先決條件
升級偵錯模式功能已引入版本 中的 AWS CLI`1.44.0`。
使用 AWS CLI 第 1 版，執行 `aws --version`，並確認 CLI AWS 版本為 `1.44.0` 或更新版本。
如果版本小於 `1.44.0`，請參閱[安裝、更新和解除安裝 AWS CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html)。
## 運作方式
如果啟用，升級偵錯模式會偵測 CLI 第 2 AWS 版中因重大變更而更新的功能使用情況。如果您在升級至 CLI AWS 第 2 版[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)後使用 中列出的命令或功能，輸出中會顯示警告。中斷變更偵測是根據使用的命令、提供的引數、執行環境 （例如環境變數、組態設定等），以及在少數情況下， AWS 使用帳戶中資源的內容或組態。
警告說明動作，以防止升級至 CLI AWS 第 2 版時發生非預期的問題。進行警告訊息建議的變更後，您可以重新執行命令以確認警告不再顯示，以確認命令已成功更新。正在解決的警告表示命令不會再遇到升級到 CLI AWS 第 2 版時所描述的重大變更。
下列範例示範這些警告的外觀。此命令示範範例警告。所有警告文字都以「AWS CLI V2 UPGRADE WARNING」開頭，後面接著特定的警告訊息。在此情況下，會輸出警告，因為 命令依賴 AWS CLI 擷取 URL 的內容，並使用內容做為`--template-body`參數值，這是在 CLI 第 2 版中移除 AWS 的功能。
```
$ aws cloudformation create-stack \
--stack-name "stack012345" \
--template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"
AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or
https://, AWS CLI v2 will not automatically request the content of the URL for
the parameter, and the `cli_follow_urlparam` option has been removed. See
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.
```
下表列出所有重大變更，以及如何避免在 CLI AWS 第 2 版中面臨重大變更。解決偵錯模式中警告的修復動作為粗體。
| 突破性變更 | 在 v1 上，遷移至 v2 行為 | 在 v2 上，保留 v1 行為 |
| --- | --- | --- |
| [已新增環境變數以設定文字檔案編碼](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 取消設定 PYTHONUTF8和 PYTHONIOENCODING 環境變數。 | 將AWS\$1CLI\$1FILE\$1ENCODING環境變數設定為 v1 中指定的編碼。 |
| [預設情況下，會以 base64 編碼字串的格式傳遞二進位參數](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 使用 base64 編碼 參數的值。如果從檔案載入 參數，請使用 base64 編碼檔案內容。 | 將 cli\$1binary\$1format設定設為 raw-in-base64-out。 |
| [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 使用 --copy-props none 參數。 |
| [不會為參數自動擷取 `http://` 或 `https://` URL](cliv2-migration-changes.md#cliv2-migration-paramfile) | 使用 curl （或其他工具） 將 URLs的內容下載到本機檔案。然後，使用 file[：//](https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-parameters-file.html) 將檔案內容載入 參數。或者，將 cli\$1follow\$1urlparam設定為 false，將原始 URL 指定為參數值。 | 不適用。 無法在第 2 版中保留第 1 版行為。 |
| [預設情況下，對於所有輸出使用的分頁程式](cliv2-migration-changes.md#cliv2-migration-output-pager) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 將cli\$1pager設定或AWS\$1PAGER變數設定為空字串。 |
| [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 將 cli\$1timestamp\$1format 設定設為 iso8601。 | 將 cli\$1timestamp\$1format設定設為有線。 |
| [改善未造成任何變更的 CloudFormation 部署處理](cliv2-migration-changes.md#cliv2-migration-cfn) | 使用 --no-fail-on-empty-changeset 參數。 | 使用 --fail-on-empty-changeset 參數。 |
| [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 將AWS\$1ENDPOINT\$1URL\$1S3環境變數或--endpoint-url命令列選項設定為 us-east-1 [區域 URL](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)。 | 使用--region aws-global命令列選項。 |
| [已移除 `ecr get-login` 並替換為 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | (1.17.10 或更新版本） 使用 並將輸出[已移除 `ecr get-login` 並替換為 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login)輸送到 docker 命令。 | 不適用。 無法在第 2 版中保留第 1 版行為。 |
| [AWS CLI 外掛程式的第 2 版支援正在變更](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 將 [cli\$1legacy\$1plugin\$1path](https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#plugins) 設定為組態檔案的 [plugins]區段。測試第 2 版中的外掛程式、鎖定第 2 版，以及在每次升級時測試您的外掛程式。 |
| [已移除隱藏別名支援](cliv2-migration-changes.md#cliv2-migration-aliases) | 從已淘汰的隱藏別名切換到[已移除隱藏別名支援](cliv2-migration-changes.md#cliv2-migration-aliases)適用於所有版本的 。 | 不適用。 無法在第 2 版中保留第 1 版行為。 |
| [不支援 `api_versions` 組態檔案設定](cliv2-migration-changes.md#cliv2-migration-api-versions) | 將舊版 API 的用量遷移至最新的 API 版本，並從組態設定中移除 [api\$1versions](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-api_versions)。 | 不適用。 無法在第 2 版中保留第 1 版行為。 |
| [AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求](cliv2-migration-changes.md#cliv2-migration-sigv4) | 指定第 4 版的簽章版本 （請參閱[在請求身分驗證中指定簽章版本）](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html)。 | 不適用。 無法在第 2 版中保留第 1 版行為。 |
| [AWS CLI 第 2 版與分頁參數更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 將輸入 JSON 參數中的分頁參數移至命令本身。 | 從輸入 JSON 參數中移除分頁參數。 |
| [AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](cliv2-migration-changes.md#cliv2-migration-return-codes) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 不適用。 無法在第 2 版中保留第 1 版行為。 |
## 限制
我們強烈建議客戶檢閱我們的 [中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。
### 不支援的中斷變更偵測
升級偵錯模式功能支援每個重大變更，但 除外[AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](cliv2-migration-changes.md#cliv2-migration-return-codes)。此模式無法考慮如何使用下游 CLI AWS 傳回的錯誤代碼。
### 條件式中斷變更偵測
偵測 [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) 是偵測取決於 AWS 帳戶狀態的唯一情況，如果稍後更新帳戶資源，則可能會有重大變更。如果來自 服務的 API 回應中未包含時間戳記，則不會對此重大變更進行任何偵測。
如果您依賴 CLI AWS 命令傳回的時間戳記格式，且尚未將 AWS CLI 設定為使用 ISO 8601，請採取額外的預防措施，以確保您的時間戳記處理不會在升級至第 2 版後中斷。
### 無法解決的中斷變更偵測
升級偵錯模式的某些警告輸出無法透過修改命令或環境來解決。下列情況下，只要您使用對應的功能，系統一律會透過升級偵錯模式輸出警告：
+ [AWS CLI 外掛程式的第 2 版支援正在變更](cliv2-migration-changes.md#cliv2-migration-profile-plugins) - 如果您倚賴[組態檔案中](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)的外掛程式，升級偵錯模式一律會輸出無法解析的警告。此模式無法保證您的任何外掛程式是否可在 CLI AWS 第 2 版中運作。
+ [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - 如果 `aws s3` 用來執行bucket-to-bucket Amazon S3 複製，則升級偵錯模式一律會輸出無法解決的警告。
### 錯誤偵測
升級偵錯模式的警告輸出不保證升級到 AWS CLI v2 後將面臨重大變更。以下是即使 CLI v2 AWS 中沒有重大變更，仍會透過升級偵錯模式輸出警告的情況：
+ [已新增環境變數以設定文字檔案編碼](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) - 如果指定 `PYTHONUTF8`或 `PYTHONIOENCODING`環境變數來設定文字檔案編碼，且指定的編碼已符合安裝的區域設定，則警告可能是錯誤偵測，因為偵錯模式不會檢查編碼是否符合安裝的區域設定。
+ [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - 如果 `aws s3` 用來執行bucket-to-bucket體 Amazon S3 複製，而且由於來源物件低於分段[閾值大小](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#multipart-threshold)，則不會輸出假偵測。
+ [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) - 如果 cli\$1timestamp\$1format 組態設定為有線 （預設），服務會傳回 ISO 8601 格式的時間戳記。
+ [改善未造成任何變更的 CloudFormation 部署處理](cliv2-migration-changes.md#cliv2-migration-cfn) - 如果 `--fail-on-empty-changeset`旗標與 `aws cloudformation deploy`命令搭配使用，且產生的變更集為空，則會輸出 false 偵測。此外，如果變更集不是空`--no-fail-on-empty-changeset`的，而且未使用，則會輸出 false 偵測。
+ [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) - 如果 `aws s3`或 `aws s3api` 用於執行 Amazon S3 操作，且區域設定為 `us-east-1`，且`s3.us_east_1_regional_endpoint`組態未設定為區域性，且全域 Amazon S3 端點因[端點組態設定](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-endpoints.html#endpoints-precedence)而用於請求，則警告可能是錯誤偵測，因為偵錯模式不會檢查設定的端點設定。
## 設定升級偵錯模式
您可以使用下列方法啟用或停用升級偵錯模式，依優先順序列出：
+ 命令列選項會啟用或停用單一命令的升級偵錯模式。使用 [--v2-debug](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-options.html#cli-configure-options-v2-debug) 來使用升級偵錯模式。
+ 環境變數使用 [AWS\$1CLI\$1UPGRADE\$1DEBUG\$1MODE](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-envvars.html#envvars-list-aws_cli_upgrade_debug_mode) 變數。