架構決策：以 Cloudflare Pages + @cloudflare/next-on-pages 部署 Next.js 電商前台
1. 核心決策與建議
針對目前的電商 MVP 開發計畫，我們決定採用 Cloudflare Pages 搭配 @cloudflare/next-on-pages 作為 Next.js Storefront 的部署方案。
這個選擇是基於「彈性最大化」與「成本效益」的考量：
- 解決社群分享痛點：支援 SSR（伺服器端渲染），確保商品頁在 Line/WeChat 分享時能正確顯示預覽圖與標題（這是純靜態 Export 做不到的）。
- 不需維護伺服器：將 Next.js 編譯為 Cloudflare Workers/Functions，享有 Edge Network 的效能與 Serverless 的免運維優勢。
- 保留未來擴充性：雖然 MVP 不做會員登入，但此架構保留了未來實作 SSR 個人化內容或 Edge Middleware 的能力，不會像純靜態網站那樣「把路走死」。
2. 這是什麼技術組合？
Cloudflare Pages + @cloudflare/next-on-pages
這並不是要你維護兩個分開的專案，而是一個將 Next.js 應用程式「轉譯」到 Cloudflare 邊緣環境的流程。
- Cloudflare Pages：這是你的託管平台（Hosting），負責 Git 自動部署、提供對外網址、SSL 憑證與 CDN。
@cloudflare/next-on-pages：這是一個 Build Adapter（轉接器）。它會介入 Next.js 的 Build 過程，將原本預設跑在 Node.js 或 Vercel 的程式碼，轉換成 Cloudflare Edge 可以理解的格式（Static Assets + Workers Functions）。
結果：你寫的是標準的 Next.js，但部署後，它跑在 Cloudflare 的全球節點上，且可以直接與你現有的後端架構（Workers/Hono）整合。
| 部署方式 | 執行環境 | 成本 | 適合場景 |
|---|---|---|---|
| Vercel (原生) | AWS Lambda / Edge | 中高 | 極度依賴 Next.js 特有黑科技，不在意鎖定平台。 |
| CF Pages (Static Export) | 純靜態檔案 | 極低 | 部落格、文檔。缺點是無法動態產生 Meta Tags (影響分享預覽)。 |
| CF Pages + next-on-pages | Edge Functions | 低/中 | 全端/動態網站。享有 SSR 能力，且與 R2/D1/Workers 整合性佳。 |
3. 架構分工：Storefront vs. Backend
在這個架構下，我們明確定義了職責邊界，確保系統單純化：
[Storefront] apps/web (Next.js)
- 角色：負責 UI 渲染、互動邏輯、路由管理、SEO Meta 生成。
- 渲染策略：
- 商品頁 (
/products/[slug])：採用 SSR 或 SSG。這是為了確保當機器人（Crawler）爬取頁面時，HTML 內已經包含正確的og:image與og:title。 - 互動頁 (
/cart,/checkout)：採用 CSR (Client-Side Rendering)。這些頁面高度依賴使用者當下的狀態，不需要伺服器預先渲染。
- 商品頁 (
- 數據來源：所有的資料讀取（Fetch）與寫入（Mutate），都指向我們的獨立後端 API。
[Backend] apps/api (Hono + Workers)
- 角色：唯一的業務邏輯中心。
- 職責：
- 商品資料庫存取 (D1/Supabase/Neon)。
- 交易處理：建立 Stripe Session、驗證庫存、處理 Webhook。
- 搜尋邏輯：處理
/api/products/search。 - 未來擴充：會員認證、Wishlist 同步等。
4. 針對 8 大互動功能的技術驗證
我們從 Astro 轉向 Next.js 的主因是為了優化 UI 互動體驗。經過評估，您擔心的 8 個核心功能在 Cloudflare Pages 環境下完全不會受限，且大部分僅需 Client Components 即可完成：
- 加入購物車 (Add to Cart)：純前端狀態管理 (Zustand/Context) + LocalStorage。
- 商品規格切換 (Variant Selector)：前端 State 切換圖片/價格，或透過 Client Fetch 取得變體資料。
- 會員登入 UI：MVP 階段不做。未來加入時，可透過 API 驗證 Token，前端僅需處理狀態顯示。
- 結帳表單驗證：前端使用 React Hook Form + Zod，提交時打到
apps/api進行最終驗證。 - 購物車側欄 (Cart Drawer)：標準的前端 UI Component 互動。
- 搜尋即時建議：前端 Debounce + Client Fetch (
apps/api/search)。 - 收藏 (Wishlist)：MVP 存 LocalStorage，未來若需同步則呼叫後端 API。
- 導覽列互動：標準 React UI 行為。
結論：這些功能都不需要 Next.js 的 Server Actions 或 Node.js Runtime，它們在 Edge 環境或純瀏覽器端都能完美運作。
5. 規格總結 (Spec)
為了確保開發與文件的一致性，請依據以下原則執行：
-
部署配置：
- 專案設置：使用 Cloudflare Pages。
- Build 指令：使用
npx @cloudflare/next-on-pages。 - 不使用
output: 'export'，以保留 SSR 能力。
-
SEO 與分享 (關鍵需求)：
- 商品頁必須在 Server 端產生 Meta Tags。
- 這確保了在 Line、WeChat、Facebook 分享連結時，能直接顯示商品圖片與標題，無需等待 JavaScript 執行。
-
MVP 範圍鎖定：
- 不實作：Shopper 登入/註冊系統。
- 實作：完整的購物車流程、Stripe 結帳（由 Workers 建立 Session）、商品瀏覽與搜尋。
這個架構既滿足了您對「互動體驗 (React)」的需求，也解決了「社群分享 (SSR)」的問題，同時保持了與 Cloudflare 生態系（Workers/D1）的最佳相容性。