分享方式:


建置 Azure Static Web Apps 的組態

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 buildnpm 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

組建組態

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

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 專案,位置相對於發佈輸出資料夾。

請勿變更、 actionazure_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_commandapi_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'

略過建置前端應用程式

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

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

  • 設定 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

略過建置 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

擴充建置逾時

根據預設,應用程式和 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

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

有時候,即使遺漏某些秘密,您也需要工作流程繼續處理。 將 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

環境變數

您可以透過 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

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 之檔案的 pushpull_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工作流程檔案的變更

下一步