故障排除 Azure 开发者命令行工具

本文提供了使用 Azure 开发人员 CLI（azd）时可能出现的常见问题的解决方案。

获取帮助并提供反馈

如果无法找到本文中要查找的内容，或者想要提供反馈，可以将问题发布到 Azure 开发人员 CLI 讨论。

可以通过在 Azure 开发人员 CLI GitHub 存储库中打开 GitHub 问题来报告错误。

使用--debug开关

如果在使用 azd 时遇到意外问题，请使用 --debug 选项重新运行命令，以启用更多调试和诊断输出。

azd up --debug

还可以将调试输出发送到本地文本文件，以提高可用性。 此方法允许其他监视系统引入调试，在 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中符号链接的版本优先于azd中符号链接的版本。

若要恢复使用 bash 中已在 Cloud Shell 上安装的 azd 版本，请执行以下步骤：

1. 运行 rm ~/bin/azd
2. 运行 rm -rf ~/azd

解决方案

使用另一个主机执行需要 docker 守护程序的任务。 一个选项是使用 docker-machine，如 Cloud Shell 故障排除 文档中所述。

Azure Bicep 命令行接口需求

azd up 和 azd provision 需要 Azure Bicep CLI 的最新发布版本。 可能会收到以下错误消息：“错误：编译 bicep 模板失败：运行 Az PowerShell 模块 bicep 生成失败：退出代码：1，stdout： ，stderr： WARNING：新的 Bicep 版本可用：v0.4.1272。

解决方案

以前，安装和使用azd 需要先安装 Bicep。 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. 转到受影响 GitHub 存储库的 操作选项卡，并查看管道运行的日志文件以获取更多信息。

有关其他资源，请参阅 排查常见的 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 静态 Web 应用时，存在一个已知问题，其中默认 azd up 输出可能会显示操作成功，但实际上未部署更改。 可以通过运行命令azd up并启用--debug标志来诊断此问题。 在输出日志中，可能会看到以下消息：

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

当从 GitHub操作运行azd时，你很可能会遇到此问题。 解决方法是，在生成站点后，复制到 staticwebapp.config.json 生成文件夹中。 可以通过使用预处理或预部署命令钩子来自动化此步骤，这样就可以在 azd 命令工作流的不同阶段执行自定义脚本。

产品团队正在努力解决此问题。

GitHub Actions 错误 - “没有密钥库中访问机密的权限”

在本地和 GitHub Actions 中同时预配资源时共享相同的环境或资源组名称可能会导致来自 Key Vault 服务的错误 Does not have secrets get permission on key vault.. 。 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 二进制文件可能会导致用 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: 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 主机：

使用的是缓存的 Dockerfile，而不是当前的 Dockerfile

在本地开发环境中使用 azd 与 Docker 协作时，Docker 可能会使用Dockerfile的缓存版本，而不是当前版本。 这会导致使用包含不正确信息的容器进行部署。

解决方案

若要配置 Azure 开发人员 CLI 用来生成容器的本地 Docker 安装，需要使用以下环境变量配置 Docker：

DOCKER_BUILDKIT=1
DOCKER_BUILD_ARGS="--no-cache"

可以更改自己的 azd up 设置以包括以下设置：

DOCKER_BUILDKIT=1 DOCKER_BUILD_ARGS="--no-cache" azd up

azd pipeline config 支持

azd pipeline config 在 DevContainers/VS Code 远程容器中尚不支持。

Python 的实时指标支持

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

创建 GitHub 问题以请求帮助

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

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