spree

机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

Website · Next.js Storefront · Documentation · API · Roadmap · Discord

按你想要的方式构建商业。 Spree 是一个开源商业平台，提供完整的 REST API、TypeScript SDK、React 管理仪表盘以及可生产使用的 Next.js 商店前端。BSD 3-Clause 许可——保持对你的代码、数据和基础设施的完全所有权。

团队使用 Spree 构建多卖方市场以及B2B 和批发渠道，还可实现无头 DTC、跨境和全渠道销售——所有功能都基于同一组商业原语，并且可与您现有的 ERP、PIM 和支付系统配合使用。

使用案例

Spree 提供电商基础功能，因此同一个核心可以服务非常不同的业务。

Multi-vendor Marketplace

卖家入驻支持可配置的需求清单，订单在完成时按卖家拆分，具有灵活的佣金引擎、通过 Stripe Connect 管理的付款账本，以及专用的卖家面板。这些都在开源核心中实现。

B2B & Wholesale

价格表 支持批量阶梯，客户群体、公司 具有地址、联系人和免税信息，目录 用于按细分市场配置产品，并且商店仅向获批买家开放。

Headless & Omnichannel

通过一个后端运行网页商店、移动应用、销售点、B2B 面板和市场。通道 为每个界面提供自己的目录、定价、支付方式和订单归属。

Next.js 商店 就是这样一个界面——可以直接投入生产、开源，使用 Next.js 16、React 19 和 TypeScript 构建。可以分叉、定制并部署。尝试在线演示

Cross-border Commerce

市场按区域捆绑货币、语言、支付方式和运输，因此每个客户都能从单一平台看到本地化的店面。翻译用于产品内容、欧盟综合历史价格和关税均已内置。

Multi-tenant SaaS ^Enterprise

运行一个SaaS平台，每个租户都拥有自己的独立商店——目录、订单、客户、支付方式和品牌——员工可以管理多个租户。需要企业版。

入门

将以下命令复制并粘贴到您的终端，以在 5 分钟内本地设置 Spree：

npx create-spree-app@latest my-store

这会在单个项目中设置 Spree 后端、React 管理仪表板，以及可选的 Next.js 店面。店面使用 Next.js 16、React 19、Tailwind CSS 4 和 TypeScript 构建。

你需要安装 Node.js 24 并运行 Docker。更多信息请查阅 安装文档。

如果你喜欢所看到的内容，考虑给 Spree 在 GitHub 上点个⭐星。

感谢你支持 Spree 开源 ❤️

智能开发

使用 AI 编程代理构建？安装 Spree 代理技能——它们教授 Claude Code、Cursor、Copilot 以及其他 60 种工具的 Spree 约定、定制模式和升级流程：

npx skills add spree/agent-skills

然后连接 docs MCP 服务器，让你的代理和你一起构建。更多信息请参见 Agentic Development 文档。

Spree 命令行界面

@spree/cli 从终端管理你的 Spree 项目——启动堆栈、运行生成器和迁移、查看日志——并通过简单的 get / post / patch / delete 命令直接调用 Admin API 。这是检查和编写你的商店脚本的快速方式，并且适用于 AI 代理（本地开发中零配置凭证）。

spree dev                                                            # boot the project (web + worker + db)
spree generate api_resource Brand name:string description:rich_text  # Creates full API endpoints, models and database schema for a Brand resource
spree api get /orders -q status_eq=complete --limit 10               # query the Admin API
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'  # create resources

spree api endpoints 和 spree api schema 离线浏览完整的 API。请参阅 CLI 文档。

功能

此存储库中的所有内容均根据 BSD 3-Clause 许可证发布。

• REST API 与 TypeScript SDKs — 面向店铺、管理员和卖家的 REST API，具有可发布的密钥、作用域秘密密钥、速率限制以及 OpenAPI 3.0 规范。三个类型化客户端： @spree/sdk （店铺）、 @spree/admin-sdk （管理员）和 @spree/seller-sdk （卖家）。
• React 管理员仪表板 — 基于 TanStack Router 和 Query、shadcn/ui 及 Tailwind 构建的 Vite React SPA。通过 插件 扩展它——导航条目、路由、表格列和插槽小部件——无需分叉即可扩展。附带面向市场卖家的匹配 卖家面板。
• Next.js 店铺界面 — 使用 Next.js 16、React 19、Tailwind CSS 4 和 TypeScript 构建的开源店铺界面。提供完整购物体验、多区域 URL 路由、Stripe 支付（Apple Pay、Google Pay、Klarna、Affirm）、客户账户和内置 SEO。 试用演示
• Spree CLI — 可从终端管理项目（启动、生成、迁移、升级）并直接调用 Admin API 的工具，使用 spree api get/post/... — 本地开发零配置，为脚本和 AI 代理构建。
• 市场与支付 — 卖家入驻时提供可配置的要求检查表、每位卖家订单拆分、带 EU 佣金税收的 佣金引擎，以及通过 Stripe Connect 的支付账本。
• B2B 与批发 — 价格表 包含批量阶梯价格和协商费率，客户组 用于细分，公司 包含地点、联系人和验证的税收豁免，目录 用于按段提供商品组合。
• 支付 — 与提供商无关的支付会话，即使标签页关闭也能可靠完成。支持 Stripe、Adyen 和 PayPal。可使用 支付提供商 SDK 添加您自己的支付方式。
• 促销与礼品卡 — 基于规则的 促销引擎，支持百分比和固定折扣、免运费、买一送一优惠和优惠码，以及原生的 商店积分和礼品卡。
• 履行 — 发货、数字交付和店内自提，交付配置文件和区域、多地点 库存，以及 退货、换货和索赔。
• 税务与合规 — 包含或附加的税费，通过 Avalara 和 Stripe Tax 自动计算，跨境 关税与费用，以及用于 GDPR 主体请求和欧盟综合价格历史的 数据隐私 工具。
• 产品与目录 — 任意记录的 自定义字段、CSV 导入和导出、数字产品、产品标签、共享的 媒体库 以及批量操作。
• 供应商合同 — 直接接入现有系统而无需替换：ERP、PIM、仓储管理系统和承运商、数字资产管理、单点登录 和 付款。
• 安全与身份 — 为员工和客户提供 OpenID Connect 单点登录，适用于任意 JWT 发行者的 自定义身份验证适配器，每个店铺可配置的 基于角色的权限，以及 符合 PCI 标准 的支付架构，确保卡片数据永远不会接触您的服务器。
• MeiliSearch 集成 — 容错拼写的产品搜索和多维度过滤，或 使用您自己的搜索提供者。
• 集成与扩展性 — 事件总线、Webhooks、OpenTelemetry 仪表，以及原生集成（GA4、GTM、Klaviyo）。
• 自主开发 — 代理技能（ npx skills add spree/agent-skills ）教 AI 编码代理 Spree 的规范，一个 文档 MCP 服务器、支持 LLM 的文档（llms.txt，按页面 Markdown，离线 npm 包），以及在每个脚手架项目中生成的 AGENTS.md/CLAUDE.md。

部署

Spree 后端可以部署在任何地方——云端、本地或 VPS。我们提供官方的 Docker 镜像和 Dockerfile，因此您可以使用 AWS、Azure、GCP、Render、Railway、Fly.io、Heroku 或任何其他兼容 Docker 的主机。Next.js 店面可以部署到 Vercel、Netlify 或任何 Node.js 主机。有关更多详细信息，请参见 部署文档。

社区与贡献

Spree 是一个开源项目，我们欢迎各种形式的贡献——拉取请求、问题报告、功能创意。

• Follow our Contributing Guide
• 加入我们的 Discord 与其他社区成员交流
• 浏览 路线图 并打开 问题

Spree 企业版

Spree 由一个获得资助的团队构建和维护，团队支持该开源项目。除了开源核心，我们还为需要额外模块和 SLA 支持的组织提供付费的 企业版。

企业版增加了B2B 审批工作流，包括基于角色的审批链和 ERP 连接器、市场自动化，如 Shopify 和 WooCommerce 卖家同步以及高级报表、多租户 SaaS——从单次部署运行多个隔离的租户商店，包括超级管理员、租户配置和白标计费——审计日志和静态加密，以及SLA 支持，提供专属成功经理、长期支持版本（LTS）和全天候监控。

其他所有内容——API、SDK、仪表板、市场、B2B 和跨境功能——都在此代码库中。企业版建立在相同的 BSD 3-Clause 核心上，因此您的团队将完全拥有代码、数据和基础设施。零平台费用。零交易费用。

联系销售团队 获取企业版演示，或加入 Discord 与社区一起使用开源版。

许可

Spree Commerce 的核心代码位于 spree/spree 仓库中，已在自由、开源的 BSD-3-Clause 许可证下发布（LICENSE）。

如果您喜欢看到的内容，可以考虑为 Spree 点一个 GitHub ⭐

感谢您对 Spree 开源项目的支持 ❤️