自建 React SPA 電商 vs. WooCommerce：原始碼分析、SEO 風險與重構指南

概述：一份來自前端程式碼的架構推斷報告

本分析並非基於對伺服器後端的直接存取，而是透過觀察一個現有電商網站的前端程式碼、網頁回應以及 API 端點，所進行的技術架構推斷。報告明確區分了「可觀測事實」（如使用了 React/Vite、特定 API 路徑）、「技術推論」（如資料流程與元件協作方式）以及「建議方案」（如未來的重構方向）。

核心發現是：該網站採用 Cloudflare CDN + React SPA（Vite 建置）+ 自建 REST API 的三層架構。所有前端路由（如 /shop、/product/<slug>）都由伺服器回傳同一個殼層（app-shell）HTML，其中包含 window.__INITIAL_DATA__ 等變數用於「引導」（bootstrap）資料。

重要區別：殼層中僅有 JSON 資料與空白的 root div，並無產品的實際 HTML 內容，這代表它是純客戶端渲染（CSR），而非伺服器端渲染（SSR）。真正的 SSR 應在 HTML 中就包含產品標題、價格、圖片等內容。

---

1. 現有架構深度解析

1.1 首次載入流程與潛在問題

1. 瀏覽器取得 app-shell HTML。
2. 下載並解析 /assets/index-<hash>.js。這類檔案因其雜湊值可長期快取。
3. React 啟動，讀取 window.__... 中的初始資料，或呼叫 REST API。
4. 元件根據 API 回應渲染 DOM。
5. 後續頁面導航透過 History API 切換，形成流暢的 SPA 體驗。

潛在風險：軟 404 （Soft 404）

由於所有路由（包括不存在的頁面）回傳的都是同一個 app-shell（HTTP 200），這讓 Google 爬蟲難以正確判斷頁面狀態。如果 React 在客戶端顯示「找不到頁面」，但伺服器仍回傳 200，這就會被視為「軟 404」，對 SEO 非常不利 。

1.2 目錄資料流與資料模型缺陷

API 端點顯示資料是透過 GET /api/products?limit=500 等動態請求取得，這讓前端部署與商品管理脫鉤，沒錯。

但 limit=500 是個警示：這暗示 API 是針對小型目錄（目前只有 16 個商品）設計的。若商品數成長到數千個，每次載入 500 筆資料會造成不必要的負擔。未來應改用基於游標的分頁（cursor pagination）。

資料模型問題更嚴重：

• 庫存（stock）欄位存在於商品層級（product），但同時又有 variants（規格）陣列。真正的庫存管理應該以「SKU」（例如「黑色 / M 號」這個組合）為單位。
• 選項值未標準化：同時出現了 XXL 和 2XL，以及 ink navy 和 Ink Navy，這會導致資料過濾、分析功能無法穩定運作。
• 部分欄位（如 type, isbn）看起來像是從其他領域挪用，缺乏明確的電商語意。

1.3 首頁建構器（Homepage Builder）的設計

/api/homepage API 回傳包含 section_order 的設定，讓行銷人員可以透過後台排序、開關頁面上的區塊（如 Hero、產品展示）。這是個好設計，但問題在於一致性。

API 回傳中同時存在 ann 和 announcement（公告）兩個不同的 key，這表示資料結構可能經歷過不嚴謹的遷移。此外，區塊順序、開關狀態與實際資料是分開儲存的，容易產生不同步的 bug。重構時應將每個區塊整合成一個包含 id, kind, enabled, position, payload 的完整物件。

1.4 結帳流程與安全性（PayPal 整合）

結帳流程是標準的兩步驟：

1. 客戶端請求 POST /api/paypal/create-order，伺服器在後端創建 PayPal 訂單。
2. 客戶端驗證後，請求 POST /api/paypal/capture 完成交易。

至關重要的原則：伺服器絕不能信任客戶端傳來的價格、折扣或總金額。伺服器必須根據資料庫中的商品價格、折扣規則與運費設定，自行計算所有金額，否則極易被竄改。

報告也點出，良好與不良的實作差異，在於是否有做到：

• 冪等性金鑰 (Idempotency Key)：防止因網路問題重複點擊而導致重複扣款。
• 交易鎖 (Transaction/Locking)：防止超賣。
• Webhook 簽章驗證：確認付款通知確實來自 PayPal。

1.5 後端推測與安全提醒

雖然無法 100% 確定後端語言（可能是 Node.js、PHP 或 Python），但報告提出了一個關鍵的安全疑慮：/api/track 這類追蹤端點如果無條件接收所有請求資料，可能成為被濫用注入垃圾資料的管道，導致資料庫快速膨脹。

此外，/api/orders/track 允許用短數字序號查詢訂單，這存在列舉攻擊（enumeration attack）風險，可能洩露他人購買資訊。建議使用簽署的追蹤令牌（signed tracking token）或需要配對訂單號碼與電子郵件/ZIP 碼。

---

2. 正面對決：客製化 SPA vs. WooCommerce

2.1 SEO（搜尋引擎最佳化）

這是最關鍵的差距。

• WooCommerce 預設優勢：伺服器直接傳送包含產品 HTML 的頁面，Google 爬蟲一來就能讀取所有內容。
• 純客戶端渲染 SPA（現狀）：Google 雖然有能力執行 JavaScript，但它會延遲索引，而且依賴 API 的可用性。如果渲染引擎超時或 API 出錯，爬蟲看到的就是空白頁。

Google 官方文件已明確指出，動態渲染（Dynamic Rendering）只是權宜之計，不建議長期使用 。最佳解是 SSR（伺服器端渲染）或 SSG（靜態網站生成）。

更糟的是，這個網站目前採用的是「偽 SPA」架構：伺服器為所有路由回傳相同的、幾乎空白的 HTML。這對 Google 來說是「軟 404」與「內容稀少」的雙重打擊 。甚至連社交媒體爬蟲（如 Facebook、LINE 的連結預覽）都因為不執行 JavaScript，永遠抓不到正確的標題與圖片。

2.2 速度與效能

• 客製化 SPA 的潛力：在後續導航中因為僅需交換資料，理論上非常快。靜態資源可透過 CDN 極速傳遞。
• WooCommerce 的基礎：若搭配快取外掛、物件快取（如 Redis）與圖片優化，小型 WooCommerce 網站的首頁載入速度（FCP）可能遠勝過成熟的 SPA。

關鍵區別：SPA 的痛點在於首次載入。它必須先下載並執行大量 JavaScript，再打 API 取得資料，最後才渲染出商品圖片與價格，這段「載入空白」的時間對使用者體驗傷害極大。

2.3 維護與擴展

• WooCommerce：將網站改成產品上架、訂單管理的維護成本轉移到生態系維護（更新 WordPress 核心、外掛、主題，處理相容性問題）。
• 客製化系統：將維護成本轉移到工程團隊（維護前後端程式碼、API、資料庫遷移、CI/CD 流程）。沒有外掛市場，所有功能都得自己寫或整合。

對於一個 16 個商品的網站，客製化架構帶來的複雜度很可能遠超過其帶來的彈性優勢。

---

3. 重構建議：打造更具前瞻性的新程式碼庫

報告最終提出了一個務實的建議：繼續走客製化路線，但徹底翻新架構，而非直接改用 WooCommerce。因為該網站的頁面建構器與品牌體驗已是其核心競爭力。

3.1 具體建議

前端層（Storefront）

• 框架：採用 Next.js（App Router） 或 Remix 這類混合渲染框架。這能讓你對不同頁面採用不同策略：
  • 產品頁、行銷頁：使用 SSG（靜態生成）或 ISR（增量靜態再生），讓 HTML 一載入就有內容，SEO 與社群分享瞬間獲得改善。
  • 購物車抽屜、個人化推薦：仍可使用客戶端元件（Client Components）處理互動。
• 資料驗證：在 API 邊界使用 Zod 等工具做類型驗證。
• 圖片優化：利用 CDN/物件儲存服務的圖片處理功能，指定寬度與格式。

後端層

• 語言與框架：可考慮 NestJS 或 Fastify（TypeScript），並搭配 PostgreSQL。
• 資料庫工具：使用 Prisma 或 Drizzle ORM 來確保型別安全的資料庫操作與遷移。
• 佇列系統：引入 BullMQ 等任務佇列處理非同步作業，如發送電子郵件、處理 Webhook 重試與訂單對帳。這樣 HTTP 請求就不會直接阻塞在郵件伺服器上。
• 監控與可觀測性：導入 OpenTelemetry 進行分散式追蹤，串聯整個結帳流程，方便除錯。

3.2 決策表格

比較項目	現有：客製化 React SPA	WooCommerce 傳統架構	建議：客製化混合渲染 (Hybrid)
品牌 UI 彈性	極高	受限於主題	極高
預設 SEO 表現	差（純 CSR）	良好（伺服器端 HTML）	佳 (SSR/SSG)
導航速度 (後續)	非常快 (SPA)	傳統完整頁面載入	非常快 + 漸進式增強
首次載入速度	慢 (需下載 JS + API)	快 (有 HTML)	快 (有 HTML)
後台管理功能	需完全自建	成熟完善	需自行開發或串接
維護複雜度	專注工程維護	專注生態系(外掛)更新	專注工程維護 (但架構更健康)
多通路擴展性	佳 (API-first)	需啟用 Headless 模式	佳 (API-first)
適合 16 商品？	大材小用，風險高	非常適合	適合 (若品牌需求明確)

---

結論

這個網站並非使用 WooCommerce、Shopify 等現成平台，而是一個技術含量不低的客製化專案。然而，其純客戶端渲染的架構、不盡理想的資料模型，以及潛在的安全漏洞，為其 SEO、效能與穩定性帶來了顯著風險。

對於技術團隊而言，最務實的路線不是盲目改回 WooCommerce，而是借鏡這個客製化架構的優點（如頁面建構器），並用現代化的渲染模式（如 SSR/SSG）與更嚴謹的資料設計，從根本上解決問題。這份報告提供了一份詳盡的藍圖，供開發團隊作為評估與執行的參考。