HelloWorld ARM 模板教程

本教程直接带你动手写一个最简 HelloWorld ARM 模板并完成本地验证与 Azure 部署；我会解释模板的必备字段（schema、contentVersion、parameters、variables、resources、outputs）、常用表达式与函数、如何用 Azure CLI 或 PowerShell 发布，以及调试与复用的技巧。过程中穿插示例 JSON、命令行示例和常见错误解析，目的是让你既能读懂别人的模板，也能独立编写、校验和维护自己的 ARM 模板，快速上手并在真实项目中应用。

先说为什么要学 ARM 模板（用生活化比喻）

把基础设施写成代码，就像把家里的装修清单写成一张详尽的购物单：你能重复使用、版本控制，还能让别人照单买同样的东西。ARM（Azure Resource Manager）模板就是这张购物单的格式，它是 JSON 文件，声明你要哪些资源、它们之间怎么关联以及部署后的输出。

ARM 模板的基本结构（像拼积木一样）

从结构上看，ARM 模板就是一套固定的积木块，主要部分包括：

• schema：指向模板规范的版本（告诉 Azure 如何解释这个 JSON）。
• contentVersion：模板自身的版本号，方便管理。
• parameters：外部传入的可配置项，相当于可调节的按钮。
• variables：模板内部复用或计算出来的中间值，便于减少重复。
• resources：要创建或更新的 Azure 资源清单，是核心积木。
• outputs：部署完成后要返回的信息，比如 URL、资源 ID 等。

举个最简单的“HelloWorld”模板骨架

下面这个模板只是骨架，实际示例后面会给完整可运行的版本：

{
  "$schema": "...",
  "contentVersion": "1.0.0.0",
  "parameters": { },
  "variables": { },
  "resources": [ ],
  "outputs": { }
}

逐项详解：参数、变量、资源与表达式

Parameters（参数）

参数让模板更通用。可以定义类型（string、int、bool、object、array）、默认值、允许的取值（allowedValues）以及描述。部署时可以通过命令行或参数文件传入。

• 优点：同一个模板能用于不同环境（开发/测试/生产）。
• 建议：敏感信息使用 Key Vault 或 SecureString，但优先用 Key Vault 引用，不要把密码明文放在模板里。

Variables（变量）

变量用于拼接字符串、复用复杂表达式或减少重复。如果有多个资源共享相同计算逻辑，把它放到 variables 更清晰。

Resources（资源）

资源数组里每一项都有 type、apiVersion、name、location、properties 等字段。资源可以有依赖关系（dependsOn），Azure 会依据依赖关系顺序创建。

Expressions & Functions（表达式与函数）

ARM 模板内置很多函数，例如 concat、parameters、variables、resourceId、uniqueString 等，常用于动态生成名称或引用已有资源。

完整示例：部署一个最小可运行的 Storage Account（HelloWorld）

这是一个可以直接用来练手的模板，会在指定资源组中创建一个 Storage Account。注意：Storage Account 名称必须全小写且全局唯一。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[toLower(concat('hw', uniqueString(resourceGroup().id)))]",
      "metadata": {
        "description": "Storage account name (lowercase, globally unique)."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "skuName": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": ["Standard_LRS","Standard_GRS","Standard_RAGRS"],
      "metadata": { "description": "SKU for storage account." }
    }
  },
  "variables": {
    "storageKind": "StorageV2"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": { "name": "[parameters('skuName')]" },
      "kind": "[variables('storageKind')]",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[parameters('storageAccountName')]"
    },
    "storageAccountResourceId": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]"
    }
  }
}

如何本地验证模板（避免傻瓜式部署失败）

在部署前，务必先验证模板语法与参数。两种常见方式：

• Azure CLI：az deployment group validate –resource-group rgName –template-file template.json –parameters @params.json
• ARM TTK（测试工具包）：用于静态检查模板设计规范（可选）。

用 Azure CLI 或 PowerShell 部署

推荐用 Azure CLI，因为命令统一且跨平台。示例：

• 登录：az login
• 选择订阅（可选）：az account set –subscription “SUB_ID”
• 部署到资源组：az deployment group create –resource-group MyRg –template-file template.json –parameters @params.json

命令汇总表

调试与常见错误（实战贴士）

• 命名规则：很多资源对 name 有特殊限制（长度、小写、字符集），出错多因不满足命名规则。
• API 版本：资源的 apiVersion 必须支持你要设置的属性，遇到“不可识别的属性”通常是版本问题。
• 依赖关系：当资源引用另一个资源的输出但没有明确 dependsOn，可能出现并发创建问题。
• 配额与权限：订阅或角色限制（如没有创建资源权限）会导致部署失败，检查错误里返回的 HTTP 状态和提示。

进阶主题：模块化、嵌套模板与条件部署

当模板变大时，把公共部分拆成可复用的“linked”或“nested”模板是常见做法。通过 templateLink 或使用部署资源（type 为 Microsoft.Resources/deployments）来包含子模板。此外，使用条件（condition 字段）可以按需创建资源，variables 中配合 copy 可以做循环创建。

最佳实践速查（像记清单一样方便）

• 把敏感数据放 Key Vault 或由 CI/CD 提供，避免明文参数。
• 对常用模板做版本控制，并在 template metadata 写上用途与兼容的 API 版本。
• 写充足的 outputs，CI/CD 可以直接读取扩展信息。
• 每次改动先在测试订阅或资源组验证，再在生产执行。

常见场景与快速参考

几个你会遇到的场景和解决思路：

• 需要全局唯一名称：使用 uniqueString() 混合订阅或资源组 ID。
• 想复用同一套配置到多个环境：用参数文件（params）区分环境值。
• 需要等待外部资源完成：用 dependsOn 或在输出中查看子部署状态。

补充资源（建议读物与工具）

可以参考的官方与社区资料包括 Azure 官方 ARM 模板文档、ARM TTK、以及社区博客和 GitHub 上的模板示例库。看多了别人怎么写，就不会再被陌生的表达式吓到。

好啦，差不多就是这些按部就班能让你从“看不懂模板”到“能写、能部署、能调试”这条路上稳步前进的要点。你可能会在第一次写 name、apiVersion 或参数传递的时候卡壳——那很正常，遇到报错信息多读两遍并验证 API 版本，通常就能自我修复。接下来不妨把上面的示例模板拷贝到本地，跑一次 validate，然后 deploy，边做边学，记得把常见错误记下来，下次就快多了。