Shopify 嵌入式应用 React Router

要解决什么问题

Shopify 嵌入式应用跑在商家 Admin 后台 iframe 里，左侧菜单、App Bridge 导航、OAuth 会话和 Admin API 调用都有一套固定约束。自己从零拼 OAuth、Session、Webhook HMAC 和 CSP，很容易在登录循环、401 Webhook 或令牌泄露上踩坑。

本技能面向 React Router v7（framework mode）+ TypeScript + Node.js 栈，以 @shopify/shopify-app-react-router v1.x 和 Admin API 2026-04 为主线，把「能进后台、能调 API、能收事件、能上线」拆成可对照实现的步骤。

技能如何组织实现路径

核心入口是服务端 shopifyApp(config)（通常集中在 app/shopify.server.ts），对外暴露：

• authenticate.admin(request)：嵌入式路由鉴权，返回 admin（GraphQL/REST 客户端）、session、billing、cors、redirect 等
• authenticate.webhook(request)：校验 X-Shopify-Hmac-SHA256，禁止在未校验前手动 request.json() 后直接处理
• unauthenticated.admin(shop)：后台任务、定时任务在无请求上下文时访问 Admin API
• React 侧 AppProvider：为后台路由注入 App Bridge（embedded、apiKey）

最小骨架通常是三处：shopify.server.ts、带 authenticate.admin 的 app/routes/app.tsx、独立的 app/routes/webhooks.tsx（不要嵌套在 admin layout 下）。业务数据优先走 GraphQL（admin.graphql，版本用 ApiVersion.April26）；REST 需用 session 的 access token 自行 fetch。文档还覆盖 Session 存储适配（Prisma/SQLite 及 PG、Redis 等）、订阅 billing、限流与 GraphQL errors 解析、部署所需环境变量，以及 2026-04 常用 Admin 端点索引（见 references）。

适用边界与注意点

• 适合：在 Admin 内嵌 UI、需要 OAuth/Session/Webhook/计费的应用开发。
• 不适合：改主题用 Liquid；无头前台用 Hydrogen/Storefront GraphQL；仅做数据查询可改用更轻量的 Admin API 客户端技能。
• 安全底线：SHOPIFY_API_SECRET 与 accessToken 仅服务端；浏览器只拿 apiKey；APP_UNINSTALLED 必须清理 session；生产 Session 需持久化（勿用内存存储多实例）。
• 运维：GraphQL 约 50 点/秒、REST 约 2 次/秒；429 读 Retry-After 退避；Webhook 处理应幂等并失败时返回非 200 以便 Shopify 重试。