Shopify headless 選 Vercel 或 Oxygen？Next.js Agent 團隊部署指南

AI
, , , ,
1

以 Next.js 與 Agent coding 為主的團隊，部署 Shopify headless 店面不必二選一：Vercel 是自然預設，新版 Hydrogen toolkit 補足 Shopify 商務層。本文比較路線、導入步驟與 preview 風險。

如果你的團隊以 Next.js、全 Agent coding、專做 Shopify headless 為標準，部署方案常會糾結在「Vercel 還是 Hydrogen」？先講結論：Vercel 是主要預設，而不是為了使用 Shopify 的 Hydrogen 就改用 Oxygen。 原因是這符合你既有 Next.js 工作方式；而且截至 2026 年 10 月，Hydrogen 已不再等同於「React Router + Oxygen」——新版 Hydrogen 是可搭配 Next.js、Vercel 等框架與執行環境使用的 Shopify commerce toolkit，並加入專為 coding agents 設計的 skills。

不過，若問「哪個 Shopify 官方推薦的 Hydrogen 部署路徑最完整」，答案仍是 Hydrogen + Oxygen。若問「Next.js 團隊最順手、Vercel 生態整合最直接」，答案則是 Next.js + Vercel。兩條路線不是對立，Shopify 與 Vercel 正把它們逐步接起來；但要留意新版 Hydrogen 仍是 developer preview，現階段不宜當作所有專案都該立即遷移的穩定標準。

先釐清比較對象

「Vercel vs Hydrogen」其實把不同層級混在一起比較：

  • Next.js 是應用框架；Vercel 是託管與部署平台。
  • Hydrogen 舊版 是 Shopify 專用、以 React Router 為基礎的 headless storefront stack；Oxygen 是 Shopify 為 Hydrogen 設計的託管平台。
  • Hydrogen 新版 轉向框架與 runtime 無關的 Shopify commerce toolkit，可搭配 Next.js，也可部署至 Vercel、Oxygen、Node.js、Cloudflare Workers 等環境。

所以對你真正有用的三種選擇：

路線 適合的情況 主要取捨
Next.js + Vercel，不採用 Hydrogen toolkit 沿用現有 Next.js 架構與自行維護 Shopify API、cart、cache 整合 自由度最高，但重複造輪子、Agent 容易自行拼湊細節
Next.js + Vercel + 新版 Hydrogen 保留 Next.js，又使用 Shopify 提供的 API client、cart、analytics 等 commerce primitives 最貼近既有技術選擇；但新版截至目前仍在 preview
Hydrogen 舊版／React Router + Oxygen 採 Shopify 官方一體化 storefront 路徑，接受 React Router 與 Oxygen 執行環境 Shopify 整合較完整；但不符合只做 Next.js 的既有標準化

Shopify 目前仍把 Hydrogen + Oxygen 列為推薦的 headless stack；Oxygen 提供部署環境、環境變數、快取與 Shopify CDN 整合，並支援 GitHub CI/CD。Oxygen 在符合資格的付費 Shopify 方案上不另外收託管費，但其 worker runtime 有 Node.js API 相容性與資源限制，不能只看「免費」就忽略執行環境差異。

兩條路線的 Pros & Cons

面向 Next.js + Vercel Hydrogen + Oxygen
Next.js 團隊的開發體驗 直接沿用 Next.js App Router、React 生態與既有部署流程，最自然 Hydrogen 傳統主線以 React Router 為基礎，若團隊只標準化 Next.js，會增加切換與維護兩套約定的成本
Shopify 專屬功能 原本需自行串 Storefront API、購物車、Shop Pay、分析事件；新版 Hydrogen toolkit 正在把這些共用能力帶到 Next.js Shopify 整合是設計核心，包含 API client、cart、Shop Pay、analytics 等；Oxygen 整合 Hydrogen 部署管理
Hosting 與平台依賴 Next.js 可部署在 Vercel，也可依架構部署到其他相容環境；實務上要檢查各平台對 Next.js 功能及快取行為的支援 Oxygen 是 Shopify 管理的託管平台，一體化部署體驗佳；但執行時基於 workerd，部分 Node.js APIs 不可用
部署與預覽 Vercel 提供 Git 整合、preview deployment、CDN 與 Next.js 工作流程；計費依方案、流量與資源用量而異 Oxygen 提供 preview 與 production environments，可透過 GitHub 自動部署；符合條件的 Shopify 付費方案可使用 Oxygen
成本可預測性 Vercel Pro 起價每月 US$20，另有用量額度與超額計費；動態請求、函式執行、流量與快取設計都會影響總成本 Oxygen 在合資格方案上不另收託管費，但要將 Shopify 方案、worker 限制、其他服務與維運成本一併計算
Agent coding Vercel／Next.js 是已採用的開發底座；新版 Hydrogen 提供版本相符、可複製到專案內的 Agent skills 新版也有 Agent skills，減少重複實作 cart、金額格式、分析同意等細節；但舊版 Hydrogen + Oxygen 不具備新版 Next.js agent-first toolkit 特性
成熟度與風險 Next.js + Vercel 較容易延續既有生產流程；Vercel 官方 Shopify starter 有現成入口 Oxygen/Hydrogen 傳統路線已是 Shopify 官方產品；但新版 framework-agnostic Hydrogen 仍是 developer preview，API 持續演進

Vercel 對你的主要優勢

  1. 不用為 hosting 換框架。 既有程式庫、元件、部署自動化、Next.js 專業與 Agent 指令都能留在同一條主線。
  2. 更容易讓不同 Shopify 專案共享工程標準。 可把 Next.js、資料取用、快取、觀測與 CI/CD 規範整理成公司自己的 starter 和 skills。
  3. Vercel 官方已提供 Shopify Next.js starter 與部署指南。 不再需要把 Vercel 視為「非 Shopify 專用、只能自行拼接」的選擇。
  4. 新版 Hydrogen 讓 Shopify 專屬邏輯可與 Next.js 分工。 Next.js 負責路由、rendering 與快取；Hydrogen toolkit 提供 Shopify commerce primitives，降低每個案子重寫 glue code 的需求。

主要代價是平台用量費用和快取／函式成本管理。Vercel Pro 公開定價為每月 US$20，另含 US$20 用量額度；流量、函式執行、圖片最佳化等用量仍需納入商業報價與 TCO。

Hydrogen + Oxygen 的主要優勢

  1. Shopify 原生導向。 Shopify 把 Hydrogen 與 Oxygen 作為同一套 headless 體驗設計，API client、cart、部署環境與 Shopify 管理介面之間較有整合感。
  2. Oxygen 可降低額外 hosting 費用。 官方文件列出多種付費 Shopify 方案可使用 Oxygen，且不另收託管費；但免費 hosting 不代表沒有 runtime 限制或維運成本。
  3. 較適合 React Router 團隊。 若專案新建、團隊接受 Hydrogen 的架構約定，而且希望少管理一個通用 hosting 平台。
  4. 有 Shopify 官方維護與部署流程。 官方提供 CLI、preview environments、GitHub 自動部署與部署管理。

它主要的缺點不是「Hydrogen 不好」，而是舊版 Hydrogen 的框架選擇不合你的標準。此外，Oxygen 是 worker-based runtime，部分 Node.js APIs 不可用，worker 受 CPU、記憶體與 bundle 等限制；若共用程式庫依賴 Node 特定能力，必須逐案驗證。

社群與趨勢怎麼解讀

截至 2026 年 10 月，社群訊號正在轉變，不能只用過往的「Hydrogen 就是 Remix／React Router，Vercel 就是 Next.js」來判斷：

  • Shopify 在 2026 年 6 月宣布與 Vercel 合作重做 Hydrogen，目標是把它從整套框架變成可跨框架、跨 runtime 使用的 commerce toolkit，官方列出的方向包括 Next.js、React Router、SvelteKit、Astro、SolidStart 與 Nuxt。
  • Shopify 在同月推出 Hydrogen developer preview，主打 Agent skills、typed Storefront API client、cart、產品與分析等 Shopify 專用能力；官方明確說明這是 preview，功能和 API 還會變動。
  • Shopify 官方在 GitHub 上已把 Hydrogen 描述為「在你已使用的 JavaScript framework 中建置 headless storefront」的 toolkit，並同時列出 React Router on Oxygen 與 Next.js on Vercel 的 starter 選項，顯示目前策略是支援兩路，而非只推 Oxygen。
  • Shopify/Hydrogen repository 有約 2.1k stars、447 forks，可作為專案能見度的粗略參考，但不能推論「Hydrogen 和 Vercel 哪一個部署更普遍」。
  • Vercel 的官方文章也說明，Shopify 與 Vercel 正把 Vercel 過去在 Next.js commerce storefront 的經驗併入新版 Hydrogen；預期穩定後，Vercel Shop 會成為 Hydrogen + Next.js 的參考實作。

公開證據不足以可靠量化目前 Shopify headless 專案中 Vercel 與 Oxygen 各自的市場占比。比較穩妥的判斷是：Next.js 團隊採 Vercel 是自然且成熟的路線；Hydrogen + Oxygen 是 Shopify 官方整合路線；新版 Hydrogen 正在縮小兩者之間的功能落差，但仍需留意 preview 風險。

給你的建議：預設架構與導入方式

建議的預設架構

Next.js + Vercel 作為部署預設；新版 Hydrogen toolkit 作為 Shopify commerce layer 的試用與逐步導入選項。

這不是把 Next.js 專業換成 Hydrogen，而是將責任切清楚：

  • Next.js：路由、頁面架構、rendering、資料快取與 invalidation。
  • Hydrogen toolkit：Shopify Storefront API client、cart、Shop Pay、Shopify analytics 等 Shopify 專屬能力。
  • Vercel：CI/CD、preview、hosting、edge delivery 與用量管理。

這個分工符合新版 Hydrogen 的方向，也與 Vercel 公開展示的 Next.js + Hydrogen 模式一致。

導入方式

  1. 新案先做技術試點，不要整批遷移。 用一個內部 storefront 或低風險客戶案測試 preview 版 Hydrogen，涵蓋商品、變體、購物車、Market／語系、analytics、Shop Pay、錯誤處理與快取。
  2. 把 Agent skills 納入自己的工程規範。 新版 Hydrogen 會把 skills 複製到專案，且要求套件升級後同步 skills；可以把版本檢查、型別檢查與 smoke test 加進 CI。官方提供 npx @shopify/hydrogen skills sync 與 skills check 指令。
  3. 建立 Shopify Next.js 基準專案。 對多案代理商來說，真正的優勢是可重複使用的架構、Agent context、測試與部署規範，而不是每個案子重新挑 hosting。
  4. 做成本與 runtime benchmark。 用同一組流量假設比較 Vercel 用量與 Oxygen；同時測試 Vercel 快取命中率、動態請求成本，以及 Oxygen 是否能支援實際依賴的 API。Vercel 公開計價包含用量型資源，Oxygen 則有 worker 限制，兩者都不宜只用「每月基礎費」比較。
  5. 保留成熟方案作為 production fallback。 在新版 Hydrogen 的 API 穩定、功能完整且測試通過前，不建議把所有客戶案綁到 preview API。

**最終判斷：**你不需要在「Vercel 或 Hydrogen」之間二選一。短期最務實的做法是維持 Next.js + Vercel，並評估新版 Hydrogen toolkit 是否能消除重複的 Shopify commerce glue code；只有當某些客戶案明確受益於 Shopify 整合部署、且框架與 runtime 限制都符合時，才優先考慮 Hydrogen + Oxygen。

新版 Hydrogen Toolkit 是什麼

新版 Hydrogen 不再要求你用整套 storefront framework。它比較像一套 Shopify commerce SDK + Agent Skills：Next.js 仍然負責 App Router、頁面、Server Components、資料快取與部署；Hydrogen 則提供 Shopify Storefront API、購物車、商品變體、搜尋、Shop Pay、Analytics 等商務功能的共用實作。

架構示意：

Browser
  ↓
Next.js UI、路由、rendering、cache
  ↓
Hydrogen toolkit：Shopify API、cart、search、analytics 等
  ↓
Shopify Storefront API / Customer Account API

Hydrogen toolkit 不取代 Next.js，也不強制使用 Oxygen。官方把新版描述為可用於不同 JavaScript framework 和 runtime 的 toolkit；Next.js + Vercel 是官方列出的支援路線之一。

它提供哪些能力

能力 Toolkit 大致負責什麼 對你的實際意義
Storefront API client 建立具型別的 Shopify GraphQL client、gql() 查詢與錯誤處理 減少每個專案重寫 token、headers、API 呼叫封裝的機會
Request context 傳入 request、語系、買家 IP 等上下文 讓區域定價、語系、買家資訊等 API 行為一致；需依 host headers 正確取得資訊
Cart 伺服器端 cart handlers、購物車狀態 store、React bindings、表單與漸進式增強 共用 add/update/remove、樂觀更新、跨元件購物車狀態等基礎行為
商品與 collection 商品變體、collection 瀏覽、排序、篩選、分頁 提供 Shopify 專屬標準操作；視覺與互動設計仍由 Next.js UI 決定
Predictive search 搜尋 state、伺服器 handlers 與表單 helper 把常見 Shopify 搜尋資料流交給 toolkit，再由你控制搜尋 UI
Shopify 路由與 redirects Shopify 資源路徑、購物車／checkout 相關 handlers、商店 URL redirects 協助處理 Shopify storefront 常見路徑，但需接入 Next.js server request lifecycle
Money 與 Markets 貨幣格式化、國家／語言 context 減少錯誤格式化金額或忽略 Markets 區域脈絡的風險
Analytics 與 consent Shopify storefront analytics 及同意管理 提供 Shopify 標準事件與 consent 流程；仍需驗證實際資料是否進入 Shopify analytics
Shop Pay 與 Customer Accounts Shop Pay 按鈕、Customer Account API client 與帳戶流程 把部分 Shopify 特有功能納入可重用層；會員登入仍需要完整設定與端到端測試
Agent Skills 依安裝版本提供設定、購物車、搜尋、Markets、Analytics 等指引 Agent 可依專案內的說明建置，而不是只靠通用 LLM 知識猜 API 用法

它不會替你們決定網站的視覺設計、品牌體驗、CMS 架構、所有第三方 app 整合，也不會自動設計好 Next.js 的快取策略。官方方向是 Shopify API client 與商務邏輯由 Hydrogen 提供，Next.js 繼續負責 framework 層能力，例如快取與資料重新驗證。

在 Next.js 專案怎麼導入

官方文件列出的基本流程是在既有 Next.js 專案加入 preview toolkit：

npx create-next-app@latest my-store
cd my-store
npx @shopify/hydrogen@preview setup

setup 會安裝 preview 套件並複製對應的 Agent Skills；接著要在 Shopify Headless sales channel 建立 Storefront API 存取，並設定商店網域與 token。

設定值大致會包含：

PUBLIC_STORE_DOMAIN="your-shop.myshopify.com"
PUBLIC_STOREFRONT_API_TOKEN="..."
PRIVATE_STOREFRONT_API_TOKEN="..."

公開 token 可供瀏覽器使用；private token 僅能在伺服器端使用，不能暴露到 client bundle。建議加上 CI 檢查與程式碼 review 規範。

伺服器端以 request-scoped client 查詢 Shopify，例如：

import {
  createShopifyRequestContext,
  createStorefrontClient,
  gql,
} from "@shopify/hydrogen";

const requestContext = createShopifyRequestContext({
  request,
  i18n: { language: "EN", country: "US" },
  buyerIp,
});

const storefront = createStorefrontClient({
  type: "private",
  requestContext,
  config: {
    storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
    privateStorefrontToken:
      process.env.PRIVATE_STOREFRONT_API_TOKEN!,
  },
});

const { data } = await storefront.graphql(
  gql(`
    query Home {
      products(first: 3) {
        nodes { handle title }
      }
    }
  `),
);

重點不是照抄這段，而是理解責任邊界：Hydrogen 建立 Shopify client 和 query 型別；Next.js 的 server code 負責在正確的 request context 中呼叫它，並決定如何快取結果。

Cache 還是交由 Next.js 管理

不應假設「裝了 Hydrogen 就有完整的 Next.js cache 策略」。Shopify 與 Vercel 的示範方向是：Hydrogen 提供 typed Storefront API client，Next.js 控制快取與 revalidation。建議把每類資料明確分級：

  • 公開、相對穩定資料：商品描述、collection 資訊，可採 Next.js cache，並設定可控的重新驗證策略。
  • 價格、庫存、Markets 相關資料：確認是否受地區、買家或即時庫存影響，再決定快取鍵與有效時間。
  • 個人化資料：cart、Customer Account、會員訂單等，不應因不當快取設定而跨使用者共用。
  • checkout 與 redirect：由 Shopify 的正確 URL／handler 行為負責，納入端到端測試。

實際 cache tags、revalidation 和資料新鮮度需求，要依每個店家的 Markets、庫存與促銷規則確認，不能只套一種預設值。

Agent Skills 對全 Agent coding 的價值

新版差異不只在 SDK，也把 Agent 使用方式納入產品設計。安裝時會把 skills 放進專案的 Agent skills 目錄；技能涵蓋 Hydrogen setup、Storefront client、request handlers、routing、cart、collection、search、variant、Markets、Analytics、Shop Pay、Customer Accounts 與 smoke tests 等。

對全 Agent coding 團隊，這表示可把「Shopify storefront 的固定工程知識」從長篇 prompt 或個人記憶，轉成隨套件版本管理的專案文件。Agent 不只生成購物車畫面，還會依 skill 接入 cart handlers、狀態 store 和型別；官方 repo 也提到 setup skill 會協助建置基本 storefront、執行 typecheck 並做 smoke test。

但 skills 不是自動保證正確性的測試系統。仍需自行建立：

  • 對 Storefront API query、型別與 token 使用方式的檢查
  • cart、變體、折扣、Markets、Customer Account 的測試情境
  • hydrogen-setup 產生程式碼的 review checklist
  • 套件升級後同步 skills，並在 CI 檢查 skill 是否與安裝版本一致（使用 npx @shopify/hydrogen skills sync 與 skills check）

Preview 階段的風險與建議

新版 Hydrogen 目前仍標示為 developer preview，與舊版（React Router 核心）不同。官方建議：若要使用 Shopify 完整支援的 React Router 路徑，可採用目前正式 Hydrogen；若要在 Next.js 等框架使用新的 commerce primitives，則使用 developer preview。

Preview 正在快速迭代，例如近期更新涵蓋 cart session attribution、Cart attributes、Shopify 標準 page-view events、Customer Account 本機 HTTPS、商品 ?variant= 路徑，以及外部 cart mutation 後的 cart refresh。功能活躍也代表升級與相容性需要納入工程管理。

具體落地做法

  1. 先用一個內部店或低風險案建立 Next.js + Vercel proof of concept。 比較現有 Shopify client／cart 程式與 Hydrogen toolkit 的差異。
  2. 挑完整購物流程測試，不只測首頁和商品頁。 至少驗證 variant、add/update/remove、cart drawer、checkout、登入／登出、Markets、consent analytics、redirect，以及手機瀏覽器行為。
  3. 把 Hydrogen 包成公司自己的 adapter。 例如統一 getProduct、getCollection、getCart、mutateCart 等內部介面，讓頁面元件不直接依賴低階 Shopify query 細節。
  4. 鎖定套件版本，避免 preview 自動升級。 用 lockfile 和明確版本範圍控制更新；每次升級跑型別檢查、Agent skills 同步檢查與 storefront smoke tests。
  5. 先採用共用且低風險的 primitives。 Storefront API client、money formatting、cart、analytics 等可逐項評估；不必一次採納所有 route handlers 或替換現有架構。
  6. 把 Next.js cache policy 留在掌控中。 Hydrogen 解決 Shopify commerce glue code，不應讓 Agent 自動替價格、庫存、會員或 cart 做未經審核的共用快取。

**整體建議：**新版 Hydrogen toolkit 值得在 Next.js/Vercel 標準架構中做試點，尤其是大量使用 Agent coding 時，skills 與共享 commerce primitives 可能直接減少重複實作。但目前宜把它視為可評估、可逐步導入的 Shopify 整合層，而不是已完全穩定、應立即全面重構的基礎設施。