在本地端完成開發後，最關鍵的一步就是將前端專案推向雲端，讓所有人都能隨時在線上體驗《喵語日誌》。

今天將專案正式部署至 Vercel 雲端平台，並記錄在生產環境中串接 Google Gemini API 與 Firebase 時遇到的實戰除錯歷程。

為什麼選擇 Vercel？

在評估現代前端應用的部署平台時，Vercel 提供了極具效率的開發者體驗：

• Git 原生整合：只要推送程式碼至 GitHub main 分支，即可自動觸發 CI/CD 流程進行建置與發布。

• 開箱即用的環境變數管理：提供專屬後台安全注入 API Key，徹底杜絕敏感金鑰外洩至公開代碼庫。

• 全球 CDN 邊緣加速：自動配置 HTTPS 憑證並透過全球邊緣節點分發，確保極快的載入速度與高可用性。

部署流程與環境變數設定

1. 依賴檢查與首次推送

在將專案推送到 GitHub 前，確認專案依賴已完整安裝並提交：

# 檢查工作區狀態
git status

# 加入所有變更並提交初始版本
git add .
git commit -m "feat: initial commit for production"
git push origin main

2. 設定環境變數（Environment Variables）

登入 Vercel 專案管理後台，前往 Settings → Environment Variables，依序匯入本地 .env 的 7 組核心環境變數：

• VITE_GEMINI_API_KEY
• VITE_FIREBASE_API_KEY
• VITE_FIREBASE_AUTH_DOMAIN
• VITE_FIREBASE_PROJECT_ID
• VITE_FIREBASE_STORAGE_BUCKET
• VITE_FIREBASE_MESSAGING_SENDER_ID
• VITE_FIREBASE_APP_ID

確認所有變數在 Production、Preview 與 Development 環境皆已勾選並生效。

3. 觸發 Production 部署

環境變數儲存完成後，點擊 Redeploy 觸發雲端建置流程。

生產環境踩坑與除錯實錄

當專案部署到真實線上環境後，我在實際操作與發送訊息時遇到了幾項關鍵問題，以下是排查與修復過程：

1. 補齊缺失的 SDK 套件依賴

• 問題現象： 首次雲端打包時，建置記錄（Build Log）報錯指出無法解析 @google/genai 模組，導致打包中斷。

• 原因排查： 本地開發時曾以全域或快取模組進行測試，但 package.json 缺少明確的依賴宣告。

• 解決方案： 於專案根目錄重新安裝 Google Gen AI 最新套件並推送到遠端：

# 安裝 Google GenAI 套件
npm install @google/genai

# 提交 lockfile 變更以觸發重新建置
git add package.json package-lock.json
git commit -m "fix: add @google/genai dependency"
git push

2. 應對 Gemini API 503 負載問題

• 問題現象： 線上傳送日記時觸發了前端的 Fallback 保底回覆，打開 F12 開發者工具發現 Console 出現 503 Service Unavailable 錯誤。

• 原因排查： 部分通用模型在特定時段面臨全球高流量排隊，導致請求超時或被暫時拒絕。

• 解決方案： 在 src/services/geminiService.ts 中，將模型切換為專為高並發、低延遲打造的輕量模型 gemini-3.1-flash-lite（或適用於生產環境的高可用性輕量模型），確保在維持優秀理解力與 JSON 結構輸出的同時，大幅降低延遲並提升穩定度：

# 提交模型調整設定
git add src/services/geminiService.ts
git commit -m "fix: switch to lightweight flash model for low latency"
git push

3. IndexedDB 多連線阻擋問題

• 問題現象： 控制台偶爾出現 Database is closing/hidden 警告，導致 Firebase 匿名登入狀態延遲建立。

• 原因排查： 在頻繁切換測試環境與重新整理過程中，瀏覽器的 IndexedDB 快取鎖定尚未完全釋放。

• 解決方案： 在瀏覽器 F12 開發者工具的 Application → Storage 面板點選 Clear site data 清除衝突快取，重新整理後 Firebase Auth 即可順暢完成匿名身分驗證。

最終成果驗收

完成排錯與重新部署後，正式網址上的各核心模組均運作正常：

• 多模態對話： Gemini 成功依據使用者輸入的文字與照片，即時給予細膩溫暖的貓咪口吻回覆。
  

• 雲端資料同步： Firestore 即時寫入日記記錄、情緒分數與生活標籤，跨頁面日曆與圖表即時連動。
  

• 正式上線： 《喵語日誌》正式在 Vercel 提供的專屬 HTTPS 網址上穩定運行。
  

實作心得

在本地端執行 npm run dev 順利運作，往往容易讓人產生「專案已經全部完成」的錯覺。直到真正推向雲端生產環境，才體會到前後端整合與雲端部署的細節考驗：

環境變數與安全意識： 在本地可以依賴 .env 快速讀取金鑰，但上了雲端必須熟練運用平台提供的注入機制，確保敏感設定不被暴露在公開儲存庫。

雲端服務的高可用性思維： 面對第三方 API 偶發的服務負載波動，前端不能只依賴單一調用邏輯，必須具備 Fallback 保底機制與根據業務需求選用合適輕量模型的架構思維。

全方位除錯能力： 從 Network 狀態碼、Console 報錯日誌到 Application 儲存空間，學會抽絲剝繭定位問題源頭，能大幅提升排查生產問題的效率。

當看到貓咪管家在正式公開網址上即時跳出專屬回應、Firestore 順利寫入第一筆雲端資料時，那種看見作品真正「上線」的成就感十分踏實。

結語

今天順利完成了從程式碼儲存庫到全球 CDN 的全自動化部署里程碑。《喵語日誌》不再只是本機上的 Demo，而是一個真正具備 AI 多模態對話、情緒分析視覺化與雲端即時同步的完整 Web 應用。

接下來，我們將進一步優化前端使用體驗、打磨 UI 微互動動畫，並針對整體系統進行效能與資安的最終盤點，讓這款陪伴工具以更穩定的品質陪伴每一位使用者。

明天見，喵～ 🐾