企业官网建设流程全解析

Azure Developer CLI 官方参考知识体系：以 Microsoft Learn 为事实源的 azd 项目开发与排障指南

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

本指南以 awesome-copilot 仓库中 azure-developer-cli 技能 的官方参考资料索引（references/official-docs.md）为骨架，系统梳理 Azure Developer CLI（azd）的权威知识领域：核心概念与项目结构、基础设施即代码（Bicep/Terraform）、环境与密钥管理、钩子/流水线与运维，以及 GitHub Copilot Agent 技能格式。读者读完本指南后，将掌握一套"按需查阅官方文档、以仓库内参考手册落地"的 azd 项目设计、审查、迁移与排障方法论，并能在不确定字段、命令参数或预览特性行为时，快速定位正确的权威依据。

为什么需要一份"官方参考索引"

Azure Developer CLI 是快速演进的工具，其 Schema、命令参数、Host 类型、预览状态与认证行为经常调整。azd项目一旦基于过时记忆或过气博客编写，很容易在生产环境暴露出字段不兼容、命令行为漂移等问题。

因此，本技能在 references/official-docs.md 中确立了一条铁律：

Use Microsoft Learn as the source of truth for AZD behavior and schema details.

即：以 Microsoft Learn 作为 azd 行为与 Schema 细节的事实源。该参考索引于 2026-08-05 经过复核，并将官方资料按五大领域组织：核心概念与结构、基础设施即代码、环境与密钥、钩子/流水线与运维、技能格式。文档末尾的原则进一步要求：当某个字段、命令标志、宿主类型、预览状态或认证行为不确定时，必须查阅对应的最新参考后再修改代码，不要依赖对快速演进的预览特性（preview feature）的背诵式记忆。

这条方法论与技能的整体定位一致：SKILL.md 的 frontmatter（第 1-5 行）即声明该技能用于"依据 Microsoft 当前指导，设计、创建、审查、迁移或排障 azd 项目"，覆盖 azure.yaml、AZD 模板、infra 下的 Bicep/Terraform、环境与密钥、钩子、部署工作流与 azd 托管的 CI/CD。

核心概念与结构：从 azd 概览到 azure.yaml 清单

官方参考的第一组主题回答"azd 是什么、模板怎么来、清单怎么写、一条命令如何贯通部署"：

• Azure Developer CLI 文档与 What is the Azure Developer CLI?：工具定位与整体能力边界。
• Azure Developer CLI 模板概述与如何创建兼容模板：官方模板生态与azd对仓库结构的要求。
• Azure Developer CLI Schema 参考与azure.yamlJSON Schema：清单文件的权威字段定义，是编辑器校验与审查的底层依据。
• azd up工作流详解与全栈部署：一条命令完成打包、预配、部署的组合语义，以及多服务全栈场景下的行为。

仓库内与之对应的是 references/project-structure.md，它给出了 azd 项目推荐布局——根目录一份azure.yaml、infra/存放 IaC 编排入口、src/<service-name>/存放每个可独立部署的服务、scripts/azd/存放钩子脚本，而.azure/是生成的本地环境状态，必须被.gitignore排除。

azure.yaml基线清单直接来自技能自带的可运行示例 examples/azure.yaml：

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json name: sample-app infra: provider: bicep path: ./infra module: main services: api: project: ./src/api language: ts host: appservice web: project: ./src/web dist: dist language: ts host: staticwebapp

要点解读（依据 project-structure.md 的清单核对项）：

• 首行的 Schema 指令为编辑器提供 azure.yaml 的实时校验，这正是官方azure.yamlJSON Schema 在工程中的落地方式。
• name必须小写、以字母数字开头与结尾，仅允许字母数字与连字符。
• infra块的provider（Bicep 为默认）、path（默认./infra）、module（默认main）显式声明时更利于审查；若省略则按默认值推断，所以阅读azure.yaml时切勿先入为主地假设默认路径或默认提供商。
• services中每个条目代表一份可部署的应用代码（而非数据库、Key Vault 等共享资源），服务名应简短、有意义且保持稳定，因为它们参与资源发现与部署。
• metadata.template、requiredVersions、workflows、state.remote等顶层字段各有明确用途：模板分发时标识来源、依赖最低 azd 版本时声明约束、仅当部署顺序确有需要时覆盖工作流、团队共享环境时配置远程状态。

基础设施即代码：Bicep 与 Terraform 的官方口径

官方参考的第二组主题确立 IaC 侧的权威依据：

• Use Terraform as an infrastructure as code tool for Azure Developer CLI：azd 对 Terraform 的集成方式与当前限制。
• Azure Verified Modules：微软验证过的可复用资源模块体系。
• Bicep 文档与 Terraform on Azure 文档：两种 IaC 语言本身的权威资料。

仓库内 references/iac-and-environments.md 给出了与此对应的选型与实践口径：

• Bicep 是 azd 的默认 IaC 提供商，适用于纯 Azure 项目、追求原生资源覆盖与无状态部署模型的团队；Terraform 则适用于仓库已采用 Terraform、已有模块/状态/策略/审查实践，或确有跨云需求的团队。
• Terraform 支持目前被微软官方文档标记为 beta，这是必须向用户明示的约束，不能仅因熟悉而把项目迁到 Terraform。
• Bicep 结构上保持main.bicep为薄编排层，能力按modules/core、modules/data、modules/identity、modules/observability、modules/services拆分；模块版本应锁定并走评审升级，不浮动追踪。

参数流转是 azd 与 IaC 的契约核心。用main.parameters.json将 AZD 环境值映射进 Bicep（iac-and-environments.md）：

{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": { "environmentName": { "value": "${AZURE_ENV_NAME}" }, "location": { "value": "${AZURE_LOCATION}" } } }

入口文件中使用带描述与校验装饰器的参数声明与之呼应：

@description('Stable name of the AZD deployment environment.') @minLength(1) param environmentName string @description('Primary Azure region for this deployment.') param location string

而outputs是预配阶段与后续azd deploy、钩子、流水线之间的契约——例如output SERVICE_API_ENDPOINT_URL string = api.outputs.endpoint，输出名必须稳定，因为服务、钩子、流水线会把它当作环境变量消费。任何秘密值都禁止出现在 IaC 输出中，因为部署输出会被复制进 AZD 环境。

Terraform 侧的关键实践（同样依据 iac-and-environments.md）：

• 在azure.yaml显式设置infra.provider: terraform，并将所有 azd 托管的.tf文件置于配置的 infra 路径下。
• 锁定 Terraform 与 Provider 版本并提交依赖锁文件；.tfstate、计划文件、崩溃日志、Provider 凭据一律不入库。
• Terraform 的 Azure Provider 默认使用 Azure CLI 认证（不经 azd 凭据缓存），推荐单次登录配置：azd config set auth.useAzCliAuth true后执行az login；否则需要同时执行azd auth login与az login。
• 在azd pipeline config或协作部署前配置受保护的远程后端，azd 按官方 Terraform 集成要求从infra/provider.conf.json读取后端设置；远程状态须按机密数据对待，配 RBAC 与网络控制。

环境与密钥：官方环境模型的落地

官方参考的第三组主题覆盖 azd 的多环境模型与密钥处理：

• Azure Developer CLI 环境概述与使用环境：环境是什么、如何创建/选择/管理。
• 环境变量管理：非密钥型配置的存取方式。
• 远程环境支持：团队共享环境状态的官方方案。
• 环境密钥（Environment secrets）：密钥在 azd 环境中的标准用法。

仓库内对应文档 iac-and-environments.md 描述了 azd 的本地状态布局：

.azure/ |-- config.json |-- <environment-name>/ |-- .env |-- config.json

整个.azure目录必须留在源码控制之外。环境命名建议：共享环境用<project>-dev、<project>-test、<project>-prod；个人环境用<alias>-<purpose>；临时环境用<project>-pr-<number>并保证自动化同时负责清理，名称要短到能容纳资源命名限制。

环境管理应使用命令而非手工改文件（同样来自 iac-and-environments.md）：

azd env new <name> azd env list azd env select <name> azd env set <key> <value> azd env get-value <key> azd env unset <key> azd env refresh

在自动化与可能破坏性的操作中，务必显式指定环境：

azd provision -e <environment> --no-prompt azd deploy -e <environment> --no-prompt

密钥方面，官方环境密钥特性对应azd env set-secret <name>，它在 AZD 环境中保存一个 Key Vault 引用而非明文。仓库内 security-cicd-operations.md 给出密钥偏好顺序：托管身份 + 最小权限 RBAC → CI/CD 用工作负载身份联合（OIDC）→ Key Vault 引用 → 仅在无身份方案可用时才使用短时密钥材料。与 Bicep 配合时：输入参数标记@secure()、经main.parameters.json映射 AZD 密钥引用、绝不输出该安全值；同时要注意当前官方文档指出环境密钥与.bicepparam文件不兼容。

团队共享环境时配置state.remote（iac-and-environments.md）：

state: remote: backend: AzureBlobStorage config: accountName: <storage-account-name> containerName: <project-container-name>

需特别区分：AZD 远程状态同步的是.env与 azdconfig.json（环境配置），与Terraform 远程状态（托管基础设施状态）是两回事；一个通过 azd 协作的 Terraform 项目可能同时需要两者，且两份存储都须以最小权限 RBAC 与数据保护设置加以防护。

钩子、流水线与运维：官方扩展点与生命周期

官方参考的第四组主题覆盖 azd 的扩展与运维：

• 用钩子定制 azd 工作流：生命周期各阶段的扩展机制。
• CI/CD 流水线支持与 GitHub Actions 流水线创建：azd 生成与托管流水线的官方路径。
• 高级流水线特性与配置：变量、密钥、审批、环境保护等。
• azd 命令参考与故障排查：权威命令语义与排障方法。

仓库内 security-cicd-operations.md 给出了落地的完整闭环。azd 的标准生命周期是：打包应用制品 → 预配/更新基础设施 → 部署应用制品。azd up是这三步的组合命令，适合日常开发与简单部署；当需要基础设施评审、应用频繁重部署、隔离排障或自定义依赖顺序时，应拆分为azd package、azd provision -e <environment>、azd deploy -e <environment>。

钩子只在默认生命周期无法表达需求时添加，规则包括：优先外部脚本（存放于scripts/azd）、显式声明shell（sh或pwsh）、必要时提供windows与posix双实现、脚本幂等、CI 中非交互、continueOnError保持false（除非仅观测或确实可选）、先azd hooks run <hook-name>独立测试。技能自带的 examples/azure.yaml 第 20-32 行就是标准的双平台钩子模板：

hooks: preprovision: windows: shell: pwsh run: ./scripts/azd/validate.ps1 interactive: false continueOnError: false posix: shell: sh run: ./scripts/azd/validate.sh interactive: false continueOnError: false

CI/CD 侧，azd pipeline config被官方标记为beta，运行前须审查模板自带的流水线定义，确认仓库、组织、环境、订阅与认证模式，并预期其对仓库、身份、变量、密钥、提交、推送与流水线的副作用；pipeline.variables或pipeline.secrets变更后需重跑。GitHub Actions 场景下 azd 默认配置 OIDC/联合凭据，但当前 azd 的 Terraform 流水线流程不支持 OIDC，应明确评估认证取舍，而不是静默回退到长期凭据。

部署前的本地验证（来自 security-cicd-operations.md）：

Bicep: az bicep build --file infra/main.bicep Terraform: terraform fmt -check -recursive terraform init -backend=false terraform validate AZD hooks: azd hooks run <hook-name> Packaging: azd package

故障排查遵循同样的"以事实源为准"思路（security-cicd-operations.md）：先判断失败发生在打包、预配、部署、钩子、认证还是资源发现阶段，重跑最小失败阶段而非整个azd up，核对选中环境与预期的订阅/租户/区域，检查azure.yaml路径与资源发现标签，Azure 状态在别处变更后用azd env refresh同步，Terraform 项目则同时核查 azd/Azure CLI 认证与远程状态，必要时开启调试日志并先脱敏再分享。

技能格式：Agent 侧的知识来源

官方参考的第五组主题面向 GitHub Copilot Agent 技能的编写者：

• 为 GitHub Copilot 添加 Agent 技能（Adding agent skills for GitHub Copilot）：技能的安装与接入方式。
• 关于 Agent 技能（About agent skills）：技能概念、边界与最佳实践。

这两份资料之所以被收入 azd 技能参考，是因为 azure-developer-cli 本身就是一个以 SKILL.md 为入口的 Copilot 技能：其 frontmatter 声明了name（azure-developer-cli）、description（描述适用场景，供模型匹配调用）与license（MIT）。当技能作者或使用该技能的 Agent 需要调整技能行为、字段或参考引用时，应先查阅官方技能格式文档，再决定如何修改 frontmatter、正文与references/下的手册，避免把 azd 行为与技能元数据格式混为一谈。

落地清单：不确定时该查哪份参考

将官方参考索引的方法论转化为可执行的核对动作（文件均为本仓库内路径）：

结尾再次回到 official-docs.md 的核心结论：对于 azd 这样快速演进的工具，正确性来源于"查阅当前官方文档"这一习惯本身。把官方参考索引用作知识地图、把仓库内三份参考手册用作落地细则，就能在字段、命令与预览特性不断变化的情况下，稳定地产出可维护、安全、环境感知的 azd 项目。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot