azure-static-web-apps

概觀

Azure Static Web Apps (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"  # 自動啟動開發伺服器

常見框架連接埠：

框架	連接埠
React/Vue/Next.js	3000
Angular	4200
Vite	5173

主要旗標：

• --port, -p - 模擬器連接埠（預設：4280）
• --api-location, -i - API 資料夾路徑
• --api-port, -j - API 連接埠（預設：7071）
• --run, -r - 啟動開發伺服器的命令
• --open, -o - 自動開啟瀏覽器
• --ssl, -s - 啟用 HTTPS

swa deploy

部署至 Azure Static Web Apps。

swa deploy                              # 使用設定部署
swa deploy ./dist                       # 部署特定資料夾
swa deploy --env production             # 部署至生產環境
swa deploy --deployment-token <TOKEN>   # 使用部署權杖
swa deploy --dry-run                    # 預覽但不實際部署

取得部署權杖：

• Azure 入口網站：Static Web App → 概觀 → 管理部署權杖
• 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. 更新 CLI 設定 在 swa-cli.config.json 中：

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

5. 在本機測試：

npx swa start ./dist --api-location ./api
# 在 http://localhost:4280/api/message 存取 API

支援的 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 - 自訂建置命令

疑難排解

問題	解決方案
用戶端路由出現 404	在 staticwebapp.config.json 中加入 navigationFallback 並設定 rewrite: "/index.html"
API 回傳 404	確認 api 資料夾結構、確保已設定 platform.apiRuntime、檢查函式匯出
找不到建置輸出	確認 output_location 與實際建置輸出目錄相符
本機驗證無法運作	使用 /.auth/login/<provider> 存取驗證模擬器 UI
CORS 錯誤	/api/* 下的 API 為同源；外部 API 需要 CORS 標頭
部署權杖過期	在 Azure 入口網站 → Static Web App → 管理部署權杖中重新產生
設定未生效	確保 staticwebapp.config.json 位於 app_location 或 output_location 中
本機 API 逾時	預設為 45 秒；最佳化函式或檢查是否有阻塞呼叫

除錯命令：

swa start --verbose log        # 詳細輸出
swa deploy --dry-run           # 預覽部署
swa --print-config             # 顯示解析後的設定