你当前正在访问 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 buildnpm 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_tokenactionazure_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_commandapi_build_command 的值定义生成。

注意

目前,只能为 Node.js 生成定义 app_build_commandapi_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 节为生成设置环境变量。

有关 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

单存储库支持

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

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

后续步骤