[Cloud CICD] 前端篇 - Vue3, Github Action, Azure Static Web App

-

前言：本篇記錄了將 Vue3 前端專案部署到 Azure Static Web Apps 的完整流程，包含自動化 CI/CD 設定。過程中遇到了 Vite 7 版本相容性問題以及 SPA 路由 404 問題，本文將詳細說明解決方案。

📦 技術堆疊

🎨 前端框架 Vue 3 + Vite 7
🔄 CI/CD GitHub Actions
☁️ 雲端平台 Azure Static Web Apps

🗺️ 部署流程總覽

1. 推送程式碼至 GitHub
▼
2. Azure 建立 Static Web App
▼
3. 綁定 GitHub Repository
▼
4. 自動產生 Workflow 檔案
▼
5. 微調 yml 設定（重點！）
▼
6. 建立 staticwebapp.config.json
▼
7. 部署成功 🎉

📝 詳細步驟

1推送 Vue3 專案至 GitHub

確保你的 Vue3 專案已建立並推送到 GitHub Repository。

📁 專案結構檢查
project-root/
├── src/                    # Vue 原始碼
├── public/                 # 靜態資源
├── package.json            # 確認有 "build" script
├── vite.config.js          # Vite 設定檔
└── .gitignore
💻 Git 指令
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/你的帳號/你的專案.git
git push -u origin main

2在 Azure Portal 建立 Static Web Apps

  1. 登入 Azure Portal
  2. 搜尋「Static Web Apps」→ 點擊「建立」
  3. 填寫基本資訊：
    • 訂用帳戶：選擇你的訂用帳戶
    • 資源群組：建立新的或選擇現有的
    • 名稱：輸入專案名稱（例如：my-vue3-app）
    • 區域：East Asia
    • SKU：Free（免費方案）

3綁定 GitHub Repository（關鍵步驟）

在「部署詳細資料」區段進行以下設定：

  • 來源：GitHub
  • GitHub 帳戶：點擊「使用 GitHub 授權」
  • 組織：選擇你的 GitHub 帳號
  • 存放庫：選擇你的專案 Repository
  • 分支：main
⚠️ 建置詳細資料設定（重要）：
  • 建置預設值：Custom
  • 應用程式位置：/（專案根目錄）
  • API 位置：（留空）
  • 輸出位置：dist（Vite 預設輸出資料夾）

完成後點擊「檢閱 + 建立」，Azure 會自動在你的 GitHub Repository 中建立 Workflow 檔案。

4檢查自動產生的 Workflow 檔案

Azure 會在 .github/workflows/ 目錄下自動建立一個 yml 檔案（例如：azure-static-web-apps-xxx.yml）。

📄 初始 Workflow 檔案（Azure 自動產生）
name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main

jobs:
  build_and_deploy_job:
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v3
      
      - name: Build And Deploy
        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 }}
          action: "upload"
          app_location: "/"
          api_location: ""
          output_location: "dist"

⚠️ 遇到的問題與解決方案

❌ 問題 1：Vite 7 版本建置失敗

錯誤訊息：

Error: The engine "node" is incompatible with this module
npm ERR! Expected version: ">=18.0.0"

原因：Vite 7 需要 Node.js 18 以上版本，但 Azure Static Web Apps 的預設 Node 版本較舊。

✅ 解決方案 1：在 Workflow 中指定 Node.js 版本

在 Build And Deploy 步驟之前加入 Node.js 設定：

📄 修改後的 Workflow（關鍵修改）
name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main

jobs:
  build_and_deploy_job:
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v3
      
      # 🔥 新增：設定 Node.js 版本（解決 Vite 7 相容性問題）
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'  # 或 '18'、'20'
      
      - name: Build And Deploy
        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 }}
          action: "upload"
          app_location: "/"
          api_location: ""
          output_location: "dist"

❌ 問題 2：前端 URL 直接輸入或重新整理時出現 404

症狀：

  • 透過頁面上的連結點擊可以正常切換路由 ✅
  • 直接在網址列輸入 /about 會出現 404 ❌
  • 重新整理頁面時會跳轉並顯示 404 ❌

原因：這是 SPA（單頁應用程式）的經典問題。Vue Router 使用 History Mode 時，所有路由都是在客戶端處理的。當直接輸入 URL，瀏覽器會向伺服器請求該路徑，但伺服器上並沒有對應的檔案，因此返回 404。

✅ 解決方案 2：建立 staticwebapp.config.json

在專案根目錄（與 package.json 同層）建立 staticwebapp.config.json 檔案：

📄 staticwebapp.config.json（放在專案根目錄）
{
  "routes": [
    {
      "route": "/api/*",
      "rewrite": "https://你的後端API網址.azurewebsites.net/api/*",
      "allowedRoles": ["anonymous"]
    }
  ],
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": [
      "/api/*",
      "/*.css",
      "/*.js",
      "/*.png",
      "/*.jpg",
      "/*.jpeg",
      "/*.gif",
      "/*.svg",
      "/*.ico",
      "/*.webp",
      "/*.woff",
      "/*.woff2"
    ]
  },
  "responseOverrides": {
    "404": {
      "rewrite": "/index.html",
      "statusCode": 200
    }
  }
}
📌 設定說明：
  • navigationFallback：將所有不存在的路徑導向 index.html，讓 Vue Router 接手處理
  • exclude：排除靜態資源檔案，避免被重定向
  • responseOverrides：確保 404 錯誤也返回 index.html
  • routes：設定 API 代理（如果你的後端是獨立部署的）

5完整的 Workflow 最終版本

整合以上所有修正後的完整設定檔：

📄 .github/workflows/azure-static-web-apps-xxx.yml（最終版）
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@v3
        with:
          submodules: true
          lfs: false
      
      # 🔥 設定 Node.js 版本（解決 Vite 7 問題）
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - 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 }}
          action: "upload"
          app_location: "/"
          api_location: ""
          output_location: "dist"
          
  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"

6提交並推送變更

git add .github/workflows/azure-static-web-apps-xxx.yml
git add staticwebapp.config.json
git commit -m "Fix: Add Node.js 20 for Vite 7 and configure SPA routing"
git push origin main
🎉 部署成功！

推送後，GitHub Actions 會自動觸發建置與部署流程。你可以在 GitHub Repository 的「Actions」頁籤查看部署狀態。

🧪 驗證部署結果

部署完成後，請測試以下功能確保一切正常：

  • ✅ 點擊頁面上的連結能正常切換路由
  • ✅ 直接在網址列輸入路由（例如 /about）能正常顯示
  • ✅ 在任意頁面按下重新整理（F5）不會出現 404
  • ✅ API 呼叫能正常運作（如果有設定 API 代理）

📚 重點整理

🔑 關鍵要點：
  1. Vite 7 相容性：必須在 Workflow 中明確設定 Node.js 18+ 版本
  2. SPA 路由問題：透過 staticwebapp.config.json 設定 navigationFallback 解決
  3. 檔案位置：staticwebapp.config.json 必須放在專案根目錄
  4. 部署順序：先建立 Azure 資源並綁定 GitHub，再微調自動產生的 Workflow

🔗 相關資源

希望這篇文章能幫助你順利部署 Vue3 專案到 Azure！
如果遇到其他問題，歡迎留言討論 😊

留言

張貼留言

這個網誌中的熱門文章

[C#] 無法載入檔案或組件 或其相依性的其中之一。 找到的組件資訊清單定義與組件參考不符。 (發生例外狀況於 HRESULT: 0x80131040)

-
圖片
如提，當專案使用 .NET Framework 時，多少會出現這個問題，尤其是多個專案使用同個套件，如果調整版本時，連帶的依賴套件也會變動，就會造成父子專案的套件版本不同，以下紀錄解決方式。 以下附上情境:  System.IO.FileLoadException: 無法載入檔案或組件 'System.Text.Json, Version=8.0.0.4, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51' 或其相依性的其中之一。 找到的組件資訊清單定義與組件參考不符。 (發生例外狀況於 HRESULT: 0x80131040) 分析:       1. 系統認為套件要使用 System.Text.Json, Version=8.0.0.4     2. 但專案中使用的套件 不是  System.Text.Json, Version=8.0.0.4 解決方式:      1. 先確認 bin 裡面的套件版本是多少 。(看起來是 7.0.0)                2. 檢查 App.Config 或是 Web.Config 的套件版本是多少。(看起來是 8.0.4)                3. 檢查 .csproj 的套件版本是多少。(看起來是 8.0.4)                  4. 把  App.Config, Web.Config, .csproj 的版本都改成 7.0.0      5. 清除方案 > 重建方案     
Read more »

[Cloud CICD] 後端篇 - .Net8 WebApi, Github Action, Azure App Service

-
前言： 本篇記錄了將 .NET 8 Web API 專案部署到 Azure App Service 的完整流程，包含 GitHub Actions 自動化部署設定。重點包含 Publish Profile 設定 、 環境變數階層設定 ，以及 Database 防火牆 IP 白名單設定 。 📦 技術堆疊 ⚙️ 後端框架 .NET 8 Web API 🔄 CI/CD GitHub Actions ☁️ 雲端平台 Azure App Service 🗺️ 部署流程總覽 1. 推送 .NET 8 API 至 GitHub ▼ 2. 建立 Azure App Service ▼ 3. 下載 Publish Profile ▼ 4. 設定 GitHub Secrets ▼ 5. 建立 GitHub Actions Workflow ▼ 6. 設定 Environment Variables ▼ 7. 設定 Database 防火牆 ▼ 8. 部署成功 🎉 📝 詳細步驟 1 推送 .NET 8 Web API 專案至 GitHub 確保你的 .NET 8 Web API 專案已建立並推送到 GitHub Repository。 📁 專案結構檢查 project-root/ ├── Controllers/ # API Controllers ├── Models/ # 資料模型 ├── Services/ ...
Read more »