部署前準備

這份教學會帶你把 Wordmem 放到 GitHub，並部署到 Vercel，同時設定 Google Cloud，讓 Google Drive 備份功能可以正常使用。

你需要準備：

一個 GitHub 帳號
一個 Vercel 帳號
一個 Google 帳號
本機已安裝 Git
本機已安裝 Node.js 與 npm
專案原始碼

建議版本：

工具	建議
Node.js	使用目前 LTS 版本
npm	隨 Node.js 安裝即可
Git	使用最新版

檢查本機工具：

node -v
npm -v
git --version

本機專案檢查

進入專案資料夾：

cd C:\\Users\\Tavric\\Documents\\projects\\Wordmem

安裝套件：

npm install

建立本機環境變數檔：

Copy-Item .env.example .env.local

\.env\.local 先保留範例值也可以，等 Google Cloud 設定完成後再回來填入。

啟動本機開發伺服器：

npm run dev

瀏覽器開啟 Vite 顯示的網址，通常是：

<http://localhost:5173>

正式部署前，建議先跑一次檢查：

npm run typecheck
npm run lint
npm run test
npm run build

如果以上指令都成功，代表專案基本狀態正常。

建立 GitHub Repository

在 GitHub 建立空 Repository

開啟 GitHub。
點右上角 \+。
選擇 New repository。
Repository name 可填：

Wordmem

Visibility 可選 Public 或 Private。
不要勾選 Add a README file。
不要勾選 \.gitignore。
不要勾選 Choose a license。
點 Create repository。

這樣 GitHub 會建立一個空的遠端 Repository。

將本機專案推上 GitHub

回到 PowerShell，確認目前在專案根目錄：

cd C:\\Users\\Tavric\\Documents\\projects\\Wordmem

確認 Git 狀態：

git status

如果專案還沒有初始化 Git：

git init

加入檔案：

git add .

建立第一次 commit：

git commit -m "Initial commit"

把遠端 Repository 加進來。請把網址換成你的 GitHub Repository URL：

git remote add origin <https://github.com/你的帳號/Wordmem.git>

設定主要分支名稱：

git branch -M main

推送到 GitHub：

git push -u origin main

推送完成後，重新整理 GitHub Repository 頁面，應該會看到專案檔案。

Google Cloud 設定

Wordmem 的 Google Drive 備份功能需要 Google OAuth 2.0 Client ID。這個 Client ID 會放在 Vercel 的環境變數 VITE\_GOOGLE\_CLIENT\_ID。

建立 Google Cloud Project

開啟 Google Cloud Console：

<https://console.cloud.google.com/>

登入 Google 帳號。
點上方專案選擇器。
點 New Project。
Project name 可填：

Wordmem

Organization 沒有也沒關係。
點 Create。
等待專案建立完成。
確認目前選到剛建立的 Wordmem 專案。

啟用 Google Drive API

在 Google Cloud Console 左上角選單打開 APIs & Services。
進入 Library。
搜尋：

Google Drive API

點進 Google Drive API。
點 Enable。

啟用完成後，Wordmem 才能透過 Drive API 建立資料夾、上傳備份、列出備份與下載備份。

到 APIs & Services。
進入 OAuth consent screen。
如果看到使用者類型，選擇 External。
點 Create。

填寫 App 資訊：

欄位	建議填寫
App name	Wordmem
User support email	你的 email
App logo	可先不填
App domain	部署完成前可先空著
Developer contact information	你的 email

儲存後繼續。

設定 Scopes

Wordmem 使用的 Google Drive scope 是：

<https://www.googleapis.com/auth/drive.file>

設定方式：

在 OAuth consent screen 的 Scopes 步驟點 Add or Remove Scopes。
搜尋 drive\.file。
勾選 Google Drive API 的 \.\.\./auth/drive\.file。
點 Update。
儲存並繼續。

drive\.file 的用途是讓 Wordmem 建立與管理自己的備份檔，不需要完整讀取使用者整個 Google Drive。

加入測試使用者

如果 OAuth App 還在 Testing 狀態，只有測試使用者能登入。

在 OAuth consent screen 找到 Test users。
點 Add users。
輸入你的 Google 帳號 email。
儲存。

如果你要給其他人測試，也要把對方的 Google 帳號加入測試使用者。

建立 OAuth Client ID

到 APIs & Services。
進入 Credentials。
點 Create Credentials。
選擇 OAuth client ID。
Application type 選：

Web application

Name 可填：

Wordmem Web

設定 Authorized JavaScript Origins

這裡要填允許載入 Google 登入服務的網站來源。

本機開發先加入：

<http://localhost:5173>

Vercel 正式網址稍後部署完成才會知道，之後要回來加入，例如：

<https://wordmem.vercel.app>

如果 Vercel 給你的網址不同，請填你的實際網址。

設定 Authorized Redirect URIs

Wordmem 目前使用 Google Identity Services 的 token client，不需要傳統 redirect callback 頁面。

一般情況下，Authorized redirect URIs 可以不填。

如果 Google Cloud 介面要求你填寫，或你之後改成 redirect flow，才需要額外設定 callback URL。

複製 Client ID

建立完成後，Google Cloud 會顯示 OAuth Client。

複製 Client ID，格式大約像：

1234567890-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com

這個值等等會填到：

VITE_GOOGLE_CLIENT_ID

本機設定 Google Client ID

打開 \.env\.local，填入剛剛複製的 Client ID：

VITE_GOOGLE_CLIENT_ID=你的-client-id.apps.googleusercontent.com

重新啟動開發伺服器：

npm run dev

測試流程：

開啟 Wordmem。
建立至少一個單字集。
開啟備份與匯入。
點登入 Google。
完成授權。
點備份到 Drive。
到 Google Drive 確認是否出現 Wordmem 資料夾與 ZIP 備份檔。

如果看到 尚未設定 VITE\_GOOGLE\_CLIENT\_ID，代表 \.env\.local 沒有設定成功或開發伺服器沒有重新啟動。

Vercel 部署

匯入 GitHub 專案

開啟 Vercel：

<https://vercel.com/>

使用 GitHub 帳號登入。
點 Add New。
選擇 Project。
找到 Wordmem Repository。
點 Import。

設定 Framework 與 Build

Vercel 通常會自動偵測為 Vite 專案。

確認設定如下：

項目	值
Framework Preset	Vite
Build Command	`npm run build`
Output Directory	`dist`
Install Command	`npm install`

Root Directory 如果專案就在 Repository 根目錄，保持預設即可。

設定 Vercel 環境變數

在部署前，找到 Environment Variables 區塊。

新增：

Name	Value
`VITE\_GOOGLE\_CLIENT\_ID`	你的 Google OAuth Client ID

Environment 建議全部勾選：

Production
Preview
Development

填好後再部署。

開始部署

點 Deploy。
等待 Vercel 安裝套件與執行 build。
部署成功後，Vercel 會提供網址，例如：

<https://wordmem.vercel.app>

請複製你的實際網址。

回到 Google Cloud 加入正式網域

Vercel 部署完成後，必須把正式網址加入 Google OAuth Client 的 Authorized JavaScript Origins。

回到 Google Cloud Console。
進入你的 Wordmem Project。
到 APIs & Services。
進入 Credentials。
點剛剛建立的 OAuth 2.0 Client ID。
在 Authorized JavaScript origins 加入 Vercel 網址，例如：

<https://wordmem.vercel.app>

儲存。

注意：

不要在網址最後加 /。
必須使用 https://。
必須填實際部署網址。
如果你使用自訂網域，也要把自訂網域加入。

Google Cloud 設定更新後可能需要幾分鐘才完全生效。

驗證正式站

打開 Vercel 正式網址，逐項確認。

基本功能

首頁可正常載入。
可新增單字集。
可編輯單字集。
可進入單字卡。
可進入選擇題練習。
可進入拼字測試。
測驗完成後可看到結果頁。

路由重新整理

Wordmem 使用 Vue Router，vercel\.json 已設定 rewrite：

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

請測試：

進入任一練習頁。
重新整理瀏覽器。
確認不會出現 404。

PWA 與快取

vercel\.json 也針對以下檔案設定重新驗證：

sw.js
version.json
index.html

這能降低使用者卡在舊版本的機率。

部署新版本後，如果畫面沒有更新，可以嘗試：

重新整理頁面。
關閉再打開瀏覽器分頁。
清除該網站快取。

Google Drive 備份

正式站測試：

開啟 Wordmem 正式網址。
建立一個測試單字集。
開啟備份與匯入。
點登入 Google。
選擇已加入測試使用者的 Google 帳號。
完成授權。
點備份到 Drive。
到 Google Drive 檢查是否有 Wordmem 資料夾與 ZIP 檔。
回到 App，點讀取 Drive 備份。
確認可以列出備份並選擇匯入。

常見問題

Google 登入顯示 access blocked

可能原因：

OAuth consent screen 還在 Testing，但你的 Google 帳號沒有加入 Test users。
OAuth App 設定不完整。
使用了未授權的網域。

處理方式：

到 Google Cloud 的 OAuth consent screen。
確認你的 email 已加入 Test users。
確認 Authorized JavaScript origins 有正式 Vercel 網址。
等幾分鐘後再重試。

Google 登入顯示 origin mismatch

代表目前網站網址沒有被加入 Authorized JavaScript origins。

請檢查：

本機開發是否加入 http://localhost:5173
正式站是否加入你的 Vercel 網址
網址是否多了結尾 /
http 與 https 是否填錯

App 顯示尚未設定 VITE_GOOGLE_CLIENT_ID

代表環境變數沒有正確注入。

本機請檢查：

.env.local

Vercel 請檢查：

Project Settings -> Environment Variables

修改 Vercel 環境變數後，需要重新部署。

Vercel 部署成功但 Google Drive 仍不能用

請確認：

Vercel 有設定 VITE\_GOOGLE\_CLIENT\_ID。
修改環境變數後已重新部署。
Google Cloud 已啟用 Google Drive API。
OAuth Client ID 的 Authorized JavaScript origins 有正式網址。
使用的 Google 帳號已加入 Test users，或 OAuth App 已正式發布。

重新整理練習頁出現 404

請確認 Repository 內有 vercel\.json，且內容包含：

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

如果你剛新增或修改 vercel\.json，請 commit、push，並讓 Vercel 重新部署。

npm run build 在 Vercel 失敗

先在本機執行：

npm run typecheck
npm run lint
npm run test
npm run build

本機如果也失敗，先修本機錯誤。

本機成功但 Vercel 失敗時，檢查：

Node.js 版本是否差太多。
package-lock.json 是否已 commit。
是否有缺少環境變數。
Vercel Build Logs 的第一個錯誤訊息。

更新部署

日後修改程式後，照以下流程更新正式站。

檢查狀態：

git status

加入變更：

git add .

建立 commit：

git commit -m "Update Wordmem"