Bangun konfigurasi untuk Azure Static Web Apps

  • Artikel
  • 7 menit untuk membaca

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 Diperlukan
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 yang berfungsi. 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

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

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 output penerbitan.

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.

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.

...

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'

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 disalin juga ke direktori output .

...

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

Lewati pembuatan API

Jika Anda ingin melewati pembuatan 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.
...

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

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 .

...

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

Variabel lingkungan

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

...

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

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.

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

Langkah berikutnya

Meninjau permintaan pull di lingkungan pra-produksi