Bangun konfigurasi untuk Azure Static Web Apps

Konfigurasi build Azure Static Web Apps didukung oleh GitHub Actions atau Azure Pipelines. Setiap situs memiliki file konfigurasi YAML yang mengontrol bagaimana sebuah situs dibangun dan digunakan. Artikel ini menjelaskan struktur dan opsi file.

Tabel berikut mencantumkan pengaturan konfigurasi yang tersedia.

Properti	Deskripsi	Wajib diisi
app_location	Folder ini berisi kode sumber untuk aplikasi front-end Anda. Nilai ini relatif terhadap root repositori di GitHub dan folder kerja saat ini di Azure DevOps. Saat digunakan dengan skip_app_build: true, nilai ini adalah lokasi output build aplikasi.	Ya
api_location	Folder ini yang berisi kode sumber untuk aplikasi API Anda. Nilai ini relatif terhadap root repositori di GitHub dan folder kerja saat ini di Azure DevOps. Saat digunakan dengan skip_api_build: true, nilai ini adalah lokasi output build API.	Tidak
output_location	Jika aplikasi web Anda menjalankan langkah build, lokasi output adalah folder tempat file publik dihasilkan. Untuk sebagian besar proyek, output_location relatif terhadap app_location. Namun, untuk proyek .NET, lokasinya relatif terhadap folder output publikasi.	Tidak
app_build_command	Untuk aplikasi Node.js, Anda dapat menentukan perintah khusus untuk membangun aplikasi konten statis. Misalnya, untuk mengonfigurasi build produksi untuk aplikasi Angular, buat skrip npm bernama build-prod untuk menjalankanng build --prod dan masukkan npm run build-prod sebagai perintah kustom. Jika dibiarkan kosong, alur kerja mencoba menjalankan perintah npm run build atau npm run build:azure.	Tidak
api_build_command	Untuk aplikasi Node.js, Anda dapat menentukan perintah kustom untuk membangun aplikasi Azure Functions API.	Tidak
skip_app_build	Atur nilai ke true untuk melewati pembuatan aplikasi front-end.	Tidak
skip_api_build	Atur nilai ke true untuk melewati pembuatan fungsi API.	Tidak
cwd (Hanya Azure Pipelines)	Jalur absolut ke folder kerja. Default ke $(System.DefaultWorkingDirectory).	Tidak
build_timeout_in_minutes	Atur nilai ini untuk menyesuaikan batas waktu build. Default ke 15.	Tidak

Dengan pengaturan ini, Anda dapat mengatur GitHub Actions atau Azure Pipelines untuk menjalankan continuous integration/continuous delivery (CI/CD) untuk aplikasi web statis Anda.

Nama dan lokasi file

GitHub Actions

File konfigurasi dihasilkan oleh GitHub dan disimpan dalam folder .github/workflows dinamai menggunakan format berikut: azure-static-web-apps-<RANDOM_NAME>.yml.

Alur Azure

Secara default, file konfigurasi disimpan di akar repositori Anda dengan nama azure-pipelines.yml.

Konfigurasi build

Konfigurasi sampel berikut memantau repositori untuk perubahan. Saat commits didorong ke main cabang, aplikasi ini dibangun dari app_location folder dan file di dilayani ke web output_location publik. Selain itu, aplikasi dalam folder api tersedia di bawah api jalur situs.

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"

Dalam konfigurasi ini:

• Bagian main dipantau untuk berkomitmen.
• Alur kerja tindakan GitHub dipicu saat permintaan tarik pada bagian main adalah: dibuka, disinkronkan, dibuka kembali, atau ditutup.
• build_and_deploy_job mengeksekusi saat Anda mendorong penerapan atau membuka permintaan pull terhadap cabang yang tercantum di properti on.
• Titik app_location ke src folder yang berisi file sumber untuk aplikasi web. Untuk mengatur nilai ini ke akar repositori, gunakan /.
• Titik-titik api_location ke folder api yang berisi aplikasi Azure Functions untuk titik akhir API situs. Untuk mengatur nilai ini ke akar repositori, gunakan /.
• Titik output_location ke folder public yang berisi versi final file sumber aplikasi. Ini relatif terhadap app_location. Untuk proyek .NET, lokasi relatif terhadap folder terbitkan output.

Jangan ubah nilai untuk repo_token, action, dan azure_static_web_apps_api_token karena nilai itu ditetapkan untuk Anda oleh Azure Static Web Apps.

Alur Azure

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)

Dalam konfigurasi ini:

• Bagian main dipantau untuk berkomitmen.
• Titik app_location ke src folder yang berisi file sumber untuk aplikasi web. Nilai ini relatif terhadap direktori kerja (cwd). Untuk mengaturnya ke direktori kerja, gunakan /.
• Titik-titik api_location ke folder api yang berisi aplikasi Azure Functions untuk titik akhir API situs. Nilai ini relatif terhadap direktori kerja (cwd). Untuk mengaturnya ke direktori kerja, gunakan /.
• Titik output_location ke folder public yang berisi versi final file sumber aplikasi. Nilai ini relatif terhadap app_location. Untuk proyek .NET, lokasi relatif terhadap folder terbitkan output.
• cwd adalah jalur absolut yang menunjuk ke direktori kerja. Ini default ke $(System.DefaultWorkingDirectory).
• Variabel $(deployment_token) menunjuk ke token penyebaran Azure DevOps yang dihasilkan.

Catatan

app_location dan api_location harus relatif terhadap direktori kerja (cwd) dan harus subdirektori di bawah cwd.

Perintah build kustom

Untuk aplikasi Node.js, Anda dapat mengambil kontrol halus atas perintah apa yang dijalankan selama proses pembuatan aplikasi atau API. Contoh berikut menunjukkan cara mendefinisikan build dengan nilai untuk app_build_command dan api_build_command.

Catatan

Saat ini, Anda hanya dapat mendefinisikan app_build_command dan api_build_command untuk build Node.js. Untuk menentukan versi Node.js, gunakan engines bidang dalam 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'

Alur Azure

...

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)

Lompati membangun aplikasi front-end

Jika Anda memerlukan kontrol penuh atas build untuk aplikasi front-end Anda, Anda dapat melewati build otomatis dan menerapkan aplikasi yang dibangun pada langkah sebelumnya.

Untuk melewatkan membangun aplikasi front-end:

• Atur app_location ke lokasi file yang ingin Anda terapkan.
• Atur skip_app_build ke true.
• Atur output_location ke string kosong ('').

Catatan

Pastikan file Anda staticwebapp.config.json juga disalin ke direktori 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

Alur Azure

...

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)

Lewati pembuatan API

Jika Anda ingin melewati pembangunan API, Anda dapat melewati build otomatis dan menyebarkan API yang dibangun pada langkah sebelumnya.

Langkah-langkah untuk melewati pembuatan API:

• Dalam file staticwebapp.config.json, atur apiRuntime ke runtime dan versi yang benar. Lihat Mengonfigurasi Azure Static Web Apps untuk daftar runtime dan versi yang didukung.

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

• Atur skip_api_build ke true.
• Atur api_location ke folder yang berisi aplikasi API bawaan untuk disebarkan. Jalur ini relatif terhadap akar repositori di GitHub Actions dan cwd di 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

Alur Azure

...

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

Memperpanjang batas waktu build

Secara default, build aplikasi dan API dibatasi hingga 15 menit. Anda dapat memperpanjang batas waktu build dengan mengatur build_timeout_in_minutes properti .

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

Alur Azure

...

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

Jalankan alur kerja tanpa rahasia penyebaran

Terkadang Anda memerlukan alur kerja Anda untuk terus memproses bahkan ketika beberapa rahasia hilang. Atur SKIP_DEPLOY_ON_MISSING_SECRETS variabel lingkungan ke true untuk mengonfigurasi alur kerja Anda untuk melanjutkan tanpa rahasia yang ditentukan.

Saat diaktifkan, fitur ini memungkinkan alur kerja untuk melanjutkan tanpa menyebarkan konten situs.

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

Alur Azure

...

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

Variabel lingkungan

Anda dapat mengatur variabel lingkungan untuk build melalui bagian env konfigurasi pekerjaan.

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

Alur Azure

...

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

Dukungan Monorepo

Monorepo adalah repositori yang berisi kode untuk lebih dari satu aplikasi. Secara default, alur kerja melacak semua file dalam repositori, tetapi Anda dapat menyesuaikan konfigurasi untuk menargetkan satu aplikasi.

Untuk menargetkan file alur kerja ke satu aplikasi, Anda menentukan jalur di bagian push dan pull_request.

GitHub Actions

Saat Anda menyiapkan monorepo, setiap konfigurasi aplikasi statis dicakup hanya untuk file untuk satu aplikasi. File alur kerja yang berbeda tinggal berdampingan di folder .github/workflows repositori.

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

Contoh berikut menunjukkan cara menambahkan simpul paths ke bagian push dan pull_request file bernama 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

Dalam contoh ini, hanya perubahan yang dilakukan pada file berikut yang memicu build baru:

• File apa pun di dalam folder app1
• File apa pun di dalam folder api1
• Perubahan pada file alur kerja azure-static-web-apps-purple-pond.yml aplikasi

Alur Azure

Untuk mendukung lebih dari satu aplikasi dalam satu repositori, buat file alur kerja terpisah dan kaitkan dengan Pipa Azure yang berbeda.

Langkah berikutnya

Meninjau permintaan pull di lingkungan pra-produksi