Azure Static Web Apps Skill

微软近日为 GitHub Copilot 推出官方 Azure Static Web Apps (SWA)，将原本需 30 分钟的手动配置流程压缩至几分钟内完成。该 Skill 基于开放标准构建，未来还可跨平台用于 Claude 等支持 MCP 协议的 AI 助手。

开发者只需在聊天中输入一句自然语言指令，如：

“将我的 React 应用部署到 SWA”

Copilot 即可自动执行完整工作流：安装 CLI、初始化项目、配置路由、部署上线——全程无需记忆命令或查阅文档。

什么是 Agent Skill？

Agent Skill 是一组轻量级指令包（仅含 SKILL.md 文件），用于教 AI 助手处理特定任务。

• 自动触发：Copilot 根据上下文智能调用，无需手动激活
• 开放标准：基于 Model Context Protocol（MCP），支持跨 AI 平台移植
• 本地优先：Skill 文件存于项目 .skills/ 目录，不依赖云端服务

要使用 Azure SWA Skill，只需：

mkdir -p .skills
cd .skills
git clone https://github.com/github/azure-static-web-apps-skill.git

Copilot 将自动识别并启用。

Azure Static Web Apps 简介

Azure Static Web Apps 是微软提供的全托管服务，支持：

• 静态前端托管（React、Vue、Svelte 等）
• 可选无服务器 API 后端（Azure Functions）
• 内置身份验证、自定义域名、CI/CD 集成

配套的 SWA CLI 提供本地开发模拟与一键部署能力。

核心功能亮点（由 Skill 自动处理）

例如，Skill 会确保 staticwebapp.config.json 包含：

{
  "navigationFallback": { "rewrite": "/index.html" }
}

从而解决单页应用（SPA）刷新 404 问题。

快速上手：从零到部署

1. 安装 SWA CLI

npm install -D @azure/static-web-apps-cli
npx swa --version  # 验证安装

2. 初始化项目（关键步骤！）

npx swa init        # 交互式配置
# 或
npx swa init --yes  # 接受自动检测的默认值

⚠️ 切勿手动创建 swa-cli.config.json —— 必须通过 swa init 生成。

3. 本地开发

npx swa start       # 启动模拟器（默认 http://localhost:4280）

支持：

• 自动代理到开发服务器（如 http://localhost:3000）
• 模拟 API 调用与身份验证
• 实时重载

4. 部署到 Azure

npx swa login       # Azure 身份验证
npx swa deploy      # 一键部署

支持生产/预览环境切换、部署令牌认证、干运行预览。

高级场景支持

✅ 添加 Azure Functions 后端

1. 创建 api/ 目录并初始化函数
2. Skill 自动配置：
   • swa-cli.config.json 中的 apiLocation
   • staticwebapp.config.json 中的 platform.apiRuntime
3. 本地测试：swa start ./dist --api-location ./api

✅ 数据库连接

swa db init --database-type postgresql

支持 Cosmos DB、SQL Server、PostgreSQL。

✅ GitHub Actions CI/CD

Skill 可生成标准工作流文件 .github/workflows/azure-static-web-apps.yml，自动处理：

• 构建命令
• 输出路径
• PR 预览环境
• 密钥管理

常见问题与调试

调试命令：

swa start --verbose log    # 查看详细日志
swa deploy --dry-run       # 预览部署内容
swa --print-config         # 输出解析后的配置

为什么值得使用？

• 降低门槛：新手无需学习 SWA 复杂配置
• 提升效率：资深开发者免去重复样板操作
• 减少错误：自动处理易错点（如路由回退、API 运行时）
• 开放生态：Skill 格式未来可复用于其他 AI 工具