你的第一个 Shopify 应用

在本节课中，你将从零开始创建一个运行中的 Shopify 应用，并安装到你的开发店铺上。我们将使用 Shopify CLI 生成项目脚手架，理解文件结构，启动开发服务器，然后使用 Claude Code 构建你的第一个功能。

使用 `shopify app init` 创建脚手架

Shopify CLI 会生成一个包含认证、数据库和 UI 的完整应用项目。运行以下命令：

# Create a new Shopify app
cd ~/shopify-projects
shopify app init

# The CLI will prompt you:
# ? Your app project name: masterclass-app
# ? Get started building your app:
#   > Start with Remix (recommended)
#     Start with a blank extension-only app
#     Start with a template

选择 Start with Remix -- 这是 Shopify 推荐的框架，也是我们在整个课程中使用的。

# After scaffolding completes
cd masterclass-app

为什么选择 Remix？

Shopify 选择 Remix 作为其推荐的应用框架，因为它的服务端渲染模型、嵌套路由和出色的数据加载模式。Remix 的 actions 和 loaders 天然适配 Shopify 的 OAuth 流程和 API 调用。Shopify Remix 模板开箱即用，包含认证、会话管理和 App Bridge 集成。

理解项目结构

生成的项目有一个特定的结构，理解它很重要。每个目录都有明确的用途：

masterclass-app/
├── app/                          # Remix application
│   ├── routes/                   # Page routes (file-based routing)
│   │   ├── app._index.jsx        # Main app page (after auth)
│   │   ├── app.jsx               # App layout with nav
│   │   ├── auth.$.jsx            # OAuth callback handler
│   │   ├── auth.login/           # Login page
│   │   │   ├── route.jsx
│   │   │   └── login.css
│   │   └── webhooks.jsx          # Webhook handler
│   ├── shopify.server.js         # Shopify API client setup
│   ├── db.server.js              # Database connection (SQLite)
│   └── entry.server.jsx          # Remix server entry
├── extensions/                   # Shopify extensions (UI, Functions, etc.)
├── prisma/
│   └── schema.prisma             # Database schema
├── public/                       # Static assets
├── shopify.app.toml              # App configuration
├── shopify.web.toml              # Web server configuration
├── package.json
├── remix.config.js
└── .env                          # Environment variables (auto-generated)

关键文件说明

shopify.app.toml -- 应用清单。它定义了你的应用名称、权限范围和扩展配置：

name = "masterclass-app"
client_id = "your-client-id"
application_url = "https://your-tunnel.trycloudflare.com"
embedded = true

[access_scopes]
scopes = "write_products,read_orders"

[webhooks]
api_version = "2026-04"

app/shopify.server.js -- Shopify API 客户端。此文件设置认证并提供 API 调用方法：

import "@shopify/shopify-app-remix/adapters/node";
import {
  ApiVersion,
  AppDistribution,
  shopifyApp,
} from "@shopify/shopify-app-remix/server";
import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
import prisma from "./db.server";

const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET || "",
  apiVersion: ApiVersion.April26,
  scopes: process.env.SCOPES?.split(","),
  appUrl: process.env.SHOPIFY_APP_URL || "",
  authPathPrefix: "/auth",
  sessionStorage: new PrismaSessionStorage(prisma),
  distribution: AppDistribution.AppStore,
  future: {
    unstable_newEmbeddedAuthStrategy: true,
  },
});

export default shopify;
export const apiVersion = ApiVersion.April26;
export const addDocumentResponseHeaders = shopify.addDocumentResponseHeaders;
export const authenticate = shopify.authenticate;
export const unauthenticated = shopify.unauthenticated;
export const login = shopify.login;
export const registerWebhooks = shopify.registerWebhooks;
export const sessionStorage = shopify.sessionStorage;

app/routes/app._index.jsx -- 你的应用主页面，作为嵌入式应用在 Shopify Admin 中渲染。

运行开发服务器

使用 Shopify CLI dev 命令启动你的应用：

shopify app dev

这一个命令做了大量工作：

CLI 将会：

启动 Remix 开发服务器 在 localhost:3000 上
创建 Cloudflare 隧道 用于 HTTPS 访问
更新你的应用 URL 在合作伙伴仪表板中
打开你的浏览器 将应用安装到你的开发店铺

首次运行需要更长时间

首次运行时，CLI 会创建数据库表、生成 OAuth 凭据并设置隧道。后续运行会快得多。

安装到开发店铺

当 CLI 打开你的浏览器时，你会看到一个 Shopify 授权页面。点击 Install app 授予请求的权限。安装后，你的应用主页面会嵌入显示在 Shopify Admin 中。

你应该看到一个使用 Shopify Polaris UI 的页面，显示 "Nice work on building a Shopify app" 以及一些示例内容。

使用 Claude Code 构建你的第一个功能

现在到了令人兴奋的部分 -- 使用 Claude Code 构建一个真正的功能。我们将添加一个产品统计仪表板，显示店铺中产品的总数及其状态分布。

在你的项目目录中打开 Claude Code：

cd ~/shopify-projects/masterclass-app
claude

给 Claude Code 这个提示：

Update the main app page (app/routes/app._index.jsx) to show a product
dashboard. Use the Shopify Admin GraphQL API to fetch the total number
of products and break them down by status (active, draft, archived).
Display the data using Polaris Cards and Layout components. Include a
loading state.

Claude Code 将会：

读取现有的 app._index.jsx 文件理解当前结构
编写一个调用 Shopify Admin API 的 Remix loader 函数
使用 GraphQL 查询按状态获取产品数量
更新 JSX 以渲染 Polaris Card、Layout 和 Text 组件
添加加载和错误状态

以下是生成的代码样子：

import { json } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import {
  Page,
  Layout,
  Card,
  BlockStack,
  Text,
  InlineGrid,
} from "@shopify/polaris";
import { authenticate } from "../shopify.server";

export const loader = async ({ request }) => {
  const { admin } = await authenticate.admin(request);

  const response = await admin.graphql(`
    {
      activeCount: productsCount(query: "status:active") {
        count
      }
      draftCount: productsCount(query: "status:draft") {
        count
      }
      archivedCount: productsCount(query: "status:archived") {
        count
      }
      totalCount: productsCount {
        count
      }
    }
  `);

  const data = await response.json();

  return json({
    products: {
      total: data.data.totalCount.count,
      active: data.data.activeCount.count,
      draft: data.data.draftCount.count,
      archived: data.data.archivedCount.count,
    },
  });
};

export default function Index() {
  const { products } = useLoaderData();

  return (
    <Page title="Product Dashboard">
      <Layout>
        <Layout.Section>
          <InlineGrid columns={4} gap="400">
            <Card>
              <BlockStack gap="200">
                <Text variant="headingSm">Total Products</Text>
                <Text variant="heading2xl">{products.total}</Text>
              </BlockStack>
            </Card>
            <Card>
              <BlockStack gap="200">
                <Text variant="headingSm">Active</Text>
                <Text variant="heading2xl" tone="success">
                  {products.active}
                </Text>
              </BlockStack>
            </Card>
            <Card>
              <BlockStack gap="200">
                <Text variant="headingSm">Draft</Text>
                <Text variant="heading2xl" tone="caution">
                  {products.draft}
                </Text>
              </BlockStack>
            </Card>
            <Card>
              <BlockStack gap="200">
                <Text variant="headingSm">Archived</Text>
                <Text variant="heading2xl" tone="subdued">
                  {products.archived}
                </Text>
              </BlockStack>
            </Card>
          </InlineGrid>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

保存文件并查看你的浏览器 -- Remix 会自动热重载，你应该能看到产品仪表板出现。

智能编程的优势

注意刚才发生了什么。你用自然语言描述了一个功能，Claude Code 就编写了 GraphQL 查询、Remix loader 和 Polaris UI。它知道使用 authenticate.admin(request) 是因为它读取了你现有的 shopify.server.js 文件。它知道使用 productsCount 是因为它理解 Shopify Admin API。这就是智能编程的实际运作。

检查点

在继续之前，请验证：

shopify app dev 启动无错误
你的应用已安装到开发店铺
产品仪表板显示来自你店铺的真实数据
你已成功使用 Claude Code 修改了你的应用

常见问题

"App not loaded" 错误：确保你使用的是 Cloudflare 隧道 URL，而不是 localhost。隧道由 shopify app dev 自动创建。

"Access denied" 错误：检查你的应用在 shopify.app.toml 中的权限范围是否包含 read_products。运行 shopify app dev --reset 重新认证。

产品计数为空：如果你的开发店铺没有产品，请进入 Shopify Admin 点击"Add product"创建一些测试产品，或使用批量导入功能。

你学到了什么

在本节课中你：

使用 Shopify CLI 生成了 Shopify Remix 应用脚手架
理解了项目结构和关键配置文件
运行了带有隧道和热重载的开发服务器
将应用安装到了开发店铺
使用 Claude Code 构建了产品仪表板功能

在下一节课中，我们将探索 Shopify 合作伙伴生态系统，了解 Shopify 开发的商业层面。

使用 shopify app init 创建脚手架​

理解项目结构​

关键文件说明​

运行开发服务器​

安装到开发店铺​

使用 Claude Code 构建你的第一个功能​

检查点​

你学到了什么​