Konfiguracja kompilacji dla usługi Azure Static Web Apps

  • Artykuł

Konfiguracja kompilacji usługi Azure Static Web Apps jest obsługiwana przez funkcję GitHub Actions lub usługę 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: trueta 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: trueta 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 publikowania. 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

Plik konfiguracji jest generowany przez usługę GitHub i przechowywany w folderze .github/workflows o nazwie o następującym formacie: azure-static-web-apps-<RANDOM_NAME>.yml.

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 .

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.

Niestandardowe polecenia kompilacji

W przypadku aplikacji Node.js 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_commandapi_build_command.

Uwaga

Obecnie można definiować app_build_command tylko kompilacje Node.js i api_build_command dla tych kompilacji. 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'

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

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 poprawną wersję i środowisko uruchomieniowe. 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

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

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. Ustaw zmienną SKIP_DEPLOY_ON_MISSING_SECRETS środowiskową, aby true skonfigurować przepływ pracy do kontynuowania bez zdefiniowanych wpisów tajnych.

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

Zmienne środowiskowe

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

...

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

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

Następne kroki

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