使用 Claude Code 的 Shopify 開發工作流程

本節涵蓋讓 Claude Code 成為 Shopify 開發不可或缺工具的實務工作流程。每個工作流程都是您會反覆使用的模式——從建構新應用程式到凌晨 2 點除錯生產環境的 webhook 故障。

使用自然語言建構應用程式

傳統啟動 Shopify 應用程式的方式涉及瀏覽文件、選擇範本和手動設定樣板程式碼。使用 Claude Code，您只需用簡單的語言描述您想要的東西。

啟動新的 Remix 應用程式

建構完整的 Shopify 應用程式
> Create a new Shopify Remix app for managing product bundles.
  It should have:
  - A page listing all products with bundle tagging
  - A bundle creation form using Polaris
  - GraphQL queries for product listing and metafield management
  - A webhook handler for orders containing bundles
  - Prisma schema for storing bundle configurations

Claude Code 會生成完整的檔案結構、撰寫每個檔案、設定 Prisma 結構、建立 GraphQL 查詢檔案，並將所有東西連接在一起。它了解 Shopify Remix 應用程式範本的慣例並遵循它們。

從 Shopify CLI 範本開始

為了最佳結果，先用 Shopify CLI 建構基礎應用程式，然後使用 Claude Code 在上面建構功能：

shopify app init --template remix
cd my-app
claude

這給 Claude Code 一個已經設定好驗證、工作階段處理和 App Bridge 的適當基礎。

建構應用程式擴充

應用程式擴充（佈景主題擴充、結帳 UI 擴充、管理介面 UI 擴充）有特定的檔案結構要求。Claude Code 能原生處理這些：

建立結帳 UI 擴充
> Create a checkout UI extension that displays a loyalty points
  summary. It should show the customer's current points balance
  and how many points they'll earn from this purchase. Use the
  Checkout UI extensions API with React.

Claude Code 會生成 shopify.extension.toml 設定、使用結帳 UI 元件（Banner、Text、BlockStack）的 React 元件，以及任何必要的工具函式。

生成 GraphQL 查詢

Shopify 的 Admin API 以 GraphQL 為優先，撰寫正確的查詢是最常見的任務之一。Claude Code 在這方面表現出色，因為它深入理解 Shopify GraphQL 結構。

商品查詢

生成分頁商品查詢
> Write a GraphQL query to fetch products with their variants,
  prices, inventory levels, and metafields. Include cursor-based
  pagination. Use the 2025-01 API version.

Claude Code 會產出：

app/graphql/products.ts
export const PRODUCTS_QUERY = `#graphql
  query GetProducts($first: Int!, $after: String) {
    products(first: $first, after: $after) {
      edges {
        cursor
        node {
          id
          title
          status
          totalInventory
          variants(first: 10) {
            edges {
              node {
                id
                title
                price
                inventoryQuantity
                selectedOptions {
                  name
                  value
                }
              }
            }
          }
          metafields(first: 5) {
            edges {
              node {
                namespace
                key
                value
                type
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
`;

變更操作生成

生成批次變更操作
> Write a GraphQL mutation to update product metafields in bulk,
  including the TypeScript types for the variables and response.

Claude Code 避免的常見 GraphQL 陷阱

忘記 userErrors：Claude Code 始終在變更操作回應中包含 userErrors { field, message }
錯誤的 ID 格式：它使用正確的 gid://shopify/Product/123 格式
缺少分頁：它預設使用基於游標的分頁，而不是擷取無限制的列表
API 版本不匹配：當您的 CLAUDE.md 指定了 API 版本時，它會尊重該版本的結構

使用 Claude Code 進行佈景主題開發

佈景主題開發涉及 Liquid 模板、JSON 結構、CSS 和 JavaScript 共同運作。Claude Code 可以無縫地在這個多語言環境中導航。

建立自訂區段

建構自訂區段
> Create a Liquid section called "featured-collection-tabs" that
  displays products from multiple collections in a tabbed interface.
  Include the section schema with settings for:
  - Up to 5 collection pickers
  - Tab style (underline, pill, boxed)
  - Products per tab (4, 8, 12)
  - Mobile layout option (scroll, stack)
  Make it accessible and performant.

Claude Code 會生成完整的區段：帶有適當 {% schema %} 區塊的 Liquid 模板、響應式 CSS、用於標籤功能的原生 JavaScript，以及帶有 ARIA 屬性的語意化 HTML。

佈景主題區塊和應用程式區塊

為佈景主題建立應用程式區塊
> Create a theme app extension block that displays real-time
  inventory status on product pages. It should show "In Stock",
  "Low Stock" (under 5), or "Out of Stock" badges with appropriate
  colors. Include the block schema and Liquid template.

使用 JSON 模板

Shopify Online Store 2.0 使用 JSON 模板。Claude Code 理解這個結構：

修改 JSON 模板
> Add our new featured-collection-tabs section to the homepage
  template. Place it between the hero banner and the newsletter
  signup sections.

Claude Code 會讀取 templates/index.json，理解區段順序，並正確插入引用。

程式碼審查和重構

Claude Code 在審查 Shopify 程式碼的正確性、效能和最佳實務方面表現出色。

審查 Liquid 程式碼

審查區段的問題
> Review sections/product-main.liquid for:
  - Performance issues (N+1 queries, unnecessary Liquid loops)
  - Accessibility problems
  - Missing null checks on objects
  - SEO metadata gaps
  - Mobile responsiveness issues

重構舊版佈景主題

許多 Shopify 商店執行的是 Online Store 2.0 之前的舊版佈景主題。Claude Code 可以將它們現代化：

現代化舊版區段
> Refactor this product template from a sectioned theme (1.0) to
  Online Store 2.0 format. Convert hardcoded content to section
  settings and blocks. Preserve all existing functionality.

應用程式程式碼審查

審查應用程式程式碼
> Review the webhook handlers in app/webhooks/ for:
  - HMAC verification on all endpoints
  - Proper error handling and retry logic
  - Idempotency (handling duplicate webhook deliveries)
  - Response time (must respond within 5 seconds)
  - Logging for debugging

Claude Code 了解 Shopify 最佳實務

審查程式碼時，Claude Code 會根據 Shopify 的實際要求進行檢查——例如 5 秒 webhook 回應期限、強制性 HMAC 驗證和速率限制閾值。它不僅檢查語法；還檢查 Shopify 特定的正確性。

撰寫測試

測試 Shopify 應用程式需要模擬 Shopify 的 API 回應、工作階段處理和 webhook 載荷。Claude Code 能生成全面的測試套件。

GraphQL 處理器的單元測試

為載入器生成測試
> Write Vitest tests for the products loader in app/routes/app.products.tsx.
  Mock the GraphQL admin client and test:
  - Successful product listing with pagination
  - Empty product list handling
  - GraphQL error responses
  - Unauthenticated session redirect

Webhook 處理器測試

測試 webhook 處理器
> Write tests for the ORDER_CREATED webhook handler. Include:
  - Valid HMAC verification test
  - Invalid HMAC rejection test
  - Duplicate webhook idempotency test
  - Malformed payload handling
  - Database error recovery

除錯生產環境問題

當生產環境出現問題時，Claude Code 成為您的除錯夥伴。提供錯誤日誌，它會追蹤問題。

Webhook 故障

除錯 webhook 故障
> Here are the last 5 failed webhook deliveries from Shopify:
  [paste webhook delivery details from Partner Dashboard]

  Diagnose why these are failing and fix the issue.

Claude Code 會分析錯誤模式、檢查您的 webhook 處理器程式碼、識別根本原因（逾時、HMAC 不匹配、未處理的載荷結構），並實施修復。

GraphQL 速率限制

修復速率限制問題
> Our app is hitting Shopify's GraphQL rate limit during bulk
  product syncs. The current code fetches products in a loop
  without throttling. Fix this to respect the 2000-point bucket
  with leak rate, and add proper cost tracking.

工作流程速查表

任務	提示詞模式
新區段	「建立一個名為 X 的 Liquid 區段，可以...」
GraphQL 查詢	「撰寫一個 GraphQL 查詢來擷取帶有 Y 的 X...」
Webhook 處理器	「建立一個 X 的 webhook 處理器，可以...」
錯誤修復	「當...時發生此錯誤 [貼上錯誤]。修復它。」
測試套件	「為 X 撰寫涵蓋 Y、Z 情境的測試」
重構	「將 X 重構為遵循 [模式/標準]」
程式碼審查	「審查 X 的 [具體關注點]」
遷移	「將 X 從 [舊] 遷移到 [新]」

這些模式之所以有效，是因為 Claude Code 可以完全存取您的程式碼庫。它讀取相關檔案、理解上下文，並做出與專案其餘部分一致的變更。

下一步

現在您已經理解了核心工作流程，請前往提示詞工程取得可直接使用的提示詞模板，以加速您使用 Claude Code 進行 Shopify 開發。

使用自然語言建構應用程式​

啟動新的 Remix 應用程式​

建構應用程式擴充​

生成 GraphQL 查詢​

商品查詢​

變更操作生成​

使用 Claude Code 進行佈景主題開發​

建立自訂區段​

佈景主題區塊和應用程式區塊​

使用 JSON 模板​

程式碼審查和重構​

審查 Liquid 程式碼​

重構舊版佈景主題​

應用程式程式碼審查​

撰寫測試​

GraphQL 處理器的單元測試​

Webhook 處理器測試​

除錯生產環境問題​

Webhook 故障​

GraphQL 速率限制​

工作流程速查表​

下一步​