Azure 部署预检验证

本技能在执行前验证 Bicep 部署，同时支持 Azure CLI (az) 和 Azure Developer CLI (azd) 工作流。

何时使用此技能

• 在部署基础设施到 Azure 之前
• 在准备或审查 Bicep 文件时
• 预览部署将产生哪些更改
• 验证权限是否足够进行部署
• 在运行 azd up、azd provision 或 az deployment 命令之前

验证流程

按顺序执行以下步骤。即使前一步失败，也继续执行下一步——在最终报告中捕获所有问题。

步骤 1：检测项目类型

通过检查项目指示符来确定部署工作流：

1. 检查是否为 azd 项目：在项目根目录中查找 azure.yaml
   • 如果找到 → 使用 azd 工作流
   • 如果未找到 → 使用 az CLI 工作流
2. 定位 Bicep 文件：查找所有要验证的 .bicep 文件
   • 对于 azd 项目：首先检查 infra/ 目录，然后检查项目根目录
   • 对于独立项目：使用用户指定的文件，或在常见位置搜索（infra/、deploy/、项目根目录）
3. 自动检测参数文件：对于每个 Bicep 文件，查找匹配的参数文件：
   • <filename>.bicepparam（Bicep 参数 – 首选）
   • <filename>.parameters.json（JSON 参数）
   • parameters.json 或同一目录下的 parameters/<env>.json

步骤 2：验证 Bicep 语法

在尝试部署验证之前，运行 Bicep CLI 检查模板语法：

bicep build <bicep-file> --stdout

需要捕获的内容：

• 包含行/列号的语法错误
• 警告消息
• 构建成功/失败状态

如果未安装 Bicep CLI：

• 在报告中注明此问题
• 继续执行步骤 3（Azure 会在 what-if 期间验证语法）

步骤 3：运行预检验证

根据步骤 1 中检测到的项目类型选择适当的验证。

对于 azd 项目（存在 azure.yaml）

使用 azd provision --preview 验证部署：

azd provision --preview

如果指定了环境或存在多个环境：

azd provision --preview --environment <env-name>

对于独立 Bicep（无 azure.yaml）

根据 Bicep 文件的 targetScope 声明确定部署范围：

首先使用 Provider 验证级别运行：

# 资源组范围（最常见）
az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# 订阅范围
az deployment sub what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# 管理组范围
az deployment mg what-if \
  --location <location> \
  --management-group-id <mg-id> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# 租户范围
az deployment tenant what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

回退策略：

如果 --validation-level Provider 因权限错误（RBAC）而失败，请使用 ProviderNoRbac 重试：

az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --validation-level ProviderNoRbac

在报告中注明回退情况——用户可能缺少完整的部署权限。

步骤 4：捕获 What-If 结果

解析 what-if 输出，对资源更改进行分类：

对于修改的资源，捕获特定的属性更改。

步骤 5：生成报告

在项目根目录中创建一个 Markdown 报告文件，命名为：

• preflight-report.md

使用 references/REPORT-TEMPLATE.md 中的模板结构。

报告部分：

1. 摘要 – 总体状态、时间戳、已验证的文件、目标范围
2. 执行的工具 – 运行的命令、版本、使用的验证级别
3. 问题 – 所有带有严重性和修复建议的错误和警告
4. What-If 结果 – 将创建/修改/删除/不变的资源
5. 建议 – 可操作的下一个步骤

所需信息

在运行验证之前，收集：

如果缺少必要信息，请在继续之前提示用户。

错误处理

有关详细的错误处理指南，请参阅 references/ERROR-HANDLING.md。

关键原则：即使发生错误，也要继续验证。在最终报告中捕获所有问题。

工具要求

本技能使用以下工具：

• Azure CLI (az) – 推荐使用 2.76.0+ 版本以获得 --validation-level 支持
• Azure Developer CLI (azd) – 用于包含 azure.yaml 的项目
• Bicep CLI (bicep) – 用于语法验证
• Azure MCP 工具 – 用于文档查找和最佳实践

在开始前检查工具可用性：

az --version
azd version
bicep --version

示例工作流

1. 用户：”在我运行之前，验证我的 Bicep 部署”
2. 代理检测到 azure.yaml → azd 项目
3. 代理找到 infra/main.bicep 和 infra/main.bicepparam
4. 代理运行 bicep build infra/main.bicep --stdout
5. 代理运行 azd provision --preview
6. 代理在项目根目录生成 preflight-report.md
7. 代理向用户总结发现

参考文档

• 验证命令参考
• 报告模板
• 错误处理指南