Azure Static Web Apps

概述

Azure 静态 Web 应用 (SWA) 托管带有可选无服务器 API 后端的静态前端。SWA CLI (swa) 提供本地开发模拟和部署功能。

主要功能：

• 带有 API 代理和身份验证模拟的本地模拟器
• 框架自动检测和配置
• 直接部署到 Azure
• 支持数据库连接

配置文件：

• swa-cli.config.json – CLI 设置，由 swa init 创建（切勿手动创建）
• staticwebapp.config.json – 运行时配置（路由、身份验证、标头、API 运行时）- 可以手动创建

常规说明

安装

npm install -D @azure/static-web-apps-cli

验证：npx swa --version

快速入门工作流程

重要：始终使用 swa init 创建配置文件。切勿手动创建 swa-cli.config.json。

1. swa init – 必需的第一个步骤 – 自动检测框架并创建 swa-cli.config.json
2. swa start – 在 http://localhost:4280 运行本地模拟器
3. swa login – 通过 Azure 进行身份验证
4. swa deploy – 部署到 Azure

配置文件

swa-cli.config.json – 由 swa init 创建，请勿手动创建：

• 运行 swa init 进行带有框架检测的交互式设置
• 运行 swa init --yes 接受自动检测的默认值
• 初始化后，仅在需要自定义设置时编辑生成的文件

生成的配置示例（仅供参考）：

{
  "$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（位于应用源代码或输出文件夹中）- 此文件可以手动创建，用于运行时配置：

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*", "/css/*"]
  },
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] }
  ],
  "platform": {
    "apiRuntime": "node:20"
  }
}

命令行参考

swa login

通过 Azure 进行身份验证以进行部署。

swa login                              # 交互式登录
swa login --subscription-id <id>       # 指定订阅
swa login --clear-credentials          # 清除缓存的凭据

标志： --subscription-id, -S | --resource-group, -R | --tenant-id, -T | --client-id, -C | --client-secret, -CS | --app-name, -n

swa init

基于现有的前端和（可选的）API 配置一个新的 SWA 项目。自动检测框架。

swa init                    # 交互式设置
swa init --yes              # 接受默认值

swa build

构建前端和/或 API。

swa build                   # 使用配置进行构建
swa build --auto            # 自动检测并构建
swa build myApp             # 构建特定配置

标志： --app-location, -a | --api-location, -i | --output-location, -O | --app-build-command, -A | --api-build-command, -I

swa start

启动本地开发模拟器。

swa start                                    # 从 outputLocation 提供服务
swa start ./dist                             # 提供特定文件夹的服务
swa start http://localhost:3000              # 代理到开发服务器
swa start ./dist --api-location ./api        # 带 API 文件夹
swa start http://localhost:3000 --run "npm start"  # 自动启动开发服务器

常见框架端口：

关键标志：

• --port, -p – 模拟器端口（默认：4280）
• --api-location, -i – API 文件夹路径
• --api-port, -j – API 端口（默认：7071）
• --run, -r – 启动开发服务器的命令
• --open, -o – 自动打开浏览器
• --ssl, -s – 启用 HTTPS

swa deploy

部署到 Azure 静态 Web 应用。

swa deploy                              # 使用配置进行部署
swa deploy ./dist                       # 部署特定文件夹
swa deploy --env production             # 部署到生产环境
swa deploy --deployment-token <TOKEN>   # 使用部署令牌
swa deploy --dry-run                    # 预览，不实际部署

获取部署令牌：

• Azure 门户：静态 Web 应用 → 概述 → 管理部署令牌
• CLI：swa deploy --print-token
• 环境变量：SWA_CLI_DEPLOYMENT_TOKEN

关键标志：

• --env – 目标环境（preview 或 production）
• --deployment-token, -d – 部署令牌
• --app-name, -n – Azure SWA 资源名称

swa db

初始化数据库连接。

swa db init --database-type mssql
swa db init --database-type postgresql
swa db init --database-type cosmosdb_nosql

场景

从现有的前端和后端创建 SWA

在 swa start 或 swa deploy 之前，始终运行 swa init。请勿手动创建 swa-cli.config.json。

# 1. 安装 CLI
npm install -D @azure/static-web-apps-cli

# 2. 初始化 - 必需：创建带有自动检测设置的 swa-cli.config.json
npx swa init              # 交互式模式
# 或
npx swa init --yes        # 接受自动检测的默认值

# 3. 构建应用程序（如果需要）
npm run build

# 4. 本地测试（使用 swa-cli.config.json 中的设置）
npx swa start

# 5. 部署
npx swa login
npx swa deploy --env production

添加 Azure Functions 后端

1. 创建 API 文件夹：

mkdir api && cd api
func init --worker-runtime node --model V4
func new --name message --template "HTTP trigger"

2. 示例函数（api/src/functions/message.js）：

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. 在 staticwebapp.config.json 中设置 API 运行时：

{
  "platform": { "apiRuntime": "node:20" }
}

4. 在 swa-cli.config.json 中更新 CLI 配置：

{
  "configurations": {
    "app": { "apiLocation": "api" }
  }
}

5. 本地测试：

npx swa start ./dist --api-location ./api
# 访问 API 位于 http://localhost:4280/api/message

支持的 API 运行时： node:18、node:20、node:22、dotnet:8.0、dotnet-isolated:8.0、python:3.10、python:3.11

设置 GitHub Actions 部署

1. 在 Azure 门户中或通过 Azure CLI 创建 SWA 资源
2. 链接 GitHub 仓库 – 工作流会自动生成，或手动创建：

.github/workflows/azure-static-web-apps.yml：

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. 添加密钥： 将部署令牌复制到仓库密钥 AZURE_STATIC_WEB_APPS_API_TOKEN

工作流设置：

• app_location – 前端源代码路径
• api_location – API 源代码路径
• output_location – 构建输出文件夹
• skip_app_build: true – 如果已预构建，则跳过
• app_build_command – 自定义构建命令

故障排除

调试命令：

swa start --verbose log        # 详细输出
swa deploy --dry-run           # 预览部署
swa --print-config             # 显示解析后的配置