Конфигурация сборки для Статические веб-приложения Azure

  • Статья

Конфигурация сборки Статические веб-приложения Azure работает с помощью 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 Если веб-приложение запускает шаг сборки, выходное расположение — это папка, в которой создаются общедоступные файлы. Для большинства проектов output_location относительно app_location. Однако для проектов .NET расположение относительно выходной папки публикации. Нет
app_build_command Для приложений Node.js можно определить пользовательскую команду для создания приложения статического содержимого.

Например, чтобы настроить рабочую сборку для приложения Angular, создайте скрипт npm с именем build-prod, который запускает ng build --prod, и введите настраиваемую команду npm run build-prod. Если оставить это поле пустым, рабочий процесс попытается выполнить команды npm run build или npm run build:azure.		 Нет
api_build_command Для приложений Node.js можно определить пользовательскую команду для создания приложения API Функции Azure. Нет
skip_app_build Установите значение true, чтобы пропустить сборку интерфейсного приложения. Нет
skip_api_build Задайте значение, чтобы true пропустить сборку функций API. Нет
cwd
(Только Azure Pipelines)		 Абсолютный путь к рабочей папке. По умолчанию — $(System.DefaultWorkingDirectory). Нет
build_timeout_in_minutes Задайте это значение, чтобы настроить время ожидания сборки. По умолчанию — 15. Нет

С помощью этих параметров можно настроить GitHub Actions или Azure Pipelines для выполнения непрерывной интеграции и непрерывной доставки (CI/CD) для статического веб-приложения.

Имя файла и расположение

Файл конфигурации создается GitHub и хранится в папке github/workflows с именем в следующем формате: azure-static-web-apps-<RANDOM_NAME>.yml

Конфигурация построения

В следующем примере конфигурации отслеживается репозиторий для изменений. При отправке main фиксаций в ветвь приложение создается из app_location папки и файлов в интернете output_location . Кроме того, приложение в папке 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 отслеживается для фиксаций.
  • Рабочий процесс GitHub Actions активируется при запросе на вытягивание в main ветви: открытый, синхронизированный, вновь открытый или закрытый.
  • Выполняется build_and_deploy_job при отправке фиксаций или открытии запроса на вытягивание в ветви, указанной в свойстве on .
  • Указывает app_location на src папку, содержащую исходные файлы для веб-приложения. Чтобы задать это значение корневому каталогу репозитория, используйте /.
  • Указывает api_location на api папку, содержащую приложение Функции Azure для конечных точек API сайта. Чтобы задать это значение корневому каталогу репозитория, используйте /.
  • Указывает output_location на public папку, содержащую окончательную версию исходных файлов приложения. Это относительно app_location. Для проектов .NET расположение относится к папке выходных данных публикации.

Не изменяйте значения для repo_token, actionи azure_static_web_apps_api_token по мере их установки Статические веб-приложения Azure.

Команды настраиваемой сборки

Для приложений Node.js можно точно контролировать выполнение команд во время сборки приложения или API. В следующем примере показано, как определить сборку со значениями и app_build_commandapi_build_command.

Примечание.

В настоящее время можно определить app_build_command только сборки Node.js и api_build_command только для нее. Чтобы указать версию 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 для списка поддерживаемых сред выполнения и версий. 
    {
  "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

Запуск рабочего процесса без секретов развертывания

Иногда вам нужно, чтобы рабочий процесс продолжал обрабатываться, даже если отсутствуют некоторые секреты. Задайте переменную среды, чтобы true настроить рабочий SKIP_DEPLOY_ON_MISSING_SECRETS процесс для продолжения без определенных секретов.

При включении эта функция позволяет рабочему процессу продолжать работу без развертывания содержимого сайта.

...

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.

При настройке 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 в разделы push и pull_request файла с именем azure-static-web-apps-purple-pond.yml.

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 для приложения

Следующие шаги

Проверка запросов на вытягивание в подготовительных средах