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

为 Azure Static Web Apps 生成配置

  • 项目

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。

生成配置

以下示例配置监视存储库中的更改。 将提交推送到 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 工作流。
  • 针对 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 为你设置的。

自定义生成命令

对于 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'

跳过前端应用的生成

如果需要完全控制前端应用的生成，可以绕过自动生成，部署在前面的某个步骤生成的应用。

若要跳过生成前端应用，请执行以下操作：

  • 将 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 中的存储库根路径和 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

延长生成超时

默认情况下，应用程序和 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 节为生成设置环境变量。

...

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

单存储库支持

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

若要将工作流文件定位到单个应用，请在 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 工作流文件

后续步骤

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