使用 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 schema，创建 GraphQL 查询文件，并将所有内容串联在一起。它了解 Shopify Remix 应用模板的约定并遵循它们。

从 Shopify CLI 模板开始

为获得最佳效果，先使用 Shopify CLI 搭建基础应用，然后使用 Claude Code 在此基础上构建功能：

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

这为 Claude Code 提供了一个已配置好认证、会话处理和 App Bridge 的正确基础。

搭建应用扩展

应用扩展（主题扩展、Checkout UI 扩展、Admin UI 扩展）有特定的文件结构要求。Claude Code 原生处理这些：

创建 Checkout 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 配置文件、使用 Checkout UI 组件（Banner、Text、BlockStack）的 React 组件，以及任何必要的工具函数。

生成 GraphQL 查询

Shopify 的 Admin API 以 GraphQL 为优先，编写正确的查询是最常见的任务之一。Claude Code 在这方面表现出色，因为它深入理解 Shopify GraphQL schema。

产品查询

生成分页产品查询
> 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 版本时，它会遵循该版本的 schema

使用 Claude Code 进行主题开发

主题开发涉及 Liquid 模板、JSON schema、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 处理程序的单元测试

为 loader 生成测试
> 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

端到端主题测试

为主题生成 Playwright 测试
> Write Playwright tests for the product page that verify:
  - Variant selector updates price display
  - Add to cart works and updates cart count
  - Quantity selector respects inventory limits
  - Image gallery navigation works
  - Mobile responsive layout at 375px width

调试生产问题

当生产环境出现问题时，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.

主题渲染问题

调试 Liquid 渲染
> Customers report that product metafields show as blank on
  some products but work on others. Here's the Liquid code:
  {{ product.metafields.custom.care_instructions.value }}
  Debug why this would be intermittent.

为 Shopify 项目创建 CLAUDE.md 模板

根据上述工作流，以下是你的 Shopify 项目 CLAUDE.md 的推荐结构。详细模板在 CLAUDE.md 模板部分介绍，这里是高级结构：

CLAUDE.md 结构概览
# Project Name

## Overview
Brief project description and purpose.

## Tech Stack
Framework, language, database, UI library.

## Shopify Configuration
API version, app type, scopes, extensions.

## Commands
Dev server, build, test, deploy commands.

## File Structure
Key directories and their purposes.

## Coding Standards
Language-specific conventions and Shopify rules.

## Testing Requirements
Test framework, coverage expectations, what to test.

## Common Patterns
Recurring patterns specific to your project.

## Known Issues
Active bugs or workarounds Claude should know about.

CLAUDE.md 的关键规则

始终在 CLAUDE.md 中包含你的 Shopify API 版本。如果没有，Claude Code 可能会默认使用不同的版本，生成引用已弃用或不存在字段的代码。一行简单的 API Version: 2025-01 就能避免数小时的调试。

工作流速查表

任务	提示模式
新版块	"Create a Liquid section called X that..."
GraphQL 查询	"Write a GraphQL query to fetch X with Y..."
Webhook 处理程序	"Create a webhook handler for X that..."
修复 Bug	"This error occurs when... [paste error]. Fix it."
测试套件	"Write tests for X covering Y, Z scenarios"
重构	"Refactor X to follow [pattern/standard]"
代码审查	"Review X for [specific concerns]"
迁移	"Migrate X from [old] to [new]"

每个模式之所以有效，是因为 Claude Code 可以完整访问你的代码库。它读取相关文件，理解上下文，并做出与项目其余部分一致的更改。

下一步

现在你已经理解了核心工作流，继续学习提示工程以获取可直接使用的提示模板，加速你使用 Claude Code 进行 Shopify 开发。

使用自然语言搭建应用​

启动新的 Remix 应用​

搭建应用扩展​

生成 GraphQL 查询​

产品查询​

变更生成​

使用 Claude Code 进行主题开发​

创建自定义版块​

主题区块和应用区块​

使用 JSON 模板​

代码审查和重构​

审查 Liquid 代码​

重构旧版主题​

应用代码审查​

编写测试​

GraphQL 处理程序的单元测试​

Webhook 处理程序测试​

端到端主题测试​

调试生产问题​

Webhook 故障​

GraphQL 速率限制​

主题渲染问题​

为 Shopify 项目创建 CLAUDE.md 模板​

工作流速查表​

下一步​