跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 azure-static-web-apps

Azure Static Web Apps

帮助使用 SWA CLI 创建,配置并部署 Azure Static Web Apps. 在向Azure部署静态站点时使用,设置SWA本地开发,配置静态webapp.config.json,将Azure函数API添加到SWA,或者为静态网络Apps设置GitHub Actions CI/CD.

8991 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

帮助使用 SWA CLI 创建、配置和部署 Azure Static 网络应用程序

何时用

向Azure部署静态站点,建立SWA本地开发,配置静态webapp.config.json,向SWA添加Azure函数 API,或为静态网络Apps设置 GitHub Actions CI/CD

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Overview、General Instructions、Installation、Quick Start Workflow、Configuration Files、Command-line Reference。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps.

OverviewGeneral InstructionsInstallationQuick Start WorkflowConfiguration FilesCommand-line Referenceswa loginswa initswa buildswa startswa deployswa db

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
azure-static-web-apps
description
Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「azure-static-web-apps」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-0638fdc6c4911987-Azure-%E9%9D%99%E6%80%81%E7%BD%91%E7%BB%9C%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F.html
请存为 .cursor/skills/azure-static-web-apps/SKILL.md 或 .claude/skills/azure-static-web-apps/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/github/awesome-copilot' --list

npx skills add 'https://github.com/github/awesome-copilot' --skill 'azure-static-web-apps'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: azure-static-web-apps description: Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. --- ## Overview Azure Static Web Apps (SWA) hosts static frontends with optional serverless API backends. The SWA CLI (`swa`) provides local development emulation and deployment capabilities. **Key features:** - Local emulator with API proxy and auth simulation - Framework auto-detection and configuration - Direct deployment to Azure - Database connections support **Config files:** - `swa-cli.config.json` - CLI settings, **created by `swa init`** (never create manually) - `staticwebapp.config.json` - Runtime config (routes, auth, headers, API runtime) - can be created manually ## General Instructions ### Installation ```bash npm install -D @azure/static-web-apps-cli ``` Verify: `npx swa --version` ### Quick Start Workflow **IMPORTANT: Always use `swa init` to create configuration files. Never manually create `swa-cli.config.json`.** 1. `swa init` - **Required first step** - auto-detects framework and creates `swa-cli.config.json` 2. `swa start` - Run local emulator at `http://localhost:4280` 3. `swa login` - Authenticate with Azure 4. `swa deploy` - Deploy to Azure ### Configuration Files **swa-cli.config.json** - Created by `swa init`, do not create manually: - Run `swa init` for interactive setup with framework detection - Run `swa init --yes` to accept auto-detected defaults - Edit the generated file only to customize settings after initialization Example of generated config (for reference only): ```json { "$schema": "https://aka.ms/azure/static-web-apps-cli/schema", "configurations": { "app": { "appLocation": ".", "apiLocation": "api", "outputLocation": "dist", "appBuildCommand": "npm run build", "run": "npm run dev", "appDevserverUrl": "http://localhost:3000" } } } ``` **staticwebapp.config.json** (in app source or output folder) - This file CAN be created manually for runtime configuration: ```json { "navigationFallback": { "rewrite": "/index.html", "exclude": ["/images/*", "/css/*"] }, "routes": [ { "route": "/api/*", "allowedRoles": ["authenticated"] } ], "platform": { "apiRuntime": "node:20" } } ``` ## Command-line Reference ### swa login Authenticate with Azure for deployment. ```bash swa login # Interactive login swa login --subscription-id # Specific subscription swa login --clear-credentials # Clear cached credentials ``` **Flags:** `--subscription-id, -S` | `--resource-group, -R` | `--tenant-id, -T` | `--client-id, -C` | `--client-secret, -CS` | `--app-name, -n` ### swa init Configure a new SWA project based on an existing frontend and (optional) API. Detects frameworks automatically. ```bash swa init # Interactive setup swa init --yes # Accept defaults ``` ### swa build Build frontend and/or API. ```bash swa build # Build using config swa build --auto # Auto-detect and build swa build myApp # Build specific configuration ``` **Flags:** `--app-location, -a` | `--api-location, -i` | `--output-location, -O` | `--app-build-command, -A` | `--api-build-command, -I` ### swa start Start local development emulator. ```bash swa start # Serve from outputLocation swa start ./dist # Serve specific folder swa start http://localhost:3000 # Proxy to dev server swa start ./dist --api-location ./api # With API folder swa start http://localhost:3000 --run "npm start" # Auto-start dev server ``` **Common framework ports:** | Framework | Port | |-----------|------| | React/Vue/Next.js | 3000 | | Angular | 4200 | | Vite | 5173 | **Key flags:** - `--port, -p` - Emulator port (default: 4280) - `--api-location, -i` - API folder path - `--api-port, -j` - API port (default: 7071) - `--run, -r` - Command to start dev server - `--open, -o` - Open browser automatically - `--ssl, -s` - Enable HTTPS ### swa deploy Deploy to Azure Static Web Apps. ```bash swa deploy # Deploy using config swa deploy ./dist # Deploy specific folder swa deploy --env production # Deploy to production swa deploy --deployment-token # Use deployment token swa deploy --dry-run # Preview without deploying ``` **Get deployment token:** - Azure Portal: Static Web App → Overview → Manage deployment token - CLI: `swa deploy --print-token` - Environment variable: `SWA_CLI_DEPLOYMENT_TOKEN` **Key flags:** - `--env` - Target environment (`preview` or `production`) - `--deployment-token, -d` - Deployment token - `--app-name, -n` - Azure SWA resource name ### swa db Initialize database connections. ```bash swa db init --database-type mssql swa db init --database-type postgresql swa db init --database-type cosmosdb_nosql ``` ## Scenarios ### Create SWA from Existing Frontend and Backend **Always run `swa init` before `swa start` or `swa deploy`. Do not manually create `swa-cli.config.json`.** ```bash # 1. Install CLI npm install -D @azure/static-web-apps-cli # 2. Initialize - REQUIRED: creates swa-cli.config.json with auto-detected settings npx swa init # Interactive mode # OR npx swa init --yes # Accept auto-detected defaults # 3. Build application (if needed) npm run build # 4. Test locally (uses settings from swa-cli.config.json) npx swa start # 5. Deploy npx swa login npx swa deploy --env production ``` ### Add Azure Functions Backend 1. **Create API folder:** ```bash mkdir api && cd api func init --worker-runtime node --model V4 func new --name message --template "HTTP trigger" ``` 2. **Example function** (`api/src/functions/message.js`): ```javascript const { app } = require('@azure/functions'); app.http('message', { methods: ['GET', 'POST'], authLevel: 'anonymous', handler: async (request) => { const name = request.query.get('name') || 'World'; return { jsonBody: { message: `Hello, ${name}!` } }; } }); ``` 3. **Set API runtime** in `staticwebapp.config.json`: ```json { "platform": { "apiRuntime": "node:20" } } ``` 4. **Update CLI config** in `swa-cli.config.json`: ```json { "configurations": { "app": { "apiLocation": "api" } } } ``` 5. **Test locally:** ```bash npx swa start ./dist --api-location ./api # Access API at http://localhost:4280/api/message ``` **Supported API runtimes:** `node:18`, `node:20`, `node:22`, `dotnet:8.0`, `dotnet-isolated:8.0`, `python:3.10`, `python:3.11` ### Set Up GitHub Actions Deployment 1. **Create SWA resource** in Azure Portal or via Azure CLI 2. **Link GitHub repository** - workflow auto-generated, or create manually: `.github/workflows/azure-static-web-apps.yml`: ```yaml name: Azure Static Web Apps CI/CD on: push: branches: [main] pull_request: types: [opened, synchronize, reopened, closed] branches: [main] jobs: build_and_deploy: if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed') runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Build And Deploy uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }} repo_token: ${{ secrets.GITHUB_TOKEN }} action: upload app_location: / api_location: api output_location: dist close_pr: if: github.event_name == 'pull_request' && github.event.action == 'closed' runs-on: ubuntu-latest steps: - uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }} action: close ``` 3. **Add secret:** Copy deployment token to repository secret `AZURE_STATIC_WEB_APPS_API_TOKEN` **Workflow settings:** - `app_location` - Frontend source path - `api_location` - API source path - `output_location` - Built output folder - `skip_app_build: true` - Skip if pre-built - `app_build_command` - Custom build command ## Troubleshooting | Issue | Solution | |-------|----------| | 404 on client routes | Add `navigationFallback` with `rewrite: "/index.html"` to `staticwebapp.config.json` | | API returns 404 | Verify `api` folder structure, ensure `platform.apiRuntime` is set, check function exports | | Build output not found | Verify `output_location` matches actual build output directory | | Auth not working locally | Use `/.auth/login/` to access auth emulator UI | | CORS errors | APIs under `/api/*` are same-origin; external APIs need CORS headers | | Deployment token expired | Regenerate in Azure Portal → Static Web App → Manage deployment token | | Config not applied | Ensure `staticwebapp.config.json` is in `app_location` or `output_location` | | Local API timeout | Default is 45 seconds; optimize function or check for blocking calls | **Debug commands:** ```bash swa start --verbose log # Verbose output swa deploy --dry-run # Preview deployment swa --print-config # Show resolved configuration ```

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…