Shopify Headless 開發環境完整教學|Hydrogen + Claude Code Agentic 工作流

01全貌與目標

Stack 組成與 Dev MCP 的角色

本教學採用 Shopify 官方 stack Hydrogen + Oxygen（付費方案免額外費用，內建部署、預覽與回滾）。另一種 headless 開發方式是自組框架搭配 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。

產出為連結真實商店、push 即部署、可由 Claude Code 全程開發的 Hydrogen 專案。

涵蓋範圍：

專案建立
商店連結與環境變數
MCP 配置
agent 規則（CLAUDE.md）
開發迴圈
Oxygen 部署

不涵蓋 Liquid 佈景主題與 App 開發。

元件	角色
`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 示範資料；步驟一、三、四不需真實商店。

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

04步驟二 · 連結商店

商店連結與環境變數

在商店 admin 建立 Hydrogen storefront:Sales channels → Hydrogen → Create storefront。Shopify 同時自動產生該 storefront 的環境變數。回到專案執行：

# 連結本機專案與遠端 Hydrogen storefront
npx shopify hydrogen link

# 把 storefront 的環境變數寫進 .env
npx shopify hydrogen env pull

# 需要 Customer Account API(客戶登入)時,用 tunnel 啟動 dev
npx shopify hydrogen dev --customer-account-push

環境變數	用途
`PUBLIC_STORE_DOMAIN`	商店網域，如 example.myshopify.com
`PUBLIC_STOREFRONT_API_TOKEN`	Storefront API 公開 token，客戶端查詢用
`PRIVATE_STOREFRONT_API_TOKEN`	私密 token，伺服器端查詢用；不可外流
`PUBLIC_STOREFRONT_ID`	storefront 的識別 ID
`PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID`	Customer Account API 的 OAuth client ID
`PUBLIC_CUSTOMER_ACCOUNT_API_URL`	Customer Account API 端點
`SESSION_SECRET`	React Router 簽署 session cookie 用的密鑰

程式碼經 context.env.<NAME> 讀取變數；正式環境變數在 admin 的 Storefront settings → Environments and variables 管理。--customer-account-push 經 tryhydrogen.dev 網域開 tunnel 並同步回呼網址，為本機測試客戶登入（OAuth）的必要條件。

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` 環境旗標）

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。
- 改動完成後在瀏覽器實際走過受影響的頁面,再回報完成。

07步驟五 · Agentic 迴圈

Agentic 迴圈驗收

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


$ You › 商品頁加上「庫存低於 10 件時顯示急迫提示」,用 Storefront API 的庫存欄位。


# [shopify-dev-mcp] learn_shopify_api(api: storefront) → conversationId 取得
# [shopify-dev-mcp] search_docs_chunks("product variant inventory quantity")


claude: 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 起動,無編譯錯誤


ok: ✓ 商品頁在庫存 < 10 的 variant 顯示急迫提示;GraphiQL 抽查兩個商品,數字與 admin 一致。

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

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 工具說明

全站搜尋

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

Stack 組成與 Dev MCP 的角色

建立專案

連結商店

配置 MCP

定義規則

Agentic 迴圈

部署 Oxygen

版本與帳號需求

建立 Hydrogen 專案

商店連結與環境變數

配置 Shopify Dev MCP

CLAUDE.md 工作規則

Agentic 迴圈驗收

部署 Oxygen

常見錯誤與版本邊界

完成檢查與下一步

下一步

延伸文件

參考資料

建立專案

連結商店

配置 MCP

定義規則

Agentic 迴圈

部署 Oxygen

下一步

延伸文件

參考資料

相關文件

13 個代理的 Shopify 工廠 — 單人操作者的架構與成本結構拆解

Shopify 全代理開發指南：Claude Code × Codex × MCP 安裝、設定與 30 天建站流程（2026）

Shopify AI Toolkit 實戰手冊｜20 個技能涵蓋 Admin、Liquid、Polaris、Functions