排查 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 使用容器托管 shell 环境，因此不允许运行 Docker 守护程序的任务。

在 Cloud Shell 中安装不同版本的 azd

在某些情况下，可能需要安装与 Cloud Shell 中使用的版本不同的版本 azd 。 若要在 bash 中执行此操作：

1. 运行 mkdir -p ~/bin 以确保 ~/bin 文件夹存在
2. 运行 mkdir -p ~/azd 以确保存在本地 ~/azd 文件夹
3. 运行 curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> （<version> 默认为 stable ，但也可以指定特定的已发布版本 1.0.0 ）。

安装后， azd 符号链接的版本 ~/bin 将优先于 azd 符号链接的版本 /usr/local/bin。

若要还原使用 bash 中已在 Cloud Shell 上安装的版本azd：

1. rm ~/bin/azd运行
2. 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 先决条件。 azd 现在，在本地范围内（不是全局）自动安装 Bicep azd ，现在应解决此问题。 但是，如果要使用其他版本，可以设置环境变量： AZD_BICEP_TOOL_PATH 指向所需的版本位置。

azd up 或 azd provision 失败

有时事情可能会与 azd up 或 azd provision。 常见错误包括：

• “无法预配 Azure 区域中的某些资源，因为该区域容量不足。
• “该区域中不存在相关的资源提供程序。

故障排除步骤可能会有所不同，具体取决于根本原因。

解决方案

1. 转到 Azure 门户。

2. 找到资源组，即 rg-your-environment-name<>。

3. 选择“部署”以获取详细信息。

4. 验证是否已指定与环境名称相同的环境名称。

5. 转到 https://github.com/<your repo>/actions，然后参考管道运行中的日志文件了解详细信息。

有关其他资源，请参阅排查常见的 Azure 部署错误 - Azure 资源管理器。

azd init 需要 sudo

之前 azd version = azure-dev-cli_0.2.0-beta.1， azd 将创建一个 .azd 具有 drw-r--r-- 访问权限的文件夹。

这将导致问题，就像在任何 Linux 设置（WSL、ssh-remote、devcontainer 等）上使用此版本或任何以前的版本一样，它已提供 .azd 具有只读模式的文件夹。

解决方案

1. 手动删除已提供 .azd 的文件夹：

   rm -r ~/.azd
   

2. 运行 azd init 以 azd 使用正确的访问级别再次创建文件夹。

azd monitor 用于开发容器

azd monitor 如果使用开发容器作为开发环境，则目前不受支持。

无法在 Codespaces 环境中进行身份验证

如果在 Codespaces 中遇到身份验证问题，请确保模板 Dockerfile 包含 sudo apt-get update && sudo apt-get install xdg-utils 命令。 该 xdg-utils 命令将打开一个允许你登录的浏览器选项卡。

尽管成功消息，静态Web 应用部署失败

部署到 Azure Static Web 应用时，存在一个已知问题，其中默认azd up输出可能指出操作成功，但实际上未部署更改。 可以通过运行启用了标志的azd up--debug命令来诊断此问题。 在输出日志中，可能会看到以下消息：

Preparing deployment. Please wait...
An unknown exception has occurred

从 GitHub 操作运行时 azd ，很可能遇到此问题。 解决方法是，在生成站点后，复制到 staticwebapp.config.json 生成文件夹中。 可以使用预包或 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 ，可能会遇到故障。 例如，你已：

1. 在 Windows 上运行以下内容：

   azd init --template Azure-Samples/todo-java-mongo
   azd pipeline config
   

2. 收到以下错误：

   

解决方案

这是已知问题。 在解决此问题时，请尝试以下命令：

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 版本的 azd ARM64 二进制文件升级到 ARM64 二进制文件可能会导致使用 x86_64 版本的模板 azd失败。 这是因为模板使用一个版本 v8-compile-cache ，其中可能会尝试将x86_64下生成的字节码加载到 ARM64 进程中。

若要解决此问题，请升级 v8-compile-cache 受影响项目中的包：

1. 将目录更改为失败的服务（src/api 在这种情况下 failed packaging service 'api'）
2. npm upgrade v8-compile-cache运行
3. 将目录更改为存储库的根目录并再次运行 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: be3438c1-42fc-4c37-96d8-0e723ac54f01\r\nCorrelation ID: f535565f-9f3c-4014-ad65-403f514bf892\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"be3438c1-42fc-4c37-96d8-0e723ac54f01","correlation_id":"f535565f-9f3c-4014-ad65-403f514bf892"}

此错误与条件访问策略的 Microsoft Entra 租户启用相关。 特定策略要求登录到受支持的设备平台。

你也可能因为使用设备代码机制登录而收到此错误，这可以防止 Microsoft Entra ID 正确检测设备平台。

解决方案

若要配置工作流，需要授予 GitHub 代表你部署到 Azure 的权限。 通过创建存储在名为 AZURE_CREDENTIALS 的 GitHub 机密中的 Azure 服务主体来授权 GitHub。 为步骤选择 Codespace 主机：

浏览器

1. 请确保按照错误消息在列出的设备上运行。

2. 重新运行 azd auth login 并追加了标志 --use-device-code=false ：

   azd auth login --use-device-code=false
   

3. 登录后可能会收到错误消息 localhost refused to connect 。 如果已完成这两项：

   1. 复制 URL。
   2. 在新 Codespaces 终端中运行 curl '<pasted url>' （引用中的 URL）。

   在原始终端中，登录名现在应成功。

4. 登录后，重新运行 azd pipeline config。

VS Code

1. 请确保按照错误消息在列出的设备上运行。

2. 重新运行 azd auth login 并追加了标志 --use-device-code=false ：

   azd auth login --use-device-code=false
   

3. 登录后，重新运行 azd pipeline config。

azd pipeline config 支持

azd pipeline configDevContainers/VS Code 远程容器目前不受支持。

Python 的实时指标支持

Python 应用目前不支持实时指标（azd monitor --live）。 有关详细信息，请参阅实时指标：以 1 秒的延迟进行监视和诊断。

创建 GitHub 问题以请求帮助

Azure 开发人员 CLI 和 Azure 开发人员 CLI Visual Studio Code 扩展 使用 GitHub 问题 来跟踪 bug 和功能请求。 请在提交新问题之前搜索 现有问题 ，以避免重复。

有关使用此项目的帮助和问题，请查看我们的 Wiki ，了解如何使用 Azure 开发人员 CLI 和我们的 参与文档 （如果想要参与）。