你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
快速入门：排查 Bicep 文件部署问题
本快速入门介绍如何排查 Bicep 文件部署错误。 你将创建一个包含错误的文件，并了解如何修复这些错误。
有三种类型的错误与部署相关：
- 验证错误发生在部署开始之前，由文件中的语法错误造成。 像 Visual Studio Code 这样的代码编辑器可以识别这些错误。
- 当运行部署命令但未部署资源时，将发生预检验证错误。 这些错误是部署未开始的情况下出现的。 例如，如果某个参数值不正确，则会在预检验证中发现错误。
- 部署错误发生在部署过程中，只能通过评估 Azure 环境中的部署进度来发现。
所有类型的错误都会返回用于排查部署问题的错误代码。 验证错误和预检错误会显示在活动日志中，但不会显示在部署历史记录中。 存在语法错误的 Bicep 文件不会编译为 JSON，也不会显示在活动日志中。
先决条件
若要完成本快速入门，需要准备好以下各项：
- 如果还没有 Azure 订阅，可以在开始前创建一个免费帐户。
- 装有最新 Bicep 扩展的 Visual Studio Code。
- 最新版本的 Azure PowerShell 或 Azure CLI。
创建包含错误的 Bicep 文件
复制以下 Bicep 文件并将其保存在本地。 你将使用此文件来排查验证错误、预检错误和部署错误。 本快速入门假设该文件命名为 troubleshoot.bicep，但你可以指定任意名称。
@description('SKU for the storage account')
@allowed([
'Standard_LRS'
'Standard_GRS'
'Standard_ZRS'
'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'
@description('Prefix for storage name.')
param prefixName string
var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'
resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
name: storageAccountName
location: resourceGroup().location
sku: {
name: storageAccountType
}
kind: 'StorageV2'
properties: {}
}
resource existingVNet 'Microsoft.Network/virtualNetworks@2021-03-01' existing = {
name: 'doesnotexist'
}
output storageAccountName string = storageAccountName
output vnetResult object = existingVNet
修复验证错误
在 Visual Studio Code 中打开该文件。 你将发现，Visual Studio Code 识别到了一个语法错误。 第一个参数声明标有红色波浪线，以指示错误。
标有错误的行是：
@allowed([
'Standard_LRS'
'Standard_GRS'
'Standard_ZRS'
'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'
将鼠标悬停在 parameter 上时，会看到一条错误消息。
该消息指出：“无法识别此声明类型。请指定参数、变量、资源或输出声明。”如果你尝试部署此文件，部署命令将返回相同的错误消息。
如果查看参数声明的文档，你将看到关键字实际上是 param。 更改该语法后，验证错误即会消失。
@allowed 修饰器也标记为错误，但该错误也可以通过更改参数声明来解决。 修饰器之所以标记为错误，是因为需要在其后添加一个参数声明。 如果该声明不正确，则此条件不会成立。
已修复的行是：
param storageAccountType string = 'Standard_LRS'
修复预检错误
修复验证错误后，接下来请部署该文件。 但是，请提供一个错误的参数值以查看预检错误。
az group create --name troubleshootRG --location westus
az deployment group create \
--resource-group troubleshootRG \
--template-file troubleshoot.bicep \
--parameters prefixName=longNamewith!!Charactersthatarenotallowed
Azure 资源管理器确定存储帐户的名称包含不允许的字符。 它不会尝试进行部署。
你将看到一条错误消息，指出预检验证失败。 你还会收到一条消息，指出存储帐户名称长度必须为 3 到 24 个字符，并且只能使用数字和小写字母。 提供的前缀不符合该要求。 有关此错误代码的详细信息，请参阅解决存储帐户名称错误。
由于该错误是在预检中捕获的，因此历史记录中不会显示部署。
但是，活动日志中显示了失败的部署。
可以打开日志条目的详细信息以查看错误消息。
修复部署错误
再次部署该文件，并为名称前缀参数提供允许的值。
az group create --name troubleshootRG --location westus
az deployment group create \
--resource-group troubleshootRG \
--template-file troubleshoot.bicep \
--parameters prefixName=stg
部署将会开始，但会失败并显示一条消息，指出未找到虚拟网络。 通常，可以通过更改对资源的引用来修复此错误。 在本快速入门中，你将删除引用。 有关此错误代码的详细信息，请参阅解决找不到资源错误。
请注意门户中的历史记录中显示了部署。
可以打开部署历史记录中的条目以获取有关错误的详细信息。 活动日志中也包含了该错误。
Bicep 文件尝试引用资源组中不存在的虚拟网络。 删除对现有虚拟网络的引用即可修复该错误。
@description('SKU for the storage account')
@allowed([
'Standard_LRS'
'Standard_GRS'
'Standard_ZRS'
'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'
@description('Prefix for storage name.')
param prefixName string
var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'
resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
name: storageAccountName
location: resourceGroup().location
sku: {
name: storageAccountType
}
kind: 'StorageV2'
properties: {}
}
output storageAccountName string = storageAccountName
可以部署该 Bicep 文件而不会出现任何错误。
清理资源
不再需要 Azure 资源时，请删除资源组。 可以从 Cloud Shell 或门户中删除资源组。
az group delete --name troubleshootRG
若要从门户中删除资源组，请执行以下步骤：
- 在 Azure 门户中的搜索框内输入“资源组”。
- 在“按名称筛选”字段中输入资源组名称。
- 选择资源组名称。
- 选择“删除资源组”。
- 若要确认删除，请输入资源组名称，然后选择“删除”。
后续步骤
在本快速入门中，你已了解如何排查 Bicep 文件部署错误。