Konfiguracja kompilacji dla usługi Azure Static Web Apps
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
Wskazujeapp_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
Wskazujeapi_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
Wskazujeoutput_location
folder zawierający ostateczną wersję plików źródłowych aplikacji. Ta wartość jest względna względemapp_location
wartoś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_location
i musi być względem katalogu roboczego () i api_location
muszą być podkatalogami w obszarze cwd
.cwd
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"
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 wymienionejon
we właściwości . src
Wskazujeapp_location
folder zawierający pliki źródłowe aplikacji internetowej. Aby ustawić tę wartość na katalog główny repozytorium, użyj polecenia/
.api
Wskazujeapi_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
Wskazujeoutput_location
folder zawierający ostateczną wersję plików źródłowych aplikacji. Jest to względne względemapp_location
. W przypadku projektów .NET lokalizacja jest względna względem folderu wyjściowego publikowania.
Nie zmieniaj wartości parametrów repo_token
, action
i 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
natrue
. - 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
natrue
.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 icwd
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.