教程

ShopFaaS 实战教程——从零搭建第一个店铺、配置收款与配送、开发第一个应用扩展、创建第一个主题。

本页提供 ShopFaaS 的端到端实战教程，带你从零完成具体任务。每个教程包含完整步骤与可复现代码。

教程 1：搭建第一个店铺

30 分钟从注册到上线一个完整独立站。

教程 2：开发第一个应用扩展

60 分钟开发一个订单通知应用并上架。

教程 3：创建第一个主题

45 分钟开发一个自定义店铺主题。

教程 4：对接 ERP 同步订单

使用 REST API 与 Webhook 对接外部 ERP。

教程 1：搭建第一个店铺

目标：从注册到上线一个完整独立站，含商品、收款、配送、域名。

预计耗时：30 分钟

适合：首次使用 ShopFaaS 的商家

注册账户

访问 ShopFaaS 官网，点击「免费注册」，填写邮箱、密码、店铺名称，完成邮箱验证。
创建店铺

选择行业（如「服饰」），选择免费主题「Classic」，填写店铺信息（名称、币种 CNY、语言简体中文），完成创建。
配置收款

进入「设置 → 收款」，启用 Stripe：
- 填入 Stripe Publishable Key 与 Secret Key
- 启用信用卡、Apple Pay、Google Pay
没有 Stripe 账户？
可先跳过此步，使用「线下支付」测试下单流程。正式营业前需配置在线支付。
配置配送

进入「设置 → 配送」：
- 创建运费区「中国」（地区选中国）
- 设置固定运费 ¥10，满 ¥199 免邮
- 创建运费区「其他地区」，固定运费 ¥80
上架第一个商品

进入「商品 → 新建商品」：
- 标题：纯棉 T 恤
- 价格：¥99
- 库存：100
- 上传商品图片
- 配置规格：颜色（黑/白）、尺码（S/M/L）
- 发布到在线商店
绑定自定义域名（可选）

进入「设置 → 域名」：
- 输入你的域名（如 shop.example.com）
- 在域名服务商添加 CNAME 记录指向 proxy.shopfaas.com
- 等待 SSL 证书签发（通常 5–10 分钟）
店铺上线

进入「设置 → 在线商店偏好设置」，将店铺状态从「密码保护」切换为「上线」。

访问 your-shop.shopfaas.com 确认前台可访问。
测试下单

在前台将商品加入购物车，完成结账，确认订单出现在后台「订单」列表。

教程 2：开发第一个应用扩展

目标：开发一个订单通知应用，订单创建时推送通知到企业微信/钉钉。

预计耗时：60 分钟

适合：有 TypeScript 基础的开发者

初始化项目

bunx @shopfaas/plugin-devkit init order-notify
cd order-notify

按提示填写应用名称、描述、作者。

声明权限

编辑 plugin.json：

{
  "name": "order-notify",
  "version": "1.0.0",
  "description": "订单创建时推送通知到企业微信/钉钉",
  "permissions": ["order:view"],
  "webhooks": [
    {
      "event": "order.created",
      "handler": "webhooks/order-created.ts"
    }
  ],
  "config_schema": "config-schema.ts",
  "ui": {
    "settings": "ui/Settings.tsx"
  }
}

定义配置 Schema

创建 config-schema.ts：

import { z } from "astro/zod";

export const configSchema = z.object({
  webhook_url: z.url({ message: "请输入有效的 Webhook URL" }),
  enabled: z.boolean().default(true),
});

export type Config = z.infer<typeof configSchema>;

实现 Webhook Handler

创建 webhooks/order-created.ts：

import type { WebhookHandler } from "@shopfaas/plugin-runtime";

const handler: WebhookHandler<"order.created"> = async (event, ctx) => {
  const config = await ctx.getConfig();
  if (!config.enabled) return;

  const { order_id } = event.payload;
  const order = await ctx.api.orders.get(order_id);

  await fetch(config.webhook_url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      msgtype: "markdown",
      markdown: {
        content: `### 新订单通知\n**订单号**：${order.order_number}\n**金额**：¥${order.total}\n**客户**：${order.customer?.name ?? "匿名"}`,
      },
    }),
  });
};

export default handler;

开发设置页 UI

创建 ui/Settings.tsx：

import { usePluginConfig } from "@shopfaas/plugin-bridge";

export default function Settings() {
  const [config, setConfig] = usePluginConfig();

  return (
    <div>
      <h2>订单通知设置</h2>
      <label>
        <input type="checkbox" checked={config?.enabled ?? true} onChange={e => setConfig({ ...config, enabled: e.target.checked })} />
        启用通知
      </label>
      <label>
        Webhook URL：
        <input type="url" value={config?.webhook_url ?? ""} onChange={e => setConfig({ ...config, webhook_url: e.target.value })} />
      </label>
    </div>
  );
}

本地测试
```
bunx @shopfaas/plugin-devkit dev
```
在店铺后台安装本地应用，创建一个测试订单，确认通知推送成功。

打包发布

bunx @shopfaas/plugin-devkit pack
bunx @shopfaas/plugin-devkit publish

等待自动化扫描 + 人工审核通过后上架。

教程 3：创建第一个主题

目标：开发一个极简风格的店铺主题，支持商品列表与详情页。

预计耗时：45 分钟

适合：有 HTML/CSS 基础，想学习 Liquid 模板的开发者

创建主题目录

mkdir -p themes/minimal/{templates,assets,locales,config}

编写主题配置

创建 themes/minimal/config/settings_schema.json：

{
  "name": "Minimal",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "极简风格主题",
  "settings": [
    { "type": "color", "id": "color_primary", "label": "主色", "default": "#1a1a1a" }
  ]
}

并创建 themes/minimal/config/settings_data.json（当前值）：

{
  "current": {
    "color_primary": "#1a1a1a"
  }
}

编写首页模板

创建 templates/index.liquid：

<h1>{{ shop.name }}</h1>
<div class="product-grid">
  {% for product in collections.frontpage.products %}
    <a href="{{ product.url }}" class="product-card">
      <img src="{{ product.featured_image | img_url: '400x400' }}" alt="{{ product.title }}" />
      <h3>{{ product.title }}</h3>
      <p>{{ product.price | money }}</p>
    </a>
  {% endfor %}
</div>

编写商品详情页

创建 templates/product.liquid：

<h1>{{ product.title }}</h1>
<p class="price">{{ product.price | money }}</p>
<div class="description">{{ product.description }}</div>

<form action="/cart/add" method="post">
  <input type="hidden" name="id" value="{{ product.variants[0].id }}" />
  <button type="submit">{{ 'products.add_to_cart' | t }}</button>
</form>

编写样式

创建 assets/theme.css：

:root {
  --color-primary: {{ settings.primary_color | default: '#5E6AD2' }};
  --color-text: #18181b;
  --color-bg: #ffffff;
}
body {
  font-family: -apple-system, sans-serif;
  color: var(--color-text);
  background: var(--color-bg);
  margin: 0;
}
.product-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
  gap: 16px;
  padding: 20px;
}
.product-card {
  text-decoration: none;
  color: inherit;
}

编写配置 Schema

创建 config/settings_schema.json：

[
  {
    "name": "颜色",
    "settings": [
      {
        "type": "color",
        "id": "primary_color",
        "label": "主色",
        "default": "#5E6AD2"
      }
    ]
  }
]

编写多语言文案

创建 locales/zh-cn.json：

{
  "products": {
    "add_to_cart": "加入购物车"
  }
}

安装并测试

将主题目录放入 themes/，启动 dev server，在 /admin/settings/themes 安装激活。

修改 theme.css 或 .liquid 文件后 HotReload 自动生效。

教程 4：对接 ERP 同步订单

目标：使用 REST API 与 Webhook 将 ShopFaaS 订单实时同步到外部 ERP 系统。

预计耗时：45 分钟

适合：有后端开发经验的开发者

创建 API Key

店长在「设置 → 应用 → API 密钥」创建 API Key，权限选择 order:view。
配置 ERP 端接收接口

在 ERP 侧创建一个接收订单数据的接口（如 POST https://erp.example.com/api/orders/sync）。

使用 Webhook 实时推送

开发一个轻量应用扩展，监听 order.created 与 order.paid 事件，将订单推送到 ERP：

// webhooks/order-created.ts
import type { WebhookHandler } from "@shopfaas/plugin-runtime";

const handler: WebhookHandler<"order.created"> = async (event, ctx) => {
  const order = await ctx.api.orders.get(event.payload.order_id);

  await fetch("https://erp.example.com/api/orders/sync", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-ERP-Token": process.env.ERP_TOKEN!,
    },
    body: JSON.stringify({
      source: "shopfaas",
      order_number: order.order_number,
      total: order.total,
      currency: order.currency,
      customer: order.customer,
      items: order.items,
      created_at: order.created_at,
    }),
  });
};

export default handler;

使用 REST API 补偿同步

对于 Webhook 投递失败的情况，用 REST API 定时补偿：

// 定时任务：每小时同步最近订单
async function syncRecentOrders() {
  const oneHourAgo = new Date(Date.now() - 3600 * 1000).toISOString();
  const response = await fetch(`https://your-store.com/api/orders?status=PAID&updatedAfter=${oneHourAgo}`, { headers: { "X-ShopFaaS-API-Key": process.env.SHOPFAAS_API_KEY! } });
  const { data } = await response.json();

  for (const order of data.items) {
    // 检查 ERP 是否已有此订单，若无则同步
    await syncToErp(order);
  }
}

处理库存回写

ERP 库存变更时通过 REST API 回写到 ShopFaaS：

async function updateShopfaasInventory(productId: string, quantity: number) {
  await fetch(`https://your-store.com/api/products/${productId}/inventory`, {
    method: "POST",
    headers: {
      "X-ShopFaaS-API-Key": process.env.SHOPFAAS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ quantity, reason: "ERP 库存同步" }),
  });
}

错误处理与重试
健壮性建议
- Webhook handler 实现幂等性（同一订单多次推送不重复创建）
- ERP 接口超时设置 10 秒，超时不阻塞 Webhook 响应
- 失败的同步记录到队列，定时重试（指数退避）
- 监控同步延迟与失败率

教程

教程 1：搭建第一个店铺

教程 2：开发第一个应用扩展

教程 3：创建第一个主题

教程 4：对接 ERP 同步订单

教程 1：搭建第一个店铺

教程 2：开发第一个应用扩展

教程 3：创建第一个主题

教程 4：对接 ERP 同步订单

相关文档

开始使用

开发者指南

API 参考

最佳实践