本文件說明如何將 Wordat 部署到 Vercel。專案是 Vite React 靜態前端 App，部署時不需要後端伺服器或資料庫。

部署前準備

請先確認本機已安裝：

Node.js
Git
GitHub 帳號
Vercel 帳號

專案主要指令：

npm install
npm run dev
npm run build
npm run lint

Vercel 部署設定：

Framework Preset：Vite
Build Command：npm run build
Output Directory：dist
Install Command：npm install

1. 本機確認專案可建置

在專案根目錄執行：

npm install
npm run lint
npm run build

如果 npm run build 成功，專案根目錄會產生 dist 資料夾，Vercel 會使用這個資料夾作為正式網站內容。

2. 建立 GitHub Repository

到 GitHub 建立一個新的 repository，例如：

wordat

可以選擇 Public 或 Private。Vercel 兩者都支援，但 Private repository 需要授權 Vercel 存取。

3. 將專案推送到 GitHub

如果專案尚未初始化 Git：

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin <https://github.com/><你的帳號>/wordat.git
git push -u origin main

如果專案已經有 Git，只需要確認 remote 後推送：

git remote -v
git add .
git commit -m "Update Wordat"
git push

請將 <你的帳號\> 換成自己的 GitHub username。

4. 在 Vercel 匯入專案

前往 Vercel Dashboard。
點選 Add New Project。
選擇剛剛建立的 GitHub repository。
確認 Framework Preset 為 Vite。
確認設定：
- Build Command：npm run build
- Output Directory：dist
- Install Command：npm install
點選 Deploy。

部署完成後，Vercel 會提供一個網址，例如：

<https://wordat.vercel.app>

5. 後續更新部署

之後只要將更新推送到 GitHub，Vercel 就會自動重新部署：

git add .
git commit -m "Update app"
git push

Vercel 會針對 production branch 自動建立正式部署。通常 production branch 是 main。

6. 自訂網域

如果要使用自己的網域：

進入 Vercel 專案頁面。
開啟 Settings。
進入 Domains。
輸入自訂網域。
依照 Vercel 顯示的 DNS 指示，到網域商後台設定 DNS。

常見設定方式：

根網域使用 A record 指向 Vercel 提供的 IP。
子網域使用 CNAME 指向 Vercel 提供的目標網域。

DNS 生效可能需要數分鐘到數小時。

7. PWA 與離線功能注意事項

Wordat 使用 PWA 快取機制。部署到 Vercel 後，正式環境會以 HTTPS 提供網站，符合 Service Worker 與 PWA 安裝需求。

注意事項：

第一次開啟網站時需要網路連線。
App 資源快取完成後，瀏覽器才可支援離線開啟。
如果發布新版本，使用者可能會看到更新提示。
PWA 快取與 localStorage 都是瀏覽器端資料，不等於雲端同步。

8. 資料備份建議

Wordat 的單字資料存在使用者瀏覽器 localStorage。部署到 Vercel 後，資料仍然不會上傳到 Vercel 或 GitHub。

建議使用者定期在 App 內點選匯出，下載 JSON 備份檔。更換裝置、換瀏覽器或清除網站資料前，請先匯出備份。

9. 常見問題

部署後畫面空白

先確認本機 npm run build 是否成功。如果本機成功但 Vercel 失敗，請到 Vercel 的 Deployment Logs 查看錯誤訊息。

Vercel 找不到 build output

確認 Output Directory 是：

dist

TypeScript 錯誤導致部署失敗

先在本機執行：

npm run lint

依照錯誤訊息修正後再推送。

使用者資料沒有同步到另一台裝置

這是目前設計。Wordat 採 Local-first 架構，資料存在本機瀏覽器。若要移動資料，請使用匯出 / 匯入 JSON 備份。

部署