操作教學 · Tutorial 2026 夏季號
skills.tenten.co · Shopify Headless 系列
H
教學系列 · Shopify Headless × Agentic Coding

Shopify Headless
開發環境與 Agentic
工作流建置

建立 Hydrogen(React Router 7)專案,連結商店,配置 Shopify Dev MCP 與 AI Toolkit,部署 Oxygen。六個步驟,完成可由 Claude Code 全程開發的環境。

6
操作步驟
7
環境變數
6
Dev MCP 工具
$0
Oxygen 額外費用
01
全貌與目標

Stack 組成與
Dev MCP 的角色

Shopify headless 開發有兩條路:官方 stack Hydrogen + Oxygen(付費方案免額外費用,內建部署、預覽與回滾),或自組框架搭配 Storefront API 與 Headless channel。本教學採用前者。

Hydrogen 於 2025 年 5 月(2025.5.0)自 Remix 2 遷移至 React Router 7;目前 skeleton(2026.4.4)使用 React Router 7.16,@shopify/remix-oxygen 已移除。多數模型的訓練資料早於此次遷移,agent 憑記憶產出的程式碼會含過時 import 與不存在的欄位。Shopify Dev MCP 提供文件檢索與 GraphQL schema 驗證,將 agent 錨定在現行 API。

涵蓋:專案建立、商店連結與環境變數、MCP 配置、agent 規則(CLAUDE.md)、開發迴圈、Oxygen 部署。不涵蓋 Liquid 佈景主題與 App 開發。最終產出:連結真實商店、push 即部署、可由 Claude Code 全程開發的 Hydrogen 專案。

元件 角色
Hydrogen Shopify 官方 headless 框架,建立在 React Router 7 之上
Oxygen 邊緣部署平台;付費方案(Basic 以上與 Plus)免額外費用,不支援 Starter 與 dev store
Storefront API 商品、購物車、結帳資料的 GraphQL 介面
Customer Account API 客戶登入與帳戶功能的 OAuth 介面
Shopify Dev MCP agent 的文件檢索 + GraphQL schema 驗證,本機執行、免認證
Shopify AI Toolkit 官方 agent plugin,含 agent skills 與 Dev MCP,支援 Claude Code
環境建置 · 完整路徑
建立專案→ 連結商店→ 配置 MCP→ 定義規則→ Agentic 迴圈→ 部署 Oxygen
「React Router is the open-source React-based framework that Hydrogen is built on top of.」
Hydrogen 建立在開源的 React Router 框架之上。
— shopify.dev · Hydrogen and Oxygen fundamentals
02
前置需求

版本與帳號需求

Node 版本為硬性門檻:skeleton 的 engines 要求 ^22 || ^24,Shopify CLI 4.4 要求 >=22.12.0。官方 getting-started 頁的「Node 16」為過時資訊。

  • Node.js 22 或 24 — Hydrogen skeleton 與 Shopify CLI 的最低要求;用 nvm 或 mise 釘版本。
  • Claude Code — agentic 工作流的執行主體;MCP 註冊用它的 claude mcp add 指令完成。
  • Git 與 GitHub repo — Oxygen 的持續部署走 GitHub 整合,repo 在步驟六連結。
  • Shopify 商店的管理權限 — 建立 Hydrogen storefront 要進 admin 的 Sales channels;agency 場景下通常是你組織內的 Client Transfer Store。
  • 付費方案(部署時) — Oxygen 在付費方案免額外費用,但不支援 Starter 方案與 dev store;本機開發不受此限。
  • 商店非立即必要 — quickstart 使用 mock.shop 示範資料;步驟一、三、四不需真實商店。
Node 版本需為 22 或 24。開始前執行 node -v 確認。
03
步驟一 · 建立專案

建立 Hydrogen 專案

quickstart 的參數組合:JavaScript、mock.shop 示範資料、不設 markets、建立 h2 全域捷徑。需自選 TypeScript 或樣式方案(Tailwind、CSS Modules、vanilla-extract、PostCSS)時拿掉 --quickstart,CLI 逐項詢問。

# quickstart:mock.shop 資料、JS、跳過所有詢問 npm create @shopify/hydrogen@latest -- --quickstart # 或自選語言與樣式(CLI 逐項詢問) npm create @shopify/hydrogen@latest # 啟動本機開發伺服器(port 3000) cd hydrogen-quickstart && npm run dev

Starter 內含路由:首頁、商品頁、系列頁、購物車、帳戶、搜尋、部落格、政策頁、sitemap、robots.txt。後續開發以修改既有路由為主。

npm run dev 後,http://localhost:3000 渲染 mock.shop 示範商店。商品頁與購物車可操作;此時尚未連結真實商店。
05
步驟三 · 配置 MCP

配置 Shopify Dev MCP

Shopify Dev MCP 於本機執行,不需認證。個人使用一行註冊;團隊 repo 加 --scope project,設定寫入專案根目錄 .mcp.json,commit 後全隊共用;每位成員首次使用需核准一次。

# 官方指令:註冊 Shopify Dev MCP(個人 scope) claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest # 團隊版:寫進專案 .mcp.json,可 commit 進版本庫 claude mcp add --transport stdio shopify-dev-mcp --scope project -- npx -y @shopify/dev-mcp@latest # 官方 AI Toolkit plugin(含 agent skills;需 Node 18+) claude plugin install shopify-ai-toolkit@claude-plugins-official
{ "mcpServers": { "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] } } }

1.14.2 版的六個工具。其他工具要求先呼叫 learn_shopify_api 取得 conversationId;未呼叫時一律拒絕。

工具 作用
learn_shopify_api 載入指定 API 的背景知識並發 conversationId;每個對話的第一步
search_docs_chunks 以使用者需求搜尋 shopify.dev 文件與程式範例
validate_graphql_codeblocks 對真實 schema 驗證 GraphQL 程式碼,防幻覺欄位;支援 Admin、Storefront、Partner、Customer API
validate_theme 驗證佈景主題目錄內的檔案
validate_theme_codeblocks 驗證生成的佈景主題程式碼區塊
validate_component_codeblocks 驗證 Storefront Web Components 用法(early access,需設 STOREFRONT_WEB_COMPONENTS 環境旗標)
QA 迴圈可另接瀏覽器 MCP。chrome-devtools-mcp 與 @playwright/mcp(npm)可讓 agent 修改後自行開頁驗證。
Claude Code 輸入 /mcp,shopify-dev-mcp 顯示已連線並列出 6 個工具。團隊場景另確認 .mcp.json 已 commit。
06
步驟四 · 定義規則

CLAUDE.md 工作規則

Shopify 未發布官方 CLAUDE.md 範本;最接近的官方資產為 shopify.dev/llms.txt 與 AI Toolkit 的 agent skills。以下為 Tenten 內部範本,將步驟三的工具設為 agent 的固定流程:

# Hydrogen storefront — agent 工作規則 ## Shopify API - Shopify 相關任務先呼叫 shopify-dev-mcp 的 learn_shopify_api, 再用 search_docs_chunks 查現行文件;不要憑記憶寫 API 用法。 - 任何 Storefront / Admin / Customer GraphQL 查詢, 提交前必須通過 validate_graphql_codeblocks。 ## 框架邊界 - 本專案是 React Router 7,不是 Remix: 禁止 import @shopify/remix-oxygen 或 Remix 時代的套件。 ## 環境與驗證 - 環境變數一律經 context.env 讀取; 缺變數先跑 npx shopify hydrogen env pull,不要硬編。 - 開發伺服器 npm run dev(port 3000); GraphQL 手動驗證用 http://localhost:3000/graphiql。 - 改動完成後在瀏覽器實際走過受影響的頁面,再回報完成。
新開 Claude Code session 交付一個小任務,agent 的第一個 Shopify 動作為 learn_shopify_api。若 agent 直接憑記憶寫 GraphQL,檢查 CLAUDE.md 是否位於專案根目錄。
07
步驟五 · Agentic 迴圈

Agentic 迴圈驗收

以一個真實任務驗收環境。標準迴圈:查文件、寫查詢、驗證 schema、修改程式、瀏覽器確認。validate_graphql_codeblocks 攔截 schema 中不存在的欄位與操作。

~/clients/store-a · claude code · shopify-dev-mcp 1.14
You › 商品頁加上「庫存低於 10 件時顯示急迫提示」,用 Storefront API 的庫存欄位。
[shopify-dev-mcp] learn_shopify_api(api: storefront) → conversationId 取得 [shopify-dev-mcp] search_docs_chunks("product variant inventory quantity")
Claude › 文件確認 Storefront API 用 variant 的 quantityAvailable 欄位, 需要在商品查詢裡展開 variants。先驗證查詢:
[shopify-dev-mcp] validate_graphql_codeblocks → ✓ 查詢合法,無幻覺欄位
[edit] app/routes/products.$handle.jsx — loader 加入 quantityAvailable,UI 加入條件提示 [bash] npm run dev — port 3000 起動,無編譯錯誤
✓ 商品頁在庫存 < 10 的 variant 顯示急迫提示;GraphiQL 抽查兩個商品,數字與 admin 一致。
該輪任務中,agent 至少各呼叫一次 search_docs_chunks 與 validate_graphql_codeblocks,且驗證通過。未經 MCP 完成的 Shopify 任務,抽查其 GraphQL。
08
步驟六 · 部署

部署 Oxygen

GitHub 持續部署:在 Sales channels → Hydrogen → Create storefront 流程中選 Set up GitHub continuous deployment now,選定 organization 與 repo,按 Connect;merge Shopify 自動建立的 workflow PR。之後每次 push 產生 preview deployment,預設分支對應 production。

環境結構:production 綁定預設分支;custom environments 綁定指定分支;其餘分支為 preview。deployment 不可變(immutable)且各有獨立網址;在 admin 修改環境變數會觸發相關環境重新部署。回滾僅支援 production 與 custom environments。

# 不走 GitHub 整合時,手動部署: npx shopify hydrogen deploy # GitHub 整合自動生成的 workflow 檔(merge 該 PR 即可,不要改動 id 行): # .github/workflows/oxygen-deployment-0000000000.yml # 內含 "#! oxygen_storefront_id: …" 釘選行,官方註明 Don't change
Oxygen 資源上限。worker bundle 10 MB、單一請求 CPU 30 秒、記憶體 128 MB;靜態資產影像 20 MB、影片 1 GB、3D 模型 500 MB。重運算移至 worker 之外。
push 任一分支得到 preview URL;merge 進預設分支後,admin 的 Hydrogen storefront 顯示新的 production deployment。兩個網址都實際打開驗證。
09
常見錯誤與邊界

常見錯誤與版本邊界

  • Remix 時代的範例已過時。Hydrogen 2025.5.0 起改用 React Router 7,@shopify/remix-oxygen 已移除;agent 產出含 remix 相關 import 時退回重寫。
  • getting-started 頁的 Node 16 為過時資訊。以套件 engines 為準:skeleton 要求 Node 22 或 24,CLI 4.4 要求 22.12 以上。
  • Dev MCP 舊工具名已移除。introspect_admin_schema、fetch_full_docs 不存在於 1.14.2;現行入口為 learn_shopify_api,未先呼叫時其他工具一律拒絕。
  • Oxygen 不支援 Starter 方案與 dev store。本機開發不受影響;部署驗收需在付費方案商店進行。
  • Storefront MCP 非開發工具。商店的 /api/mcp 端點(search_catalog、get_cart 等)供購物 agent 使用;開發迴圈使用本機的 Shopify Dev MCP。
  • .env 不進版本庫。PRIVATE_STOREFRONT_API_TOKEN 與 SESSION_SECRET 為伺服器端秘密;正式環境變數在 admin 的 Environments and variables 管理。
  • 客戶登入在本機需要 tunnel。Customer Account API 的 OAuth 回呼要求 --customer-account-push;未開 tunnel 的 localhost 不在允許清單。
  • project scope 的 MCP 需逐人核准。.mcp.json commit 後,每位成員首次啟動顯示 pending approval;屬預期行為。
10
完成檢查與下一步

完成檢查與下一步

最終狀態:專案連結真實商店;agent 具文件檢索與 schema 驗證;每次 push 產生 preview。逐項確認:

  • Hydrogen 專案在本機跑起來 — 步驟一的產出;localhost:3000 正常渲染。
  • .env 含 7 個變數、dev server 讀真實商店 — 步驟二的產出。
  • .mcp.json 進版本庫、/mcp 列出 shopify-dev-mcp — 步驟三的產出。
  • CLAUDE.md 規則生效 — 步驟四的產出;新 session 的第一個 Shopify 動作是 learn_shopify_api。
  • 一輪任務含 GraphQL 驗證通過 — 步驟五的產出。
  • push → preview、merge → production — 步驟六的產出;兩個網址都開過。

下一步

1. 環境模板化。CLAUDE.md、.mcp.json 與 workflow 檔各客戶案相同;收進 template repo,新案 clone 即用。
2. Agentic commerce。shopify.dev/docs/agents 的 UCP 體系(Catalog、Cart、Checkout、Order MCP)為商店側介面,供購物 agent 消費商店,與本篇的開發側互補。
3. QA 迴圈加瀏覽器。將 chrome-devtools-mcp 或 @playwright/mcp 加入 .mcp.json,由 agent 驗證頁面行為。

最該讀的延伸文件

① Hydrogen getting started(shopify.dev)——scaffold 與初始設定的官方版本。
② Shopify Dev MCP(shopify.dev)——各 agent 平台的官方安裝指令與說明。
③ Claude Code MCP 文件(code.claude.com)——scope 規則、.mcp.json 格式與核准機制。

「Validates GraphQL code blocks against the Shopify GraphQL schema to ensure they don't contain hallucinated fields or operations.」
對 Shopify GraphQL schema 驗證程式碼,確保沒有幻覺欄位與操作。
— @shopify/dev-mcp · validate_graphql_codeblocks 工具說明