Bagikan melalui

Bangun konfigurasi untuk Azure Static Web Apps

  • Artikel

Konfigurasi build Azure Static Web Apps menggunakan 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. No
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, lokasi relatif terhadap folder output. No
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.		 No
api_build_command Untuk aplikasi Node.js, Anda dapat menentukan perintah kustom untuk membangun aplikasi Azure Functions API. No
skip_app_build Atur nilai ke true untuk melewati pembuatan aplikasi front-end. No
skip_api_build Atur nilai ke true untuk melewati pembuatan fungsi API. No
cwd
(Hanya Azure Pipelines)		 Jalur absolut ke folder kerja. Default ke $(System.DefaultWorkingDirectory). No
build_timeout_in_minutes Atur nilai ini untuk menyesuaikan batas waktu build. Default ke 15. No

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

Tindakan GitHub menghasilkan file konfigurasi dan disimpan di folder .github/workflows , bernama 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 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.

Pekerjaan Tutup Permintaan Pull secara otomatis menutup permintaan pull yang memicu build dan penyebaran. Pekerjaan opsional ini tidak diperlukan agar proses berfungsi.

Saat permintaan pull dibuka, Azure Static Web Apps GitHub Action membangun dan menyebarkan aplikasi ke lingkungan penahapan. Setelah itu, pekerjaan Tutup Permintaan Pull memeriksa apakah permintaan pull masih terbuka dan menutupnya dengan pesan penyelesaian.

Pekerjaan ini membantu menjaga alur kerja permintaan pull Anda tetap terorganisir dan mencegah permintaan pull kedaluarsa. Dengan runtime secara otomatis menutup permintaan pull, repositori Anda tetap terbarui dan tim Anda diberi tahu tentang status tersebut.

Pekerjaan Tutup Permintaan Pull adalah bagian dari alur kerja GitHub Actions Azure Static Web Apps, menutup permintaan pull setelah digabungkan. Tindakan ini Azure/static-web-apps-deploy menyebarkan aplikasi ke Azure Static Web Apps, yang azure_static_web_apps_api_token memerlukan untuk autentikasi.

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 juga disalin 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 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.
...

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

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.

...

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

Variabel lingkungan

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

Untuk informasi selengkapnya tentang variabel lingkungan yang digunakan oleh Oryx, lihat Konfigurasi 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

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