Konfiguracja kompilacji dla usługi Azure Static Web Apps

Artykuł
11/05/2024

Konfiguracja kompilacji usługi Azure Static Web Apps korzysta z funkcji GitHub Actions lub usługi Azure Pipelines. Każda lokacja ma plik konfiguracji YAML, który kontroluje sposób tworzenia i wdrażania lokacji. W tym artykule opisano strukturę i opcje pliku.

W poniższej tabeli wymieniono dostępne ustawienia konfiguracji.

Właściwości	Opis	Wymagania
`app_location`	Ten folder zawiera kod źródłowy aplikacji frontonu. Wartość jest względna względem katalogu głównego repozytorium w usłudze GitHub i bieżącego folderu roboczego w usłudze Azure DevOps. W przypadku użycia z wartością `skip_app_build: true`ta wartość to lokalizacja wyjściowa kompilacji aplikacji.	Tak
`api_location`	Ten folder zawierający kod źródłowy aplikacji interfejsu API. Wartość jest względna względem katalogu głównego repozytorium w usłudze GitHub i bieżącego folderu roboczego w usłudze Azure DevOps. W przypadku użycia z wartością `skip_api_build: true`ta wartość to lokalizacja wyjściowa kompilacji interfejsu API.	Nie.
`output_location`	Jeśli aplikacja internetowa uruchamia krok kompilacji, lokalizacja wyjściowa to folder, w którym są generowane pliki publiczne. W przypadku większości projektów parametr `output_location` jest względny względem elementu `app_location`. Jednak w przypadku projektów .NET lokalizacja jest względna względem folderu wyjściowego.	Nie.
`app_build_command`	W przypadku aplikacji Node.js można zdefiniować niestandardowe polecenie w celu skompilowania aplikacji zawartości statycznej. Na przykład aby skonfigurować kompilację produkcyjną dla aplikacji Angular, utwórz skrypt npm o nazwie `build-prod` w celu uruchomienia `ng build --prod` i wprowadź `npm run build-prod` jako polecenie niestandardowe. Jeśli pole pozostanie puste, przepływ pracy spróbuje uruchomić `npm run build` polecenia lub `npm run build:azure` .	Nie.
`api_build_command`	W przypadku aplikacji Node.js można zdefiniować niestandardowe polecenie w celu skompilowania aplikacji interfejsu API usługi Azure Functions.	Nie.
`skip_app_build`	Ustaw wartość , aby `true` pominąć kompilowanie aplikacji frontonu.	Nie.
`skip_api_build`	Ustaw wartość , aby `true` pominąć kompilowanie funkcji interfejsu API.	Nie.
`cwd` (Tylko usługa Azure Pipelines)	Ścieżka bezwzględna do folderu roboczego. Wartość domyślna to `$(System.DefaultWorkingDirectory)`.	Nie.
`build_timeout_in_minutes`	Ustaw tę wartość, aby dostosować limit czasu kompilacji. Wartość domyślna to `15`.	Nie.

Te ustawienia umożliwiają skonfigurowanie funkcji GitHub Actions lub usługi Azure Pipelines w celu uruchamiania ciągłej integracji/ciągłego dostarczania (CI/CD) dla statycznej aplikacji internetowej.

Nazwa pliku i lokalizacja

Akcja usługi GitHub generuje plik konfiguracji i jest przechowywana w folderze .github/workflows o nazwie w następującym formacie: azure-static-web-apps-<RANDOM_NAME>.yml.

Domyślnie plik konfiguracji jest przechowywany w katalogu głównym repozytorium o nazwie azure-pipelines.yml.

Zabezpieczenia

Możesz wybrać między dwoma różnymi zasadami autoryzacji wdrożenia, aby zabezpieczyć konfigurację kompilacji. Usługa Static Web Apps obsługuje token wdrożenia platformy Azure (zalecane) lub token dostępu usługi GitHub.

Aby ustawić zasady autoryzacji wdrożenia w aplikacji, wykonaj następujące czynności:

Nowe aplikacje: podczas tworzenia statycznej aplikacji internetowej na karcie Konfiguracja wdrożenia wybierz zasady autoryzacji wdrożenia.
Istniejące aplikacje: aby zaktualizować istniejącą aplikację, przejdź do pozycji Konfiguracja konfiguracji> ustawień>i wybierz zasady autoryzacji wdrożenia.

Konfiguracja kompilacji

Poniższa przykładowa konfiguracja monitoruje repozytorium pod kątem zmian. W miarę main wypychania zatwierdzeń do gałęzi aplikacja jest kompilowana z app_location folderu, a pliki w folderze output_location są udostępniane publicznej sieci Web. Ponadto aplikacja w folderze interfejsu API jest dostępna w ścieżce witryny 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)

W tej konfiguracji:

Gałąź main jest monitorowana pod kątem zatwierdzeń.
src Wskazuje app_location folder zawierający pliki źródłowe aplikacji internetowej. Ta wartość jest względna względem katalogu roboczego (cwd). Aby ustawić go na katalog roboczy, użyj polecenia /.
api Wskazuje api_location folder zawierający aplikację usługi Azure Functions dla punktów końcowych interfejsu API witryny. Ta wartość jest względna względem katalogu roboczego (cwd). Aby ustawić go na katalog roboczy, użyj polecenia /.
public Wskazuje output_location folder zawierający ostateczną wersję plików źródłowych aplikacji. Ta wartość jest względna względem app_locationwartości . W przypadku projektów .NET lokalizacja jest względna względem folderu wyjściowego.
Jest cwd to ścieżka bezwzględna wskazująca katalog roboczy. Wartość domyślna to $(System.DefaultWorkingDirectory).
Zmienna $(deployment_token) wskazuje wygenerowany token wdrożenia usługi Azure DevOps.

Uwaga

app_locationi musi być względem katalogu roboczego () i api_location muszą być podkatalogami w obszarze cwd.cwd

Token wdrożenia platformy Azure
Token dostępu usługi 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"

W tej konfiguracji:

Gałąź main jest monitorowana pod kątem zatwierdzeń.
Przepływ pracy funkcji GitHub Actions jest wyzwalany po otwarciu, zsynchronizowaniu, ponownym otwarciu main lub zamknięciu żądania ściągnięcia.
Polecenie build_and_deploy_job jest wykonywane podczas wypychania zatwierdzeń lub otwierania żądania ściągnięcia względem gałęzi wymienionej on we właściwości .
src Wskazuje app_location folder zawierający pliki źródłowe aplikacji internetowej. Aby ustawić tę wartość na katalog główny repozytorium, użyj polecenia /.
api Wskazuje api_location folder zawierający aplikację usługi Azure Functions dla punktów końcowych interfejsu API witryny. Aby ustawić tę wartość na katalog główny repozytorium, użyj polecenia /.
public Wskazuje output_location folder zawierający ostateczną wersję plików źródłowych aplikacji. Jest to względne względem app_location. W przypadku projektów .NET lokalizacja jest względna względem folderu wyjściowego publikowania.

Nie zmieniaj wartości parametrów repo_token, actioni azure_static_web_apps_api_token w miarę ich ustawiania przez usługę Azure Static Web Apps.

Zadanie Zamknij żądanie ściągnięcia automatycznie zamyka żądanie ściągnięcia, które wyzwoliło kompilację i wdrożenie. To opcjonalne zadanie nie jest wymagane, aby proces działał.

Po otwarciu żądania ściągnięcia akcja GitHub usługi Azure Static Web Apps kompiluje i wdraża aplikację w środowisku przejściowym. Następnie zadanie Zamknij żądanie ściągnięcia sprawdza, czy żądanie ściągnięcia jest nadal otwarte i zamyka je z komunikatem ukończenia.

To zadanie ułatwia organizowanie przepływu pracy żądania ściągnięcia i zapobieganie nieaktualnym żądaniom ściągnięcia. Przez środowisko uruchomieniowe automatycznie zamyka żądanie ściągnięcia repozytorium pozostaje aktualne, a twój zespół jest powiadamiany o stanie.

Zadanie Zamknij żądanie ściągnięcia jest częścią przepływu pracy funkcji GitHub Actions usługi Azure Static Web Apps, zamykając żądanie ściągnięcia po scaleniu. Akcja Azure/static-web-apps-deploy wdraża aplikację w usłudze Azure Static Web Apps, co wymaga azure_static_web_apps_api_token uwierzytelnienia.

Niestandardowe polecenia kompilacji

W przypadku Node.js aplikacji możesz kontrolować dokładnie to, jakie polecenia są uruchamiane podczas procesu kompilacji aplikacji lub interfejsu API. W poniższym przykładzie pokazano, jak zdefiniować kompilację za pomocą wartości i app_build_command api_build_command.

Uwaga

Obecnie można definiować app_build_command api_build_command tylko kompilacje i dla Node.js. Aby określić wersję Node.js, użyj engines pola w package.json pliku .

...

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)

Pomijanie tworzenia aplikacji frontonu

Jeśli potrzebujesz pełnej kontroli nad kompilacją dla aplikacji frontonu, możesz pominąć automatyczną kompilację i wdrożyć aplikację wbudowaną w poprzednim kroku.

Aby pominąć tworzenie aplikacji frontonu:

Ustaw app_location na lokalizację plików, które chcesz wdrożyć.
Ustaw wartość opcji skip_app_build na true.
Ustaw output_location wartość pustego ciągu ('').

Uwaga

Upewnij się, że plik został staticwebapp.config.json również skopiowany do katalogu wyjściowego.

...

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)

Pomijanie kompilowania interfejsu API

Jeśli chcesz pominąć tworzenie interfejsu API, możesz pominąć automatyczną kompilację i wdrożyć interfejs API wbudowany w poprzednim kroku.

Kroki pominięcia tworzenia interfejsu API:

W pliku staticwebapp.config.json ustaw apiRuntime odpowiednie środowisko uruchomieniowe i wersję. Zobacz Konfigurowanie usługi Azure Static Web Apps, aby uzyskać listę obsługiwanych środowisk uruchomieniowych i wersji.
```
{
  "platform": {
    "apiRuntime": "node:16"
  }
}
```
Ustaw wartość opcji skip_api_build na true.
Ustaw api_location folder zawierający utworzoną aplikację interfejsu API do wdrożenia. Ta ścieżka jest względna względem katalogu głównego repozytorium w funkcji GitHub Actions i cwd w usłudze 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

...

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

Rozszerzanie limitu czasu kompilacji

Domyślnie kompilacje aplikacji i interfejsu API są ograniczone do 15 minut. Limit czasu kompilacji można przedłużyć, ustawiając build_timeout_in_minutes właściwość .

...

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)

Uruchamianie przepływu pracy bez wpisów tajnych wdrożenia

Czasami potrzebujesz przepływu pracy, aby kontynuować przetwarzanie nawet wtedy, gdy brakuje niektórych wpisów tajnych. Aby skonfigurować przepływ pracy do kontynuowania bez zdefiniowanych wpisów tajnych, ustaw zmienną SKIP_DEPLOY_ON_MISSING_SECRETS środowiskową na true.

Po włączeniu ta funkcja umożliwia kontynuowanie przepływu pracy bez wdrażania zawartości witryny.

...

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

Zmienne środowiskowe

Zmienne środowiskowe kompilacji można ustawić za pomocą env sekcji konfiguracji zadania.

Aby uzyskać więcej informacji na temat zmiennych środowiskowych używanych przez oryx, zobacz Konfiguracja 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

Obsługa platformy Monorepo

Monorepo to repozytorium zawierające kod dla więcej niż jednej aplikacji. Domyślnie przepływ pracy śledzi wszystkie pliki w repozytorium, ale można dostosować konfigurację tak, aby dotyczyła jednej aplikacji.

Aby wskazać plik przepływu pracy dla pojedynczej aplikacji, należy określić ścieżki w push sekcjach i pull_request .

Podczas konfigurowania monorepo każda konfiguracja statycznej aplikacji jest ograniczona tylko do plików dla jednej aplikacji. Różne pliki przepływu pracy działają obok siebie w folderze .github/workflows repozytorium.

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

W poniższym przykładzie pokazano, jak dodać paths węzeł do push sekcji i pull_request pliku o nazwie 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

W tym przykładzie tylko zmiany wprowadzone w następujących plikach wyzwalają nową kompilację:

Wszystkie pliki w folderze app1
Wszystkie pliki w folderze api1
Zmiany w pliku przepływu pracy azure-static-web-apps-purple-pond.yml aplikacji

Aby obsługiwać więcej niż jedną aplikację w jednym repozytorium, utwórz oddzielny plik przepływu pracy i skojarz go z różnymi usługami Azure Pipelines.

Następne kroki

Przeglądanie żądań ściągnięcia w środowiskach przedprodukcyjnych

Udostępnij za pośrednictwem

Konfiguracja kompilacji dla usługi Azure Static Web Apps

Nazwa pliku i lokalizacja

Zabezpieczenia

Konfiguracja kompilacji

Niestandardowe polecenia kompilacji

Pomijanie tworzenia aplikacji frontonu

Pomijanie kompilowania interfejsu API

Rozszerzanie limitu czasu kompilacji

Uruchamianie przepływu pracy bez wpisów tajnych wdrożenia

Zmienne środowiskowe

Obsługa platformy Monorepo

Następne kroki

Opinia

Dodatkowe zasoby