鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

azure-static-web-apps

提供 Azure 静态网站应用的全生命周期管理能力,涵盖本地开发环境搭建、框架自动识别与配置、前后端联调模拟、静态资源与无服务器 API 的一体化部署,以及 GitHub Actions 自动化发布流程集成。

开发运维
访问 GitHub
文档Skills.MD
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 <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:

FrameworkPort
React/Vue/Next.js3000
Angular4200
Vite5173

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 <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"
  1. 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}!` } }; } });
  1. Set API runtime in staticwebapp.config.json:
▼
json
复制代码
{ "platform": { "apiRuntime": "node:20" } }
  1. Update CLI config in swa-cli.config.json:
▼
json
复制代码
{ "configurations": { "app": { "apiLocation": "api" } } }
  1. 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
  1. 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

IssueSolution
404 on client routesAdd navigationFallback with rewrite: "/index.html" to staticwebapp.config.json
API returns 404Verify api folder structure, ensure platform.apiRuntime is set, check function exports
Build output not foundVerify output_location matches actual build output directory
Auth not working locallyUse /.auth/login/<provider> to access auth emulator UI
CORS errorsAPIs under /api/* are same-origin; external APIs need CORS headers
Deployment token expiredRegenerate in Azure Portal → Static Web App → Manage deployment token
Config not appliedEnsure staticwebapp.config.json is in app_location or output_location
Local API timeoutDefault 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
开发运维

快捷安装

复制到终端去安装 Skill

npxskillsaddgithub/awesome-copilot--skill"azure-static-web-apps"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
load-balancer-configurator
根据用户需求自动生成各类负载均衡器的生产级配置,覆盖 ALB、NLB、Nginx 和 HAProxy 等主流类型,适配不同协议、端口、健康检查及后端服务拓扑,支持直接集成到基础设施即代码流程中。
implement
实现 Linus Dashboard 的功能开发与集成,基于 TypeScript 和 Python 构建前后端组件,遵循严格的代码规范与架构模式,完成视图、卡片、服务及传感器等模块的创建与验证,确保高质量交付并兼容 Home Assistant 生态。
cloud-scheduler-job-creator
自动处理 Google Cloud Platform 中的云调度任务创建,提供符合最佳实践的配置方案与生产级代码生成,支持计算、存储、大数据及机器学习服务的集成部署。