建置 Azure Static Web Apps 的組態

發行項
11/05/2024

Azure Static Web Apps 組建組態會使用 GitHub Actions 或 Azure Pipelines。每個月臺都有一個 YAML 組態檔，可控制月臺的建置和部署方式。本文說明檔案的結構和選項。

下表列出可用的組態設定。

屬性	描述	必要
`app_location`	此資料夾包含前端應用程式的原始程式碼。此值相對於 GitHub 中的存放庫根目錄，以及 Azure DevOps 中目前的工作資料夾。搭配 `skip_app_build: true`使用時，這個值是應用程式的組建輸出位置。	Yes
`api_location`	這個資料夾包含 API 應用程式的原始程式碼。此值相對於 GitHub 中的存放庫根目錄，以及 Azure DevOps 中目前的工作資料夾。搭配 `skip_api_build: true`使用時，這個值是 API 的組建輸出位置。	No
`output_location`	如果您的 Web 應用程式執行建置步驟，則輸出位置是產生公用檔案的資料夾。對於大部分的專案而言，`output_location` 是相對於 `app_location` 的。不過，針對 .NET 專案，位置相對於輸出資料夾。	No
`app_build_command`	針對Node.js應用程式，您可以定義自定義命令來建置靜態內容應用程式。例如，若要為 Angular 應用程式設定生產組建，請建立名為 `build-prod` 的 npm 腳本，以執行 `ng build --prod` 並輸入 `npm run build-prod` 作為自定義命令。如果保留空白，工作流程會嘗試執行 `npm run build` 或 `npm run build:azure` 命令。	No
`api_build_command`	針對Node.js應用程式，您可以定義自定義命令來建置 Azure Functions API 應用程式。	No
`skip_app_build`	將值設定為 `true` 以略過建置前端應用程式。	No
`skip_api_build`	將值設定為 `true` ，以略過建置 API 函式。	No
`cwd` （僅限 Azure Pipelines）	工作資料夾的絕對路徑。預設為 `$(System.DefaultWorkingDirectory)`。	No
`build_timeout_in_minutes`	設定此值以自定義建置逾時。預設為 `15`。	No

透過這些設定，您可以設定 GitHub Actions 或 Azure Pipelines ，為您的靜態 Web 應用程式執行持續整合/持續傳遞（CI/CD）。

檔名和位置

GitHub 巨集指令會產生組態檔，並儲存在 .github/workflows 資料夾中，使用下列格式命名： azure-static-web-apps-<RANDOM_NAME>.yml。

根據預設，組態檔會儲存在存放庫的根目錄中，名稱為 azure-pipelines.yml。

安全性

您可以選擇兩個不同的部署授權原則來保護組建組態。 Static Web Apps 支援使用 Azure 部署令牌（建議），或 GitHub 存取令牌。

使用下列步驟在您的應用程式中設定部署授權原則：

新增應用程式：當您建立靜態 Web 應用程式時，請在 [ 部署組態 ] 索引標籤上 選取 [部署授權原則]。
現有應用程式：若要更新現有的應用程式，請移至 [設定>組態>部署設定] 組態，然後選取 [部署授權原則]。

組建組態

下列範例組態會監視存放庫是否有變更。當認可推送至 main 分支時，應用程式會從 app_location 中的資料夾建置，並將中的 output_location 檔案提供給公用Web。此外，api 資料夾中的應用程式可在網站api的路徑下使用。

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'src' # App source code path relative to cwd
      api_location: 'api' # Api source code path relative to cwd
      output_location: 'public' # Built app content directory relative to app_location - optional
      cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
      azure_static_web_apps_api_token: $(deployment_token)

在這裡設定中：

分支 main 會監視認可。
指向app_locationsrc包含 Web 應用程式來源檔案的資料夾。這個值相對於工作目錄（cwd）。若要將它設定為工作目錄，請使用 /。
指向api_locationapi包含月臺 API 端點之 Azure Functions 應用程式的資料夾。這個值相對於工作目錄（cwd）。若要將它設定為工作目錄，請使用 /。
指向output_locationpublic包含應用程式原始程式檔最終版本的資料夾。這個值相對於 app_location。針對 .NET 專案，位置相對於輸出資料夾。
cwd是指向工作目錄的絕對路徑。其預設為 $(System.DefaultWorkingDirectory)。
變數 $(deployment_token) 會指向產生的 Azure DevOps 部署令牌。

注意

app_location 和 api_location 必須相對於工作目錄（cwd），而且它們必須是底下的 cwd子目錄。

身分識別令牌
Azure 存取令牌

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
      - dev
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    permissions:
       id-token: write
       contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - name: Install OIDC Client from Core Package
        run: npm install @actions/core@1.6.0 @actions/http-client
      - name: Get Id Token
        uses: actions/github-script@v6
        id: idtoken
        with:
           script: |
               const coredemo = require('@actions/core')
               return await coredemo.getIDToken()
           result-encoding: string
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_WATER }}
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "dist/angular-basic" # Built app content directory - optional
          production_branch: "dev"
          github_id_token: ${{ steps.idtoken.outputs.result }}
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_WATER_030D91C1E }}
          action: "close"

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        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 }} # Used for GitHub integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations ######
          app_location: "src" # App source code path relative to repository root
          api_location: "api" # Api source code path relative to repository root - optional
          output_location: "public" # Built app content directory, relative to app_location - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

在這裡設定中：

分支 main 會監視認可。
當分支上的main提取要求已開啟、同步處理、重新開啟或關閉時，就會觸發 GitHub Actions 工作流程。
會在 build_and_deploy_job 您針對屬性中列出的 on 分支推送認可或開啟提取要求時執行。
指向app_locationsrc包含 Web 應用程式來源檔案的資料夾。若要將此值設定為存放庫根目錄，請使用 /。
指向api_locationapi包含月臺 API 端點之 Azure Functions 應用程式的資料夾。若要將此值設定為存放庫根目錄，請使用 /。
指向output_locationpublic包含應用程式原始程式檔最終版本的資料夾。它相對於 app_location。對於 .NET 專案，位置相對於發佈輸出資料夾。

請勿變更、 action和 azure_static_web_apps_api_token 的值repo_token，因為它們是由 Azure Static Web Apps 為您設定。

關閉 提取要求 作業會自動關閉觸發建置和部署的提取要求。此選擇性作業不需要讓進程運作。

開啟提取要求時，Azure Static Web Apps GitHub Action 會建置應用程式，並將應用程式部署至預備環境。之後， 關閉提取要求 作業會檢查提取要求是否仍然開啟，並使用完成訊息將其關閉。

此作業可協助保持提取要求工作流程的組織，並防止過時的提取要求。藉由運行時間自動關閉提取要求，您的存放庫會保持最新狀態，且您的小組會收到狀態通知。

關閉 提取要求 作業是 Azure Static Web Apps GitHub Actions 工作流程的一部分，會在合併提取要求之後關閉提取要求。此 Azure/static-web-apps-deploy 動作會將應用程式部署至 Azure Static Web Apps，需要 azure_static_web_apps_api_token 進行驗證。

自訂建置命令

針對Node.js應用程式，您可以更精細地控制在應用程式或 API 建置程式期間執行哪些命令。下列範例示範如何使用和api_build_command的值app_build_command來定義組建。

注意

目前，您只能定義 app_build_command 和 api_build_command Node.js 組建。若要指定Node.js版本，請使用 engines 檔案中的 package.json 欄位。

...

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'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'

...

inputs:
  app_location: 'src'
  api_location: 'api'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)

略過建置前端應用程式

如果您需要完整控制前端應用程式的組建，您可以略過自動建置，並部署在上一個步驟中建置的應用程式。

若要略過建置前端應用程式：

設定 app_location 為您要部署檔案的位置。
將 skip_app_build 設定為 true。
設定 output_location 為空字串（''）。

注意

請確定您已 staticwebapp.config.json 將 檔案複製到輸出 目錄中。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src/dist'
  api_location: 'api'
  output_location: ''
  skip_app_build: true

...

inputs:
  app_location: 'src/dist'
  api_location: 'api'
  output_location: '' # Leave this empty
  skip_app_build: true
  azure_static_web_apps_api_token: $(deployment_token)

略過建置 API

如果您想要略過建置 API，您可以略過自動建置，並部署在上一個步驟中建置的 API。

略過建置 API 的步驟：

在 staticwebapp.config.json 檔案中，將設定apiRuntime為正確的運行時間和版本。如需支援的運行時間和版本清單，請參閱設定 Azure Static Web Apps 。
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
將 skip_api_build 設定為 true。
設定 api_location 為包含要部署之已建置 API 應用程式的資料夾。此路徑相對於 GitHub Actions 和 cwd Azure Pipelines 中的存放庫根目錄。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: "src" # App source code path relative to repository root
  api_location: "api" # Api source code path relative to repository root - optional
  output_location: "public" # Built app content directory, relative to app_location - optional
  skip_api_build: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

擴充建置逾時

根據預設，應用程式和 API 組建限制為 15 分鐘。您可以藉由設定 build_timeout_in_minutes 屬性來擴充建置逾時。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

執行沒有部署秘密的工作流程

有時候，即使遺漏某些秘密，您也需要工作流程繼續處理。若要將您的工作流程設定為繼續而不定義秘密，請將 SKIP_DEPLOY_ON_MISSING_SECRETS 環境變數設定為 true。

啟用時，這項功能可讓工作流程繼續執行，而不需要部署網站的內容。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

環境變數

您可以透過 env 作業組態的區段來設定組建的環境變數。

如需 Oryx 所使用之環境變數的詳細資訊，請參閱 Oryx 組態。

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Monorepo 支援

monorepo 是一個存放庫，其中包含多個應用程式的程序代碼。根據預設，工作流程會追蹤存放庫中的所有檔案，但您可以調整組態以以單一應用程式為目標。

若要將工作流程檔案設為單一應用程式，您可以在和 pull_request 區段中指定路徑push。

當您設定monorepo時，每個靜態應用程式組態的範圍僅限於單一應用程式的檔案。存放庫 . github/workflows 資料夾中的不同工作流程檔案會並存。

├── .github
│   └── workflows
│       ├── azure-static-web-apps-purple-pond.yml
│       └── azure-static-web-apps-yellow-shoe.yml
│
├── app1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md

下列範例示範如何將節點新增paths至名為 azure-static-web-apps-purple-pond.yml 之檔案的 push 和 pull_request 區段。

on:
  push:
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml

在此範例中，只有對下列檔案所做的變更會觸發新的組建：

app1 資料夾內的任何檔案
api1 資料夾內的任何檔案
應用程式azure-static-web-apps-purple-pond.yml工作流程檔案的變更

若要在單一存放庫中支援多個應用程式，請建立個別的工作流程檔案，並將它與不同的 Azure Pipelines 產生關聯。

下一步

在生產前環境中檢閱提取要求

共用方式為