無頭 WooCommerce API 設定指南

無頭 WooCommerce API 指南

設定、查詢及保護 WooCommerce 後端 API（WPGraphQL 和 REST）以支援分離式前端應用（Next.js、Remix、行動應用）的編排指南。

---

先決條件與前置作業

• 已安裝 WordPress 並啟用 WooCommerce 外掛。
• 可存取的 GraphQL 端點（預設：https://your-store.com/graphql）。
• 如需深入查詢與技術範例，請參閱 headless-api-reference.md。
• 如需前端客戶端設定，請檢查 storefront-client.ts。

---

逐步執行檢查清單

flowchart TD
    S1["1. 安裝 WPGraphQL 與 WooGraphQL"] --> S2["2. 植入模擬 / 正式目錄資料"]
    S2 --> S3["3. 設定驗證 (JWT / OAuth)"]
    S3 --> S4["4. 使用 GraphiQL 驗證 Schema"]
    S4 --> S5["5. 在 Next.js 中連接客戶端查詢"]

階段 1：後端外掛部署

• 安裝 WPGraphQL 核心：
  • 從 WordPress 外掛目錄安裝並啟用 wp-graphql。
  • 驗證端點是否正常運作：GET/POST /graphql。
• 安裝 WooGraphQL 擴充功能：
  • 下載並安裝 wp-graphql-woocommerce。
  • 驗證 Product、ProductCategory、Cart、Customer 等型別是否出現在 GraphQL schema 中。
• 植入測試資料：
  • 在 WordPress 管理後台執行 工具 → 匯入 → WooCommerce 產品 (CSV)，使用 sample-data/sample_products.csv 檔案匯入。

階段 2：設定無頭驗證

• 選項 A：JWT 驗證 (wp-graphql-jwt-authentication)：
  • 上傳並啟用 wp-graphql-jwt-authentication。
  • 產生一個 64 字元的密鑰（openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64 或使用 PowerShell 等效指令）。
  • 注入到容器中（docker exec -it <container> sed -i ... /var/www/html/wp-config.php），加到 .env 中（GRAPHQL_JWT_AUTH_SECRET_KEY），或直接加到 wp-config.php：

    define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'your-strong-random-secret' );
    

• 選項 B：無頭登入 (wp-graphql-headless-login)：
  • 如果需要外部 OAuth 2.0 / 社交登入（Google、GitHub）時使用。
  • 透過篩選器或管理員設定來設定提供者。

階段 3：查詢商店資料

• 公開目錄：使用聯合片段（... on SimpleProduct、... on VariableProduct）查詢類別和產品。
• 客戶工作階段：在購物車變更時捕捉 woocommerce-session 標頭，並在後續請求中傳遞它。
• 受保護的個人檔案：傳遞 Authorization: Bearer <authToken> 以查詢客戶訂單和地址更新。

階段 4：前端整合 (Next.js)

• 使用公開 GraphQL 查詢為靜態產品頁面實作 SSG/ISR。
• 在客戶端狀態（Zustand / LocalStorage）中維護購物車令牌，以保持 Next.js 頁面可被快取。
• 實作原生結帳橋接：重新導向至 WordPress /checkout 以使用本地支付閘道和 e-Namad 合規性。

---

邊緣情況與已知 AI 陷阱

1. 產品查詢中的聯合類型：WooCommerce 產品是多型的。切勿直接在 products { nodes { price } } 上查詢 price；你必須使用型別條件（... on SimpleProduct { price }、... on VariableProduct { price }）。
2. 缺少工作階段標頭：如果伺服器回傳的 woocommerce-session 令牌沒有被前端客戶端儲存並重新傳送，購物車項目將會在下一個請求時消失。
3. 管理員 React 不相容：如果使用嚴格的核心 WordPress 且沒有自訂建置步驟，請避免使用具有舊版 Gutenberg 管理套件（如 wp-graphql-headless-login 設定面板）的外掛；請堅持使用常數驅動的外掛，例如 wp-graphql-jwt-authentication。
4. CORS 標頭：確保 WordPress 允許來自前端來源的請求，方法是設定標頭或反向代理。

---

驗證與自我檢查

• 對 /graphql 執行測試查詢，確認 productCategories 和 products 有回傳節點。
• 執行 login mutation，確認產生了有效的 authToken。
• 確認在新增項目到購物車時，伺服器有回傳 woocommerce-session 標頭。