Build-Konfiguration für Azure Static Web Apps

Die Azure Static Web Apps-Buildkonfiguration wird entweder von GitHub Actions oder von Azure Pipelines unterstützt. Jede Site hat eine YAML-Konfigurationsdatei, die steuert, wie eine Site erstellt und bereitgestellt wird. In diesem Artikel werden Struktur und Optionen der Datei erläutert.

In der folgenden Tabelle sind die verfügbaren Konfigurationseinstellungen aufgeführt.

Eigenschaft	Beschreibung	Erforderlich
app_location	In diesem Ordner befindet sich der Quellcode für Ihre Front-End-Anwendung. Der Wert ist relativ zum Stamm des Repositorys in GitHub und dem aktuellen Arbeitsordner in Azure DevOps. Bei Verwendung mit skip_app_build: true handelt es sich bei diesem Wert um den Buildausgabespeicherort der App.	Ja
api_location	Dieser Ordner enthält den Quellcode für Ihre API-Anwendung. Der Wert ist relativ zum Stamm des Repositorys in GitHub und dem aktuellen Arbeitsordner in Azure DevOps. Bei Verwendung mit skip_api_build: true handelt es sich bei diesem Wert um den Buildausgabespeicherort der API.	Nein
output_location	Wenn Ihre Webanwendung einen Build-Schritt ausführt, ist der Ausgabeort der Ordner, in dem die öffentlichen Dateien generiert werden. Bei den meisten Projekten ist der output_location relativ zum app_location. Bei .NET-Projekten ist der Speicherort jedoch relativ zum Ausgabeordner für die Veröffentlichung.	Nein
app_build_command	Für Node.js-Anwendungen können Sie einen benutzerdefinierten Befehl definieren, um die Anwendung mit statischen Inhalten zu erstellen. Wenn Sie beispielsweise einen Produktionsbuild für eine Angular-Anwendung konfigurieren möchten, erstellen Sie ein npm-Skript mit dem Namen build-prod, um ng build --prod auszuführen, und geben Sie npm run build-prod als benutzerdefinierten Befehl ein. Wenn Sie das Feld leer lassen, versucht der Workflow, den Befehl npm run build oder npm run build:azure auszuführen.	Nein
api_build_command	Für Node.js-Anwendungen können Sie einen benutzerdefinierten Befehl definieren, um die Azure Functions API-Anwendung zu erstellen.	Nein
skip_app_build	Legen Sie den Wert auf true fest, um das Erstellen der Front-End-App zu überspringen.	Nein
skip_api_build	Legen Sie den Wert auf true fest, um das Erstellen der API-Funktionen zu überspringen.	Nein
cwd (Nur Azure Pipelines)	Absoluter Pfad zum Arbeitsordner. Wird standardmäßig auf $(System.DefaultWorkingDirectory) festgelegt.	Nein
build_timeout_in_minutes	Legen Sie diesen Wert fest, um das Buildtimeout anzupassen. Wird standardmäßig auf 15 festgelegt.	Nein

Mit diesen Einstellungen können Sie GitHub Actions oder Azure Pipelines einrichten, um kontinuierliche Integration/kontinuierliche Bereitstellung (CI/CD) für Ihre statische Webanwendung durchzuführen.

Dateiname und Speicherort

GitHub-Aktionen

Die Konfigurationsdatei wird von GitHub generiert und im Ordner .github/workflows gespeichert, der nach folgendem Format benannt ist: azure-static-web-apps-<RANDOM_NAME>.yml.

Azure Pipelines

Standardmäßig wird die Konfigurationsdatei im Stammverzeichnis Ihres Repositorys unter dem Namen azure-pipelines.yml gespeichert.

Buildkonfiguration

In der folgenden Beispielkonfiguration wird das Repository auf Änderungen überwacht. Wenn Commits in den main-Zweig gepusht werden, wird die Anwendung im app_location-Ordner erstellt und die Dateien im output_location-Ordner werden im öffentlichen Web bereitgestellt. Außerdem ist die Anwendung im Ordner api unter dem Pfad api der Website verfügbar.

GitHub-Aktionen

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"

In dieser Konfiguration:

• Der main Zweig wird auf Commits überwacht.
• Ein GitHub Actions-Workflow wird ausgelöst, wenn eine Pull-Anforderung auf dem main Zweig: geöffnet, synchronisiert, erneut geöffnet oder geschlossen wird.
• Die build_and_deploy_job wird ausgeführt, wenn Sie Commits pushen oder eine Pull Anforderung gegen den in der on Eigenschaft aufgeführten Zweig öffnen.
• Der app_location verweist auf den Ordner src, der die Quelldateien für die Webanwendung enthält. Verwenden Sie /, um diesen Wert auf den Repositorystamm festzulegen.
• Der api_location verweist auf den Ordner api, der die Azure Functions-Anwendung für die API-Endpunkte der Website enthält. Verwenden Sie /, um diesen Wert auf den Repositorystamm festzulegen.
• Der output_location verweist auf den Ordner public, der die endgültige Version der Quelldateien der App enthält. Er ist relativ zu app_location. Bei .NET-Projekten ist der Speicherort relativ zum Ausgabeordner für die Veröffentlichung.

Bitte ändern Sie die Werte für repo_token, action und azure_static_web_apps_api_token nicht, da sie von Azure Static Web Apps für Sie festgelegt werden.

Azure Pipelines

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)

In dieser Konfiguration:

• Der main Zweig wird auf Commits überwacht.
• Der app_location verweist auf den Ordner src, der die Quelldateien für die Webanwendung enthält. Dieser Wert ist relativ zum Arbeitsverzeichnis (cwd). Verwenden Sie /, um ihn auf das Arbeitsverzeichnis festzulegen.
• Der api_location verweist auf den Ordner api, der die Azure Functions-Anwendung für die API-Endpunkte der Website enthält. Dieser Wert ist relativ zum Arbeitsverzeichnis (cwd). Verwenden Sie /, um ihn auf das Arbeitsverzeichnis festzulegen.
• Der output_location verweist auf den Ordner public, der die endgültige Version der Quelldateien der App enthält. Dieser Wert ist relativ zu app_location. Bei .NET-Projekten ist der Speicherort relativ zum Ausgabeordner für die Veröffentlichung.
• cwd ist ein absoluter Pfad, der auf das Arbeitsverzeichnis verweist. Es ist standardmäßig $(System.DefaultWorkingDirectory).
• Die Variable $(deployment_token) verweist auf das generierte Azure DevOps Bereitstellungs-Token

Hinweis

app_location and api_location müssen relativ zum Arbeitsverzeichnis (cwd) sein, und sie müssen Unterverzeichnisse unter cwd sein.

Benutzerdefinierte Buildbefehle

Für Node.js-Anwendungen können Sie genau steuern, welche Befehle während des Build-Prozesses der App oder API ausgeführt werden. Das folgende Beispiel zeigt, wie man Build mit Werten für app_build_command und api_build_command definiert.

Hinweis

Derzeit können Sie nur app_build_command und api_build_command für Node.js-Builds definieren. Verwenden Sie das Feld engines in der Datei package.json, um die Node.js Version anzugeben.

GitHub-Aktionen

...

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'

Azure Pipelines

...

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)

Überspringen des Erstellens einer Front-End-App

Wenn Sie die volle Kontrolle über die Erstellung Ihrer Front-End-Anwendung benötigen, können Sie die automatische Erstellung umgehen und die in einem vorherigen Schritt erstellte Anwendung bereitstellen.

So überspringen Sie die Erstellung der Front-End-Anwendung:

• Setzen Sie app_location auf den Speicherort der Dateien, die Sie bereitstellen möchten.
• Legen Sie skip_app_build auf true fest.
• Setzen Sie output_location auf eine leere Zeichenkette ('').

Hinweis

Stellen Sie sicher, dass Sie Ihre staticwebapp.config.json-Datei auch in das output-Verzeichnis (Ausgabe) kopiert haben.

GitHub-Aktionen

...

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

Azure Pipelines

...

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)

Überspringen des Erstellens der API

Wenn Sie das Erstellen der API überspringen möchten, können Sie den automatischen Build umgehen und die in einem vorherigen Schritt integrierte API bereitstellen.

Schritte zum Überspringen des Erstellens der API:

• Legen Sie in der Datei staticwebapp.config.json die Eigenschaft apiRuntime auf die richtige Runtime und Version fest. Die Liste der unterstützten Runtimes und Versionen finden Sie unter Konfigurieren von Azure Static Web Apps.

  {
    "platform": {
      "apiRuntime": "node:16"
    }
  }
  

• Legen Sie skip_api_build auf true fest.
• Legen Sie api_location auf den Ordner fest, der die erstellte API-App enthält, die bereitgestellt werden soll. Dieser Pfad ist relativ zum Repositorystamm in GitHub Actions und cwd in Azure Pipelines.

GitHub-Aktionen

...

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

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Verlängern des Buildtimeouts

Standardmäßig sind die App- und API-Builds auf 15 Minuten beschränkt. Sie können das Buildtimeout verlängern, indem Sie die build_timeout_in_minutes-Eigenschaft festlegen.

GitHub-Aktionen

...

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

Azure Pipelines

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

Ausführen von Workflows ohne geheime Bereitstellungsschlüssel

Manchmal müssen Sie Ihren Workflow auch dann weiter verarbeiten, wenn einige geheime Schlüssel fehlen. Legen Sie die SKIP_DEPLOY_ON_MISSING_SECRETS Umgebungsvariable fest, um den Workflow so zu true konfigurieren, dass er ohne definierte geheime Schlüssel fortgesetzt wird.

Wenn diese Funktion aktiviert ist, kann der Workflow fortgesetzt werden, ohne den Inhalt der Website bereitzustellen.

GitHub-Aktionen

...

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

Azure Pipelines

...

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

Umgebungsvariablen

Umgebungsvariablen für Ihren Build können über den Abschnitt env einer Auftragskonfiguration festgelegt werden.

GitHub-Aktionen

...

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

Azure Pipelines

...

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

Unterstützung für Monorepos

Ein Monorepo ist ein Repository, das Code für mehr als eine Anwendung enthält. Der Workflow verfolgt standardmäßig alle Dateien in einem Repository nach, aber Sie können die Konfiguration so anpassen, dass eine einzelne App als Ziel verwendet wird.

Geben Sie die Pfade in den Abschnitten push und pull_request an, um für eine Workflowdatei eine einzelne App als Ziel festzulegen.

GitHub-Aktionen

Wenn Sie eine Monorepo einrichten, ist jede statische Anwendungskonfiguration nur auf Dateien für eine einzige Anwendung beschränkt. Die verschiedenen Workflowdateien befinden sich gemeinsam im Ordner .github/workflows des Repositorys.

├── .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

Im folgenden Beispiel wird veranschaulicht, wie Sie einen paths-Knoten zu den Abschnitten push und pull_request einer Datei namens azure-static-web-apps-purple-pond.yml hinzufügen.

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

In diesem Beispiel lösen nur Änderungen an den folgenden Dateien einen neuen Build aus:

• alle Dateien im Ordner app1
• alle Dateien im Ordner api1
• Änderungen an der Workflowdatei azure-static-web-apps-purple-pond.yml der App

Azure Pipelines

Um mehr als eine Anwendung in einem einzigen Repository zu unterstützen, erstellen Sie eine separate Workflow-Datei und verknüpfen Sie mit verschiedenen Azure Pipelines.

Nächste Schritte

Überprüfen von Pull Requests in Präproduktionsumgebungen