你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 Azure Static Web Apps 生成配置

项目
11/06/2024

Azure Static Web Apps 生成配置使用 GitHub Actions 或 Azure Pipelines。每个站点都有一个 YAML 配置文件，用于控制如何生成和部署站点。本文介绍文件的结构和选项。

下表列出了可用配置设置。

属性	描述	必需
`app_location`	此文件夹包含前端应用程序的源代码。此值是相对于 GitHub 中的存储库根目录和 Azure DevOps 中的当前工作文件夹的值。与 `skip_app_build: true` 一起使用时，此值是应用的生成输出位置。	是
`api_location`	此文件夹包含 API 应用程序的源代码。此值是相对于 GitHub 中的存储库根目录和 Azure DevOps 中的当前工作文件夹的值。与 `skip_api_build: true` 一起使用时，此值是 API 的生成输出位置。	否
`output_location`	如果 Web 应用运行生成步骤，则输出位置是生成公共文件的文件夹。对于大多数项目，`output_location` 是相对于 `app_location` 的。但是，对于 .NET 项目，该位置相对于输出文件夹。	否
`app_build_command`	对于 Node.js 应用程序，可以定义用于生成静态内容应用程序的自定义命令。例如，若要为 Angular 应用程序配置生产版本，请创建一个名为 `build-prod` 的 npm 脚本，以运行 `ng build --prod` 并输入 `npm run build-prod` 作为自定义命令。如果留空，工作流将尝试运行 `npm run build` 或 `npm run build:azure` 命令。	否
`api_build_command`	对于 Node.js 应用程序，可以定义用于生成 Azure Functions API 应用程序的自定义命令。	否
`skip_app_build`	将值设置为 `true` 以跳过生成前端应用。	否
`skip_api_build`	将值设置为 `true` 以跳过生成 API 函数。	否
`cwd` （仅限 Azure Pipelines）	工作文件夹的绝对路径。默认为 `$(System.DefaultWorkingDirectory)`。	否
`build_timeout_in_minutes`	设置此值可自定义生成超时。默认为 `15`。	否

使用这些设置，可以设置 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_location 指向包含 Web 应用源文件的 src 文件夹。此值相对于工作目录 (cwd)。若要将其设置为工作目录，请使用 /。
api_location 指向包含站点 API 终结点的 Azure Functions 应用程序的 api 文件夹。此值相对于工作目录 (cwd)。若要将其设置为工作目录，请使用 /。
output_location 指向包含应用源文件的最终版本的 public 文件夹。此值是相对于 app_location。对于 .NET 项目，该位置相对于输出文件夹。
cwd 是指向工作目录的绝对路径。默认为 $(System.DefaultWorkingDirectory)。
$(deployment_token) 变量指向生成的 Azure DevOps 部署令牌。

注意

app_location 和 api_location 必须相对于工作目录 (cwd)，它们必须是 cwd 下的子目录。

Azure 部署令牌
GitHub 访问令牌

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 工作流。
针对 on 属性中列出的分支推送提交或打开拉取请求时，build_and_deploy_job 会执行。
app_location 指向包含 Web 应用源文件的 src 文件夹。若要将此值设置为存储库根，请使用 /。
api_location 指向包含站点 API 终结点的 Azure Functions 应用程序的 api 文件夹。若要将此值设置为存储库根，请使用 /。
output_location 指向包含应用源文件的最终版本的 public 文件夹。它是相对于的 app_location。但是，对于 .NET 项目，该位置是相对于发布输出文件夹的。

请勿更改 repo_token、action 和 azure_static_web_apps_api_token 的值，因为它们是 Azure Static Web Apps 为你设置的。

“关闭拉取请求”作业自动关闭触发生成和部署的拉取请求。无需此可选作业也能使流程正常运行。

打开拉取请求时，Azure Static Web Apps GitHub Actions 会生成应用并将其部署到过渡环境。随后，“关闭拉取请求”作业将检查拉取请求是否仍处于打开状态，关闭该作业并返回完成消息。

此作业有助于保持拉取请求工作流井然有序，并防止拉取请求过时。通过运行时自动关闭拉取请求，存储库将保持最新状态，并且团队会收到状态通知。

“关闭拉取请求”作业是 Azure Static Web Apps GitHub Actions 工作流的一部分，用于在合并后关闭拉取请求。 Azure/static-web-apps-deploy 操作将应用部署到 Azure Static Web Apps，这需要 azure_static_web_apps_api_token 进行身份验证。

自定义生成命令

对于 Node.js 应用程序，可以精细控制在应用或 API 生成过程中运行的命令。下面的示例演示如何使用 app_build_command 和 api_build_command 的值定义生成。

注意

目前，只能为 Node.js 生成定义 app_build_command 和 api_build_command。若要指定 Node.js 版本，请使用 package.json 文件中的 engines 字段。

...

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 中的存储库根路径和 Azure Pipelines 中的 cwd。

...

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

单存储库支持

单存储库是包含多个应用程序的代码的存储库。默认情况下，工作流会跟踪存储库中的所有文件，但你可以调整配置以针对单个应用。

若要将工作流文件定位到单个应用，请在 push 和 pull_request 节中指定路径。

设置单存储库时，每个静态应用配置的范围局限于单个应用的文件。不同工作流文件并排放置在存储库的“.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 相关联。

后续步骤

查看预生产环境中的拉取请求

通过