Azure Developer CLI 官方參考知識體系以 Microsoft Learn 為事實源的 azd 項目開發(fā)與排障指南【免費(fèi)下載鏈接】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為骨架系統(tǒng)梳理 Azure Developer CLIazd的權(quán)威知識領(lǐng)域核心概念與項目結(jié)構(gòu)、基礎(chǔ)設(shè)施即代碼Bicep/Terraform、環(huán)境與密鑰管理、鉤子/流水線與運(yùn)維以及 GitHub Copilot Agent 技能格式。讀者讀完本指南后將掌握一套按需查閱官方文檔、以倉庫內(nèi)參考手冊落地的 azd 項目設(shè)計、審查、遷移與排障方法論并能在不確定字段、命令參數(shù)或預(yù)覽特性行為時快速定位正確的權(quán)威依據(jù)。為什么需要一份官方參考索引Azure Developer CLI 是快速演進(jìn)的工具其 Schema、命令參數(shù)、Host 類型、預(yù)覽狀態(tài)與認(rèn)證行為經(jīng)常調(diào)整。azd項目一旦基于過時記憶或過氣博客編寫很容易在生產(chǎn)環(huán)境暴露出字段不兼容、命令行為漂移等問題。因此本技能在 references/official-docs.md 中確立了一條鐵律Use Microsoft Learn as the source of truth for AZD behavior and schema details.即以 Microsoft Learn 作為 azd 行為與 Schema 細(xì)節(jié)的事實源。該參考索引于 2026-08-05 經(jīng)過復(fù)核并將官方資料按五大領(lǐng)域組織核心概念與結(jié)構(gòu)、基礎(chǔ)設(shè)施即代碼、環(huán)境與密鑰、鉤子/流水線與運(yùn)維、技能格式。文檔末尾的原則進(jìn)一步要求當(dāng)某個字段、命令標(biāo)志、宿主類型、預(yù)覽狀態(tài)或認(rèn)證行為不確定時必須查閱對應(yīng)的最新參考后再修改代碼不要依賴對快速演進(jìn)的預(yù)覽特性preview feature的背誦式記憶。這條方法論與技能的整體定位一致SKILL.md 的 frontmatter第 1-5 行即聲明該技能用于依據(jù) Microsoft 當(dāng)前指導(dǎo)設(shè)計、創(chuàng)建、審查、遷移或排障 azd 項目覆蓋 azure.yaml、AZD 模板、infra 下的 Bicep/Terraform、環(huán)境與密鑰、鉤子、部署工作流與 azd 托管的 CI/CD。核心概念與結(jié)構(gòu)從 azd 概覽到 azure.yaml 清單官方參考的第一組主題回答azd 是什么、模板怎么來、清單怎么寫、一條命令如何貫通部署Azure Developer CLI 文檔與 What is the Azure Developer CLI?工具定位與整體能力邊界。Azure Developer CLI 模板概述與如何創(chuàng)建兼容模板官方模板生態(tài)與azd對倉庫結(jié)構(gòu)的要求。Azure Developer CLI Schema 參考與azure.yamlJSON Schema清單文件的權(quán)威字段定義是編輯器校驗與審查的底層依據(jù)。azd up工作流詳解與全棧部署一條命令完成打包、預(yù)配、部署的組合語義以及多服務(wù)全棧場景下的行為。倉庫內(nèi)與之對應(yīng)的是 references/project-structure.md它給出了 azd 項目推薦布局——根目錄一份azure.yaml、infra/存放 IaC 編排入口、src/service-name/存放每個可獨(dú)立部署的服務(wù)、scripts/azd/存放鉤子腳本而.azure/是生成的本地環(huán)境狀態(tài)必須被.gitignore排除。azure.yaml基線清單直接來自技能自帶的可運(yùn)行示例 examples/azure.yaml# yaml-language-server: $schemahttps://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要點(diǎn)解讀依據(jù) project-structure.md 的清單核對項首行的 Schema 指令為編輯器提供 azure.yaml 的實時校驗這正是官方azure.yamlJSON Schema 在工程中的落地方式。name必須小寫、以字母數(shù)字開頭與結(jié)尾僅允許字母數(shù)字與連字符。infra塊的providerBicep 為默認(rèn)、path默認(rèn)./infra、module默認(rèn)main顯式聲明時更利于審查若省略則按默認(rèn)值推斷所以閱讀azure.yaml時切勿先入為主地假設(shè)默認(rèn)路徑或默認(rèn)提供商。services中每個條目代表一份可部署的應(yīng)用代碼而非數(shù)據(jù)庫、Key Vault 等共享資源服務(wù)名應(yīng)簡短、有意義且保持穩(wěn)定因為它們參與資源發(fā)現(xiàn)與部署。metadata.template、requiredVersions、workflows、state.remote等頂層字段各有明確用途模板分發(fā)時標(biāo)識來源、依賴最低 azd 版本時聲明約束、僅當(dāng)部署順序確有需要時覆蓋工作流、團(tuán)隊共享環(huán)境時配置遠(yuǎn)程狀態(tài)。基礎(chǔ)設(shè)施即代碼Bicep 與 Terraform 的官方口徑官方參考的第二組主題確立 IaC 側(cè)的權(quán)威依據(jù)Use Terraform as an infrastructure as code tool for Azure Developer CLIazd 對 Terraform 的集成方式與當(dāng)前限制。Azure Verified Modules微軟驗證過的可復(fù)用資源模塊體系。Bicep 文檔與 Terraform on Azure 文檔兩種 IaC 語言本身的權(quán)威資料。倉庫內(nèi) references/iac-and-environments.md 給出了與此對應(yīng)的選型與實踐口徑Bicep 是 azd 的默認(rèn) IaC 提供商適用于純 Azure 項目、追求原生資源覆蓋與無狀態(tài)部署模型的團(tuán)隊Terraform 則適用于倉庫已采用 Terraform、已有模塊/狀態(tài)/策略/審查實踐或確有跨云需求的團(tuán)隊。Terraform 支持目前被微軟官方文檔標(biāo)記為 beta這是必須向用戶明示的約束不能僅因熟悉而把項目遷到 Terraform。Bicep 結(jié)構(gòu)上保持main.bicep為薄編排層能力按modules/core、modules/data、modules/identity、modules/observability、modules/services拆分模塊版本應(yīng)鎖定并走評審升級不浮動追蹤。參數(shù)流轉(zhuǎn)是 azd 與 IaC 的契約核心。用main.parameters.json將 AZD 環(huán)境值映射進(jìn) Bicepiac-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} } } }入口文件中使用帶描述與校驗裝飾器的參數(shù)聲明與之呼應(yīng)description(Stable name of the AZD deployment environment.) minLength(1) param environmentName string description(Primary Azure region for this deployment.) param location string而outputs是預(yù)配階段與后續(xù)azd deploy、鉤子、流水線之間的契約——例如output SERVICE_API_ENDPOINT_URL string api.outputs.endpoint輸出名必須穩(wěn)定因為服務(wù)、鉤子、流水線會把它當(dāng)作環(huán)境變量消費(fèi)。任何秘密值都禁止出現(xiàn)在 IaC 輸出中因為部署輸出會被復(fù)制進(jìn) AZD 環(huán)境。Terraform 側(cè)的關(guān)鍵實踐同樣依據(jù) iac-and-environments.md在azure.yaml顯式設(shè)置infra.provider: terraform并將所有 azd 托管的.tf文件置于配置的 infra 路徑下。鎖定 Terraform 與 Provider 版本并提交依賴鎖文件.tfstate、計劃文件、崩潰日志、Provider 憑據(jù)一律不入庫。Terraform 的 Azure Provider 默認(rèn)使用 Azure CLI 認(rèn)證不經(jīng) azd 憑據(jù)緩存推薦單次登錄配置azd config set auth.useAzCliAuth true后執(zhí)行az login否則需要同時執(zhí)行azd auth login與az login。在azd pipeline config或協(xié)作部署前配置受保護(hù)的遠(yuǎn)程后端azd 按官方 Terraform 集成要求從infra/provider.conf.json讀取后端設(shè)置遠(yuǎn)程狀態(tài)須按機(jī)密數(shù)據(jù)對待配 RBAC 與網(wǎng)絡(luò)控制。環(huán)境與密鑰官方環(huán)境模型的落地官方參考的第三組主題覆蓋 azd 的多環(huán)境模型與密鑰處理Azure Developer CLI 環(huán)境概述與使用環(huán)境環(huán)境是什么、如何創(chuàng)建/選擇/管理。環(huán)境變量管理非密鑰型配置的存取方式。遠(yuǎn)程環(huán)境支持團(tuán)隊共享環(huán)境狀態(tài)的官方方案。環(huán)境密鑰Environment secrets密鑰在 azd 環(huán)境中的標(biāo)準(zhǔn)用法。倉庫內(nèi)對應(yīng)文檔 iac-and-environments.md 描述了 azd 的本地狀態(tài)布局.azure/ |-- config.json |-- environment-name/ |-- .env |-- config.json整個.azure目錄必須留在源碼控制之外。環(huán)境命名建議共享環(huán)境用project-dev、project-test、project-prod個人環(huán)境用alias-purpose臨時環(huán)境用project-pr-number并保證自動化同時負(fù)責(zé)清理名稱要短到能容納資源命名限制。環(huán)境管理應(yīng)使用命令而非手工改文件同樣來自 iac-and-environments.mdazd 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在自動化與可能破壞性的操作中務(wù)必顯式指定環(huán)境azd provision -e environment --no-prompt azd deploy -e environment --no-prompt密鑰方面官方環(huán)境密鑰特性對應(yīng)azd env set-secret name它在 AZD 環(huán)境中保存一個 Key Vault 引用而非明文。倉庫內(nèi) security-cicd-operations.md 給出密鑰偏好順序托管身份 最小權(quán)限 RBAC → CI/CD 用工作負(fù)載身份聯(lián)合OIDC→ Key Vault 引用 → 僅在無身份方案可用時才使用短時密鑰材料。與 Bicep 配合時輸入?yún)?shù)標(biāo)記secure()、經(jīng)main.parameters.json映射 AZD 密鑰引用、絕不輸出該安全值同時要注意當(dāng)前官方文檔指出環(huán)境密鑰與.bicepparam文件不兼容。團(tuán)隊共享環(huán)境時配置state.remoteiac-and-environments.mdstate: remote: backend: AzureBlobStorage config: accountName: storage-account-name containerName: project-container-name需特別區(qū)分AZD 遠(yuǎn)程狀態(tài)同步的是.env與 azdconfig.json環(huán)境配置與Terraform 遠(yuǎn)程狀態(tài)托管基礎(chǔ)設(shè)施狀態(tài)是兩回事一個通過 azd 協(xié)作的 Terraform 項目可能同時需要兩者且兩份存儲都須以最小權(quán)限 RBAC 與數(shù)據(jù)保護(hù)設(shè)置加以防護(hù)。鉤子、流水線與運(yùn)維官方擴(kuò)展點(diǎn)與生命周期官方參考的第四組主題覆蓋 azd 的擴(kuò)展與運(yùn)維用鉤子定制 azd 工作流生命周期各階段的擴(kuò)展機(jī)制。CI/CD 流水線支持與 GitHub Actions 流水線創(chuàng)建azd 生成與托管流水線的官方路徑。高級流水線特性與配置變量、密鑰、審批、環(huán)境保護(hù)等。azd 命令參考與故障排查權(quán)威命令語義與排障方法。倉庫內(nèi) security-cicd-operations.md 給出了落地的完整閉環(huán)。azd 的標(biāo)準(zhǔn)生命周期是打包應(yīng)用制品 → 預(yù)配/更新基礎(chǔ)設(shè)施 → 部署應(yīng)用制品。azd up是這三步的組合命令適合日常開發(fā)與簡單部署當(dāng)需要基礎(chǔ)設(shè)施評審、應(yīng)用頻繁重部署、隔離排障或自定義依賴順序時應(yīng)拆分為azd package、azd provision -e environment、azd deploy -e environment。鉤子只在默認(rèn)生命周期無法表達(dá)需求時添加規(guī)則包括優(yōu)先外部腳本存放于scripts/azd、顯式聲明shellsh或pwsh、必要時提供windows與posix雙實現(xiàn)、腳本冪等、CI 中非交互、continueOnError保持false除非僅觀測或確實可選、先azd hooks run hook-name獨(dú)立測試。技能自帶的 examples/azure.yaml 第 20-32 行就是標(biāo)準(zhǔn)的雙平臺鉤子模板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: falseCI/CD 側(cè)azd pipeline config被官方標(biāo)記為beta運(yùn)行前須審查模板自帶的流水線定義確認(rèn)倉庫、組織、環(huán)境、訂閱與認(rèn)證模式并預(yù)期其對倉庫、身份、變量、密鑰、提交、推送與流水線的副作用pipeline.variables或pipeline.secrets變更后需重跑。GitHub Actions 場景下 azd 默認(rèn)配置 OIDC/聯(lián)合憑據(jù)但當(dāng)前 azd 的 Terraform 流水線流程不支持 OIDC應(yīng)明確評估認(rèn)證取舍而不是靜默回退到長期憑據(jù)。部署前的本地驗證來自 security-cicd-operations.mdBicep: az bicep build --file infra/main.bicep Terraform: terraform fmt -check -recursive terraform init -backendfalse terraform validate AZD hooks: azd hooks run hook-name Packaging: azd package故障排查遵循同樣的以事實源為準(zhǔn)思路security-cicd-operations.md先判斷失敗發(fā)生在打包、預(yù)配、部署、鉤子、認(rèn)證還是資源發(fā)現(xiàn)階段重跑最小失敗階段而非整個azd up核對選中環(huán)境與預(yù)期的訂閱/租戶/區(qū)域檢查azure.yaml路徑與資源發(fā)現(xiàn)標(biāo)簽Azure 狀態(tài)在別處變更后用azd env refresh同步Terraform 項目則同時核查 azd/Azure CLI 認(rèn)證與遠(yuǎn)程狀態(tài)必要時開啟調(diào)試日志并先脫敏再分享。技能格式Agent 側(cè)的知識來源官方參考的第五組主題面向 GitHub Copilot Agent 技能的編寫者為 GitHub Copilot 添加 Agent 技能Adding agent skills for GitHub Copilot技能的安裝與接入方式。關(guān)于 Agent 技能About agent skills技能概念、邊界與最佳實踐。這兩份資料之所以被收入 azd 技能參考是因為 azure-developer-cli 本身就是一個以 SKILL.md 為入口的 Copilot 技能其 frontmatter 聲明了nameazure-developer-cli、description描述適用場景供模型匹配調(diào)用與licenseMIT。當(dāng)技能作者或使用該技能的 Agent 需要調(diào)整技能行為、字段或參考引用時應(yīng)先查閱官方技能格式文檔再決定如何修改 frontmatter、正文與references/下的手冊避免把 azd 行為與技能元數(shù)據(jù)格式混為一談。落地清單不確定時該查哪份參考將官方參考索引的方法論轉(zhuǎn)化為可執(zhí)行的核對動作文件均為本倉庫內(nèi)路徑場景優(yōu)先查閱azure.yaml 字段、服務(wù)/Host 類型、Schema 合法性references/official-docs.md 的 Schema 主題 references/project-structure.md 清單Bicep/Terraform 結(jié)構(gòu)、參數(shù)流轉(zhuǎn)、輸出契約、遠(yuǎn)程狀態(tài)references/iac-and-environments.md環(huán)境創(chuàng)建/選擇/密鑰、遠(yuǎn)程環(huán)境、state.remotereferences/iac-and-environments.md 的環(huán)境章節(jié)鉤子寫法、CI/CD、azd pipeline config、驗證與排障references/security-cicd-operations.md技能格式與接入方式references/official-docs.md 的 Skill format 主題涉及命令標(biāo)志、預(yù)覽狀態(tài)、認(rèn)證行為的任何不確定點(diǎn)先查對應(yīng)官方當(dāng)前參考再改代碼結(jié)尾再次回到 official-docs.md 的核心結(jié)論對于 azd 這樣快速演進(jìn)的工具正確性來源于查閱當(dāng)前官方文檔這一習(xí)慣本身。把官方參考索引用作知識地圖、把倉庫內(nèi)三份參考手冊用作落地細(xì)則就能在字段、命令與預(yù)覽特性不斷變化的情況下穩(wěn)定地產(chǎn)出可維護(hù)、安全、環(huán)境感知的 azd 項目。【免費(fèi)下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考