針對 Azure Developer CLI 進行疑難排解
本文提供使用 Azure 開發人員 CLI （azd） 時可能發生之常見問題的解決方案。
取得說明並提供意見反應
如果您找不到本文中想要尋找的內容，或想要提供意見反應，您可以將問題張貼至 Azure 開發人員 CLI 討論區。
您也可以在 Azure 開發人員 CLI GitHub 存放庫中開啟 GitHub 問題來回報 Bug。
--debug使用 參數
如果您在使用 azd時遇到非預期的問題，請使用 參數重新執行 命令 --debug ，以啟用額外的偵錯和診斷輸出。
azd up --debug
您也可以將偵錯輸出傳送至本機文本檔，以改善可用性。 此方法可讓其他監視系統擷取偵錯資訊，而且在 GitHub 上提出問題時也很有用。
重要
在 GitHub 上提交偵錯記錄檔或將它們儲存至其他診斷系統時，請務必修訂任何敏感性資訊。
azd deploy --debug > "<your-file-path>.txt"
目錄.azure
Azure 開發人員 CLI 假設儲存在 .azure 目錄中的任何目錄都是 Azure 開發人員 CLI 環境。 請勿從已安裝 Azure CLI 的使用者主目錄執行 Azure 開發人員 CLI 命令。
未登入 Azure 或在 Visual Studio 中過期的令牌
在 Visual Studio 中執行 azd init -t <template-name> 之後，您會收到下列錯誤：「若要存取遠端：此存放庫，您必須重新授權 OAuth 應用程式 Visual Studio」。
解決方案
執行 azd auth login 以重新整理存取令牌。
更新的 Azure 帳戶許可權不會重新整理 azd
根據預設，快 azd 取您的 Azure 認證和許可權。 如果您的 Azure 帳戶已獲指派新的角色和許可權，或新增至其他訂用帳戶，這些變更可能不會立即反映在 中 azd。 若要解決此問題，請註銷，然後使用下列命令重新登入 azd ：
azd auth logout
azd auth login
請遵循 命令中的 azd auth login 提示來完成登入程式，並更新快取的認證。
Cloud Shell 的限制 azd
在 Cloud Shell 中執行 azd 有一些限制：
Cloud Shell 中的 Docker 支援
Cloud Shell 不支援執行 Docker build 或 run 命令，因為 Docker 精靈未執行。 如需詳細資訊，請參閱 Cloud Shell 疑難解答。
Cloud Shell 逾時
Cloud Shell 可能會在長時間部署或其他長時間執行的工作期間逾時。 請確定會話不會變成閑置狀態。 請參閱 Cloud Shell 使用量限制。
Cloud Shell 介面
Cloud Shell 主要是命令行介面，其功能會比 Visual Studio Code 等整合開發環境少。
無法在 Cloud Shell 中聯機到 Docker 精靈
Cloud Shell 會使用容器來裝載殼層環境，因此不允許需要執行 Docker 精靈的工作。
在 Cloud Shell 中安裝不同版本的 azd
在某些情況下，可能需要安裝的版本與 Cloud Shell 中使用的版本不同 azd 。 若要在bash中執行這項操作：
- 執行
mkdir -p ~/bin以確保~/bin資料夾存在 - 執行
mkdir -p ~/azd以確保本機~/azd資料夾存在 - 執行
curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version>（<version>預設為stable，但也可以指定類似1.0.0的特定發行版本）。
安裝之後，中的~/bin符號連結版本azd會優先於 中/usr/local/bin以符號方式連結的版本azd。
若要還原為使用 bash 中已在 Cloud Shell 上安裝的 azd 版本：
rm ~/bin/azd執行rm -rf ~/azd執行
解決方案
使用另一個主機來執行需要 Docker 精靈的工作。 其中一個選項是使用 docker-machine，如 Cloud Shell 疑難解答檔中所述。
Azure Bicep CLI 需求
azd up 和 azd provision 需要最新版的 Azure Bicep CLI。 您可能會收到下列錯誤訊息：「錯誤：無法編譯 bicep 範本：執行 Az PowerShell 模組 bicep 組建失敗：結束代碼：1，stdout： ，stderr： WARNING： 有新的 Bicep 版本可用：v0.4.1272。」
解決方案
先前，Bicep 是安裝和使用 azd 的 preqrequisite。 azd 現在會自動在本機 azd 範圍內安裝 Bicep（並非全域），現在應該解決此問題。 不過，如果您想要使用不同的版本，您可以設定環境變數： AZD_BICEP_TOOL_PATH 指向您需要的版本位置。
azd up 或 azd provision 失敗
有時候事情可能會與或 azd provision相azd up去不及。 常見的錯誤包括：
- 「無法在 Azure 區域中布建特定資源，因為區域容量不足。
- 「相關資源提供者不存在於該區域中。」
疑難解答步驟可能會因根本原因而有所不同。
解決方案
前往 Azure 入口網站。
找出您的資源群組，也就是 rg-your-environment-name<>。
選取 [部署] 以取得詳細資訊。
確認您已指定與環境名稱相同的環境名稱。
移至
https://github.com/<your repo>/actions，然後參考管線執行中的記錄檔以取得詳細資訊。
如需其他資源，請參閱 針對常見的 Azure 部署錯誤進行疑難解答 - Azure Resource Manager。
azd init 需要 sudo
在之前 azd version = azure-dev-cli_0.2.0-beta.1， azd 會建立 .azd 具有 drw-r--r-- 存取權的資料夾。
這會導致問題，如同在任何 Linux 設定上使用這個或先前版本 （WSL、ssh-remote、devcontainer 等） 已提供 .azd 具有只讀模式的資料夾。
解決方案
手動刪除已提供
.azd的資料夾：rm -r ~/.azdazd執行azd init以使用正確的存取層級再次建立資料夾。
azd monitor 用於開發容器
azd monitor 如果您使用開發容器作為開發環境，則目前不支援。
無法在 Codespaces 環境中進行驗證
如果您在 Codespaces 中遇到驗證問題，請確定 Dockerfile 範本包含 sudo apt-get update && sudo apt-get install xdg-utils 命令。 此命令 xdg-utils 會開啟瀏覽器索引標籤，可讓您登入。
靜態 Web Apps 儘管成功訊息仍無法部署
部署至 Azure Static Web Apps 時，已知存在問題，其中默認 azd up 輸出可能會指出動作成功，但並未實際部署變更。 您可以執行已啟用 旗標的--debug命令來azd up診斷此問題。 在輸出記錄中，您可能會看到下列訊息：
Preparing deployment. Please wait...
An unknown exception has occurred
從 GitHub 動作執行時 azd ，您很可能會遇到此問題。 因應措施是在建置網站之後，複製到 staticwebapp.config.json 組建資料夾。 您可以使用 prepackage 或 predeploy 命令攔截將此步驟自動化，這可讓您在 azd 命令工作流程中的各種點執行自定義腳本。
產品小組正努力解決此問題。
GitHub Actions 錯誤 - 「沒有金鑰保存庫的秘密取得許可權」
在本機和 GitHub Actions 中布建資源時共用相同的環境或資源組名，可能會從 金鑰保存庫 服務產生錯誤Does not have secrets get permission on key vault..。 金鑰保存庫 不支援透過 Bicep 的累加許可權更新，這實際上表示 GitHub Actions 工作流程會覆寫本機使用者的存取原則許可權。
此問題的建議解決方案是針對本機開發和 GitHub Actions 工作流程使用不同的環境名稱。 深入瞭解如何在常見問題頁面上搭配azd env命令使用多個環境。
以文字為基礎的瀏覽器支援
目前不支援 azd monitor以文字為基礎的瀏覽器。
azd pipeline config 在 Windows 上使用 AzDo for Java 範本
在 Windows 上使用 AzDo for Java 範本執行 azd pipeline config 時，可能會遇到失敗。 例如，您已：
在 Windows 上執行下列命令：
azd init --template Azure-Samples/todo-java-mongo azd pipeline config收到下列錯誤：
解決方案
這是已知的問題。 當我們解決此問題時，請嘗試下列命令：
git update-index --chmod=+x src/api/mvnw && git commit -m "Fix executable bit permissions" && git push
failed packaging service 'api': failed invoking action 'package', failed to run NPM script build, signal: segmentation fault 在 Apple Silicon 升級 azd 後失敗 （M1/M2）
在某些情況下，從 x86_64 版升級至 ARM64 二進位檔，可能會導致使用 x86_64 版azdazd建置的範本失敗。 這是因為範本使用的版本 v8-compile-cache 可能會嘗試將 x86_64 底下建置的位元組程式代碼載入ARM64進程。
若要修正此問題，請升級 v8-compile-cache 受影響專案中的套件：
- 將目錄變更為失敗的服務（
src/api在 案例中為failed packaging service 'api'） npm upgrade v8-compile-cache執行- 將目錄變更為存放庫的根目錄，然後再次執行
azd命令（例如azd package或azd up）
azd pipeline config 因條件式存取原則而失敗
執行 azd pipeline config時，您可能會收到如下的錯誤：
ERROR: failed to create or update service principal: failed retrieving application list, failed executing request: http call(https://login.microsoftonline.com/common/oauth2/v2.0/token)(POST) error: reply status code was 400:
{"error":"invalid_grant","error_description":"AADSTS50005: User tried to log in to a device from a platform (Unknown) that's currently not supported through Conditional Access policy. Supported device platforms are: iOS, Android, Mac, and Windows flavors.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd"}
此錯誤與您的 Microsoft Entra 租使用者啟用條件式存取原則有關。 特定原則會要求您登入支援的裝置平臺。
您也可能因為使用裝置程式代碼機制登入而收到此錯誤，這可防止 Microsoft Entra ID 正確偵測您的裝置平臺。
解決方案
若要設定工作流程，您必須授與 GitHub 權限，以代表您部署至 Azure。 建立儲存在名為 AZURE_CREDENTIALS之 GitHub 秘密中的 Azure 服務主體，以授權 GitHub。 選取您的 Codespace 主機以取得步驟：
