藝術銀行 Art Bank 會員系統開發紀錄 — Nuxt 3 + JWT 實戰經驗
分享藝術銀行會員系統開發經驗,包含在既定的 Nuxt 3 SSR 架構下實作會員功能、JWT + Pinia 登入狀態設計,以及公司戶/個人戶複雜表單的處理心得。
本篇目錄
2024 年底到 2025 年初,我和版塊設計合作開發藝術銀行 Art Bank的會員前台。藝術銀行是文化部的藝術作品租賃平台,公司和個人都可以在線上租借藝術品,我負責的是會員系統。
我負責的部分
這個專案我主要負責會員前台的功能,包含:
- 會員登入與註冊流程
- 公司戶與個人戶的不同註冊表單
- 會員收藏藝術作品功能
- 會員中心相關頁面
- 藝術作品租賃流程表單
API 是別的工程師在處理,我就專注在會員相關的功能上。
技術架構與使用心得
專案使用 Nuxt 3 搭配 Tailwind CSS,這些技術不是我決定的,但用下來覺得蠻適合這種需要 SEO 的政府網站。Nuxt 3 的 SSR 機制讓搜尋引擎可以正確抓取頁面內容,這對藝術品的曝光來說很重要。
Tailwind CSS 用過之後才發現,原來切版也可以這麼順。以前寫傳統 CSS 常常要在檔案之間跳來跳去,現在可以直接在元件上組合 class。多人協作時,這樣比較少因為改了共用 selector 而影響其他頁面;不過共用元件和全域設定改動,還是得一起檢查。
會員系統的挑戰
這個專案的會員系統最麻煩的地方,在於要同時處理公司戶和個人戶兩種身分。兩者需要填的資料完全不同,公司戶要填統編、公司名稱、負責人等等,個人戶則是一般的個人資料。
VeeValidate 表單驗證
表單驗證用 VeeValidate 搭配 Yup。公司戶和個人戶的欄位不同,驗證規則也要跟著切換,處理起來比一般固定欄位的表單複雜。
舉例來說,選擇公司戶的時候,統一編號就是必填欄位,而且要驗證格式;選擇個人戶的時候,這個欄位就不需要了。這種動態驗證規則的切換,一開始踩了不少坑。
後來的做法是用 Yup 的 when 方法來做條件驗證,根據使用者選擇的身分類型,動態套用不同的驗證 schema:
import * as yup from "yup";
const schema = yup.object({
memberType: yup.string().required(),
taxId: yup.string().when("memberType", {
is: "company", // 公司戶時才驗證
then: (schema) =>
schema
.required("請輸入統一編號")
.matches(/^\d{8}$/, "請輸入 8 位數字的統一編號"),
otherwise: (schema) => schema.notRequired(),
}),
companyName: yup.string().when("memberType", {
is: "company",
then: (schema) => schema.required("請輸入公司名稱"),
otherwise: (schema) => schema.notRequired(),
}),
});
錯誤訊息也得讓使用者知道怎麼修正。像統編格式錯誤時,我會直接寫「請輸入 8 位數字的統一編號」,比籠統地說「格式錯誤」清楚。
登入驗證架構
驗證這塊選用 JWT,搭配 Pinia 來管理登入狀態,用 useCookie 讓 SSR 和 CSR 的 token 可以同步。這個架構的好處是全站任何地方都能方便地存取登入狀態,而且重新整理頁面時也能自動恢復。
關於 JWT + Pinia + Cookie 的完整實作細節(包含自動帶 token、權限控制、初始化登入狀態等),我在另一篇文章有更詳細的說明:Nuxt 3 JWT 身份驗證實作筆記。
收藏功能實作
首先是狀態同步的問題。我們希望使用者點愛心後立即看到回饋,所以採用樂觀更新:先改 UI,如果 API 失敗再 rollback。這是當時的互動選擇;需要先確認操作成功的功能,也可以等回應後再更新。
另外,收藏清單要能夠即時反映藝術品的狀態,像是這件作品是不是已經被租走了、價格有沒有變動等等。這邊透過 API 把最新狀態帶回來,前端再去更新顯示。
Nuxt 3 開發心得
以前習慣 Nuxt 2 的 Options API,這次改用 Nuxt 3、Composition API 和 TypeScript,我覺得開發體驗更順,也更理解 SSR 的行為。
我在表單裡踩過一個 useFetch 的坑。預設情況下,useFetch 會 watch 傳入的參數,參數改變就重新打 API,結果使用者每改一個欄位都會觸發請求。這裡需要等到送出表單才呼叫,所以我把 watch 選項設成 false:
const formData = ref({ name: "", email: "" });
const { data, execute } = await useFetch("/api/submit", {
method: "POST",
body: formData,
watch: false, // 關閉自動 watch,避免每次改值都打 API
immediate: false, // 也不要立即執行
});
// 表單送出時才手動呼叫
const handleSubmit = async () => {
await execute();
};
這樣就只會在手動呼叫 execute() 的時候才打 API。
另一個要留意的是 SSR 與 hydration。伺服器沒有 window 或 document,讀取這些瀏覽器 API 時,要安排在 onMounted,或用 import.meta.client 判斷執行環境。這和 hydration mismatch 是兩件事:即使沒在伺服器讀取瀏覽器 API,伺服器輸出與客戶端首次渲染的 HTML 不同,仍可能出現 mismatch。
確實只適合在瀏覽器呈現的區塊,可以用 ClientOnly 並安排 fallback。不過,包住 template 不會自動保護父元件 setup 裡讀取 window 的程式;程式的執行時機也要一起處理。
效能優化
雖然我主要負責會員系統,但也順手做了一些效能優化。會員中心頁面一開始載入蠻慢的,主要是因為一次撈了太多資料。
後來改成分頁載入,每次只撈當頁需要的資料。另外也加了 Skeleton Loading,在資料還沒回來之前先顯示骨架屏,讓使用者知道頁面正在載入中。這樣體驗比一片空白好很多。
圖片也做了懶載入,讓首屏以外的圖片延後下載,通常在接近可視範圍時才開始載入。這對收藏清單這種有大量圖片的頁面來說,改善很明顯;首屏的 LCP 主圖則不適合延後。
遇到的問題與解法
開發過程中遇到最頭痛的問題,大概是公司戶註冊表單更深一層的複雜驗證邏輯。前面提到的 yup.when() 只處理了 memberType 這一層分支,但實際上還有些欄位彼此之間也有相依性,像是選了某個選項之後,另一個欄位才會變成必填,光靠 when() 疊 when() 會越寫越難懂。
一開始想說再用 watch 來監聽這些欄位變化,但寫到後來發現邏輯越來越亂。後來重構成用 computed 來統一算出當下該套用的驗證 schema,再搭配 VeeValidate 的 useForm 來套用,這樣邏輯比較集中,也比較好 debug。
另一個問題是登入狀態在不同頁面之間的同步。有時候使用者在 A 頁面登入,跳到 B 頁面時,畫面卻沒有帶上登入狀態。當時調整了初始化流程,也把讀取 cookie 的處理放進 middleware。
現在沒有留下足夠的除錯紀錄,無法確認是哪個環節造成狀態落差,所以這裡只記下當時的調整。Nuxt 的 useCookie 本身能配合 SSR 使用,搬到 middleware 並不是所有 cookie 問題的通用解法;仍要依實際的請求與初始化時機排查。
學到什麼
這個專案做下來,對 Nuxt 3 的 SSR 機制理解更深了。尤其是 hydration 的原理、伺服器端與客戶端的差異、狀態同步等等,這些以前只是知道大概,現在算是有實戰經驗了。
另外也體會到,大專案的表單處理真的不簡單。動態驗證規則、欄位相依性、錯誤訊息客製化,這些加在一起會讓程式碼變得很複雜。提早規劃好架構,把邏輯拆分清楚,後面維護才會輕鬆。
專案連結:https://artbank.tfaf.org.tw/
站內相關文章: