免費服務打造全端應用：Kairis App 部署實戰指南

Kairis App 完整部署指南：從開發到上線的實戰教學

導言

恭喜您！Kairis App 的核心功能已經全部開發完成。本教學文章旨在提供一份詳盡的部署指南，協助您將開發完成的 Kairis App 發布到網際網路上，讓全球使用者都能輕鬆存取。

我們將採用一套完全免費且主流的服務組合來實現部署，確保您的應用程式能夠長期穩定地運作，同時最大化開發效率與維護便利性。

部署藍圖概覽：

程式碼儲存庫 (Code Repository): GitHub
網站與後端部署 (Frontend & Backend Deployment): Vercel (利用其 Serverless Functions 作為後端 API)
資料庫與使用者驗證 (Database & Authentication): Google Firebase (Firestore 與 Authentication)
外部數據 API (External Data APIs):
- Finnhub: 用於即時股票報價與新聞資訊。
- Alpha Vantage: 用於獲取歷史 K 線數據。
- Gemini (Google AI Studio): 用於 AI 分析與翻譯功能。

前置需求

在開始部署之前，請確保您已具備以下帳號、API 金鑰以及專案準備：

GitHub 帳號： 用於程式碼版本控制與 Vercel 專案匯入。
- 前往註冊 GitHub
Vercel 帳號： 用於部署前端應用與 Serverless API。
- 前往註冊 Vercel (建議使用 GitHub 帳號直接登入)
Firebase 專案： 一個新的 Firebase 專案 (將在後續步驟中建立)。
API 金鑰： 請確保您已申請並複製以下服務的 API 金鑰，並妥善保存：
- FINNHUB_API_KEY: 從您的 Finnhub 儀表板複製。
- ALPHA_VANTAGE_API_KEY: 從 Alpha Vantage 申請並複製。
- GEMINI_API_KEY: 從 Google AI Studio 建立並複製。
Kairis App 專案程式碼： 您的 Kairis App 專案程式碼應已完成開發，並準備好進行部署。

實作步驟

1. 獲取必要的 API 金鑰與帳號

在開始任何部署操作前，請再次確認您已經註冊了 GitHub 和 Vercel 帳號，並從 Finnhub、Alpha Vantage 和 Google AI Studio 獲取了相應的 API 金鑰。將這些金鑰暫時記錄在一個安全的地方，以便後續配置。

2. 準備並上傳您的專案程式碼至 GitHub

請確認您的 Kairis App 專案資料夾符合以下結構。這個結構對於 Vercel 識別前端檔案 (index.html, manifest.json, sw.js) 以及 Serverless Functions (/api/) 至關重要。

/ (專案根目錄)
├── index.html
├── package.json
├── manifest.json
├── sw.js
├── /api/
│   └── get-stock-data.js
└── /icons/
    ├── icon-192x192.png
    └── icon-512x512.png

確認無誤後，請將這整個專案資料夾上傳到您在 GitHub 建立的一個新的儲存庫 (Repository) 中。這將是 Vercel 獲取您程式碼的來源。

3. 設定 Firebase 服務

Firebase 將為您的 Kairis App 提供使用者驗證和資料庫服務。

3.1 建立 Firebase 專案

前往 Firebase 控制台。
點擊「新增專案」。
為專案命名 (例如 kairis-app)，並依照指示完成建立。您可以選擇關閉 Google Analytics 以簡化設定。

3.2 註冊網頁應用程式並更新程式碼

在 Firebase 專案主控台，點擊網頁圖示 </>。
為您的應用程式取一個暱稱 (例如 Kairis Web)，然後點擊「註冊應用程式」。

重要步驟： Firebase 會顯示一個包含 firebaseConfig 物件的程式碼區塊。請立即複製這段程式碼。

// 範例：您的 firebaseConfig 物件會類似這樣
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID"
};

// Initialize Firebase
// firebase.initializeApp(firebaseConfig);

將這段程式碼貼到您本地的 index.html 檔案中，尋找 // *** START: Firebase Integration *** 區塊並替換掉預留位置。
完成此步驟後，請務必將更新後的 index.html 檔案重新上傳至您的 GitHub 儲存庫，以確保 Vercel 部署時能使用最新的配置。

3.3 啟用登入方式

在 Firebase 控制台的左側選單中，選擇「Authentication」。
點擊「開始使用」，然後切換到「Sign-in method」分頁。
在服務供應商列表中，找到並點擊「Google」，將其啟用。設定您的專案支援電子郵件，然後點擊「儲存」。
同樣地，找到並啟用「匿名」登入方式。

3.4 建立並設定 Firestore 資料庫

在 Firebase 控制台的左側選單中，選擇「Firestore Database」。
點擊「建立資料庫」，選擇「以正式版模式啟動」，並選擇一個離您最近的地區 (例如 asia-east1 或 nam5)。

資料庫建立後，切換到「規則 (Rules)」分頁。將所有內容替換為以下規則，然後點擊「發布」。

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // 允許使用者只能讀寫他們自己的 /users/{userId} 文件
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
    // 如果您的應用程式有其他公開讀取或寫入的集合，需要額外定義規則
    // 例如：
    // match /publicData/{documentId} {
    //   allow read: if true; // 允許所有人讀取
    // }
  }
}

這些規則確保了使用者只能存取和修改他們自己的資料，提供了基本的安全性。

4. 部署至 Vercel

Vercel 將負責將您的前端應用程式和 Serverless API 部署到網路上。

4.1 匯入 GitHub 專案

登入 Vercel。
點擊「Add New…」-> 「Project」。
選擇您存放 Kairis 專案的 GitHub 儲存庫，並點擊「Import」。

4.2 設定 Vercel KV (快取資料庫)

Vercel KV 是一個基於 Redis 的無伺服器鍵值儲存服務，非常適合用於快取 API 響應，減少重複請求。

在 Vercel 專案設定頁面，找到「Storage」分頁。
點擊「Create a database」區塊中的 Upstash for Redis 旁邊的「Create」。
選擇 Hobby (Free) 方案，選擇一個離您最近的地區，然後完成建立與連結。Vercel 會自動為您的專案設定所有 KV 相關的環境變數。

4.3 設定 API 金鑰為環境變數

為了安全起見，您的 API 金鑰不應直接寫在程式碼中，而應作為環境變數進行管理。

回到 Vercel 專案設定的「Settings」-> 「Environment Variables」。
新增以下三個環境變數：

Key	Value (請替換為您的實際金鑰)	說明
`FINNHUB_API_KEY`	`您的 Finnhub 金鑰`	用於 Finnhub API 請求
`ALPHA_VANTAGE_API_KEY`	`您的 Alpha Vantage 金鑰`	用於 Alpha Vantage API 請求
`GEMINI_API_KEY`	`您的 Gemini 金鑰`	用於 Gemini AI API 請求

點擊「Save」儲存變數。

4.4 觸發重新部署

在設定完環境變數後，您需要觸發一次新的部署，以確保這些變數在部署的應用程式中生效。

回到 Vercel 專案的「Deployments」分頁。
找到最新的部署紀錄，點擊它右邊的三個點 ... -> 「Redeploy」來觸發一次新的部署。

4.5 設定 Firebase 授權網域 (關鍵步驟)

這是確保 Firebase 認證能夠在您的 Vercel 部署網域上正常運作的關鍵步驟。

部署成功後，Vercel 會給您一個公開的網址 (例如 https://kairis.vercel.app 或一個隨機生成的網址)。請將這個網址複製起來。
回到 Firebase 控制台的「Authentication」-> 「Settings」-> 「已授權的網域」。
點擊「新增網域」，將您從 Vercel 複製的網址貼上 (例如 kairis.vercel.app)，然後點擊「新增」。

恭喜您！完成以上所有步驟後，您的 Kairis App 就正式上線了！您可以透過 Vercel 提供的網址訪問您的應用程式。

常見錯誤與解法

Firebase 登入失敗 (例如 Google 登入彈窗關閉或報錯):
- 問題： 未在 Firebase Authentication 中設定 Vercel 的部署網域為「已授權的網域」。
- 解法： 參考「4.5 設定 Firebase 授權網域」步驟，將您的 Vercel 網址添加到 Firebase 的授權網域列表中。
API 請求失敗 (例如股票數據無法載入):
- 問題： Vercel 環境變數未正確設定，或 API 金鑰錯誤。
- 解法： 檢查 Vercel 專案設定中的「Environment Variables」，確保 FINNHUB_API_KEY、ALPHA_VANTAGE_API_KEY 和 GEMINI_API_KEY 的 Key 和 Value 都正確無誤。觸發一次重新部署。
Firestore 資料無法讀寫或權限錯誤:
- 問題： Firestore 安全規則設定不正確。
- 解法： 檢查 Firebase Firestore Database 的「規則 (Rules)」分頁，確保規則與「3.4 建立並設定 Firestore 資料庫」中提供的範例一致，並且已「發布」。
應用程式無法初始化 Firebase (控制台報錯 firebaseConfig 未定義):
- 問題： index.html 中的 firebaseConfig 物件未正確更新，或者更新後未重新上傳到 GitHub。
- 解法： 確保您已將 Firebase 控制台提供的 firebaseConfig 程式碼複製並貼到本地的 index.html 中，並且已將更新後的 index.html 推送到 GitHub，然後在 Vercel 觸發重新部署。
Vercel 部署失敗或顯示 404 錯誤:
- 問題： 專案檔案結構不正確，或 package.json 配置有誤。
- 解法： 檢查您的專案根目錄是否包含 index.html、package.json 等必要檔案，以及 /api/ 資料夾是否存在 Serverless Function。確保 package.json 中的 scripts 和 dependencies 是正確的。

延伸應用與學習資源

恭喜您的 Kairis App 成功上線！這是一個重要的里程碑。您可以考慮以下進一步的優化和學習：

自訂網域 (Custom Domain): 在 Vercel 中設定您自己的網域名稱，讓您的應用程式擁有更專業的網址 (例如 www.kairisapp.com)。
- Vercel 自訂網域文檔
持續整合/持續部署 (CI/CD): Vercel 已經提供了很好的 CI/CD 體驗，每次 GitHub push 都會自動部署。您可以進一步學習如何優化部署流程。
效能監控與優化: 使用 Vercel 的內建分析工具或整合 Google Analytics 等服務，監控應用程式的效能和使用者行為。
擴展 Firebase 功能: 探索 Firebase 的更多服務，如 Cloud Storage (用於儲存圖片等檔案)、Cloud Functions (更複雜的後端邏輯) 等。
- Firebase 官方文檔
深入學習 Vercel Serverless Functions: 了解如何編寫更複雜的 Serverless Functions 來處理後端邏輯。
- Vercel Serverless Functions 文檔
API 服務提供商文檔：

祝您在 Kairis App 的旅程中一切順利！