Configurazione della compilazione per App Web statiche di Azure

La configurazione di compilazione App Web statiche di Azure usa GitHub Actions o Azure Pipelines. Ogni sito ha un file di configurazione YAML che controlla la modalità di compilazione e distribuzione di un sito. Questo articolo illustra la struttura e le opzioni del file.

Nella tabella seguente sono elencate le impostazioni di configurazione disponibili.

Proprietà	Descrizione	Richiesto
app_location	Questa cartella contiene il codice sorgente per l'applicazione front-end. Il valore è relativo alla radice del repository in GitHub e alla cartella di lavoro corrente in Azure DevOps. Se usato con skip_app_build: true, questo valore è il percorso di output della compilazione dell'app.	Sì
api_location	Cartella che contiene il codice sorgente per l'applicazione API. Il valore è relativo alla radice del repository in GitHub e alla cartella di lavoro corrente in Azure DevOps. Se usato con skip_api_build: true, questo valore è il percorso di output della compilazione dell'API.	No
output_location	Se l'app Web esegue un passaggio di compilazione, il percorso di output è la cartella in cui vengono generati i file pubblici. Per la maggior parte dei progetti, output_location fa riferimento a app_location. Tuttavia, per i progetti .NET, il percorso è relativo alla cartella di output.	No
app_build_command	Per Node.js applicazioni, è possibile definire un comando personalizzato per compilare l'applicazione contenuto statico. Ad esempio, per configurare una compilazione di produzione per un'applicazione Angular, creare uno script npm denominato build-prod per l'esecuzione ng build --prod e immettere npm run build-prod come comando personalizzato. Se lasciato vuoto, il flusso di lavoro tenterà di eseguire i comandi npm run build o npm run build:azure.	No
api_build_command	Per Node.js applicazioni, è possibile definire un comando personalizzato per compilare l'applicazione API Funzioni di Azure.	No
skip_app_build	Impostare il valore su true per ignorare la compilazione dell'app front-end.	No
skip_api_build	Impostare il valore su true per ignorare la compilazione delle funzioni API.	No
cwd (solo Azure Pipelines)	Percorso assoluto della cartella di lavoro. Il valore predefinito è $(System.DefaultWorkingDirectory).	No
build_timeout_in_minutes	Impostare questo valore per personalizzare il timeout di compilazione. Il valore predefinito è 15.	No

Con queste impostazioni, è possibile configurare GitHub Actions o Azure Pipelines per eseguire l'integrazione continua/recapito continuo (CI/CD) per l'app Web statica.

Nome e percorso del file

GitHub Actions

L'azione GitHub genera il file di configurazione e viene archiviato nella cartella .github/workflows , denominata usando il formato seguente: azure-static-web-apps-<RANDOM_NAME>.yml.

Azure Pipelines

Per impostazione predefinita, il file di configurazione viene archiviato nella radice del repository con il nome azure-pipelines.yml.

Configurazione della build

La configurazione di esempio seguente monitora il repository per individuare le modifiche. Man mano che viene eseguito il push dei commit nel main ramo, l'applicazione viene compilata dalla app_location cartella e dai file in output_location vengono serviti al Web pubblico. Inoltre, l'applicazione nella cartella api è disponibile nel percorso del api sito.

GitHub Actions

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 questa configurazione:

• Il main ramo viene monitorato per i commit.
• Un flusso di lavoro di GitHub Actions viene attivato quando una richiesta pull nel main ramo è aperta, sincronizzata, riaperta o chiusa.
• Viene build_and_deploy_job eseguito quando si esegue il push dei commit o si apre una richiesta pull sul ramo elencato nella on proprietà .
• Punta app_location alla src cartella che contiene i file di origine per l'app Web. Per impostare questo valore sulla radice del repository, usare /.
• Punta api_location alla api cartella che contiene l'applicazione Funzioni di Azure per gli endpoint API del sito. Per impostare questo valore sulla radice del repository, usare /.
• Punta output_location alla public cartella che contiene la versione finale dei file di origine dell'app. È relativo a app_location. Per i progetti .NET, il percorso è relativo alla cartella di output di pubblicazione.

Non modificare i valori per repo_token, actione azure_static_web_apps_api_token perché sono impostati per te da App Web statiche di Azure.

Il processo Chiudi richiesta pull chiude automaticamente la richiesta pull che ha attivato la compilazione e la distribuzione. Questo processo facoltativo non è necessario per il funzionamento del processo.

Quando viene aperta una richiesta pull, il App Web statiche di Azure GitHub Action compila e distribuisce l'app in un ambiente di staging. Successivamente, il processo Chiudi richiesta pull controlla se la richiesta pull è ancora aperta e la chiude con un messaggio di completamento.

Questo processo consente di mantenere organizzato il flusso di lavoro della richiesta pull e di evitare richieste pull non aggiornati. Chiudendo automaticamente la richiesta pull, il repository rimane aggiornato e il team riceve una notifica dello stato.

Il processo Chiudi richiesta pull fa parte del flusso di lavoro App Web statiche di Azure GitHub Actions, chiudendo la richiesta pull dopo che è stata unita. L'azione Azure/static-web-apps-deploy distribuisce l'app in App Web statiche di Azure, che richiede l'autenticazioneazure_static_web_apps_api_token.

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 questa configurazione:

• Il main ramo viene monitorato per i commit.
• Punta app_location alla src cartella che contiene i file di origine per l'app Web. Questo valore è relativo alla directory di lavoro (cwd). Per impostarlo sulla directory di lavoro, usare /.
• Punta api_location alla api cartella che contiene l'applicazione Funzioni di Azure per gli endpoint API del sito. Questo valore è relativo alla directory di lavoro (cwd). Per impostarlo sulla directory di lavoro, usare /.
• Punta output_location alla public cartella che contiene la versione finale dei file di origine dell'app. Questo valore è relativo a app_location. Per i progetti .NET, il percorso è relativo alla cartella di output.
• cwd è un percorso assoluto che punta alla directory di lavoro. Il valore predefinito è $(System.DefaultWorkingDirectory).
• La $(deployment_token) variabile punta al token di distribuzione di Azure DevOps generato.

Nota

app_location e api_location devono essere relativi alla directory di lavoro (cwd) e devono essere sottodirectory in cwd.

Comandi di compilazione personalizzati

Per le applicazioni Node.js, è possibile controllare con granularità fine sui comandi eseguiti durante il processo di compilazione dell'app o dell'API. Nell'esempio seguente viene illustrato come definire la compilazione con i valori per app_build_command e api_build_command.

Nota

Attualmente, è possibile definire app_build_command e api_build_command solo per Node.js compilazioni. Per specificare la versione Node.js, usare il engines campo nel package.json file.

GitHub Actions

...

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)

Ignorare la compilazione di un'app front-end

Se è necessario il controllo completo della compilazione per l'app front-end, è possibile ignorare la compilazione automatica e distribuire l'app compilata in un passaggio precedente.

Per ignorare la compilazione dell'app front-end:

• Impostare app_location sul percorso i file da distribuire.
• Impostare skip_app_build su true.
• Impostare output_location su una stringa vuota ('').

Nota

Assicurarsi di avere copiato anche il staticwebapp.config.json file nella directory di output .

GitHub Actions

...

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)

Ignorare la compilazione dell'API

Se si vuole ignorare la compilazione dell'API, è possibile ignorare la compilazione automatica e distribuire l'API compilata in un passaggio precedente.

Passaggi per ignorare la compilazione dell'API:

• Nel file staticwebapp.config.json impostare sul apiRuntime runtime e sulla versione corretti. Vedere Configurare App Web statiche di Azure per l'elenco di runtime e versioni supportate.

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

• Impostare skip_api_build su true.
• Impostare api_location sulla cartella contenente l'app per le API compilata da distribuire. Questo percorso è relativo alla radice del repository in GitHub Actions e cwd in Azure Pipelines.

GitHub Actions

...

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)

Estendere il timeout di compilazione

Per impostazione predefinita, le compilazioni di app e API sono limitate a 15 minuti. È possibile estendere il timeout di compilazione impostando la build_timeout_in_minutes proprietà .

GitHub Actions

...

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)

Eseguire il flusso di lavoro senza segreti di distribuzione

A volte è necessario che il flusso di lavoro continui a elaborare anche quando mancano alcuni segreti. Impostare la SKIP_DEPLOY_ON_MISSING_SECRETS variabile di ambiente su true per configurare il flusso di lavoro per continuare senza segreti definiti.

Se abilitata, questa funzionalità consente al flusso di lavoro di continuare senza distribuire il contenuto del sito.

GitHub Actions

...

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

Variabili di ambiente

È possibile impostare le variabili di ambiente per la compilazione tramite la env sezione della configurazione di un processo.

Per altre informazioni sulle variabili di ambiente usate da Oryx, vedere Configurazione di Oryx.

GitHub Actions

...

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

Supporto di Monorepo

Un monorepo è un repository che contiene codice per più di un'applicazione. Per impostazione predefinita, il flusso di lavoro tiene traccia di tutti i file in un repository, ma è possibile modificare la configurazione in modo da specificare come destinazione una singola app.

Per impostare come destinazione un file del flusso di lavoro in una singola app, specificare i percorsi nelle push sezioni e pull_request .

GitHub Actions

Quando si configura un monorepo, ogni configurazione di app statica ha come ambito solo i file per una singola app. I diversi file del flusso di lavoro si trovano affiancati nella cartella .github/workflows del repository.

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

Nell'esempio seguente viene illustrato come aggiungere un paths nodo alle push sezioni e pull_request di un file denominato 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

In questo esempio vengono attivate solo le modifiche apportate ai file seguenti:

• Tutti i file all'interno della cartella app1
• Tutti i file all'interno della cartella api1
• Modifiche al file del flusso di lavoro azure-static-web-apps-purple-pond.yml dell'app

Azure Pipelines

Per supportare più di un'applicazione in un singolo repository, creare un file di flusso di lavoro separato e associarlo a azure Pipelines diverse.

Passaggi successivi

Esaminare le richieste pull negli ambienti di pre-produzione