Medusa 电商框架完整指南：模块化架构解析与最快上手路径

Medusa 电商框架完整指南：模块化架构解析与最快上手路径

【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa

Medusa 是一个开源的电商基础设施框架（commerce platform），官方口号是「数字商务的构建块」。它把商品、订单、购物车、支付、库存这些电商核心能力做成了可独立安装的模块（当前主包版本 2.19.0），让你不必从零实现这些逻辑，直接组装出一个符合自己业务的商业系统。

它和传统电商系统有什么不同

很多开发者的第一反应是：电商系统不是开箱即用吗？为什么还要一个框架？区别在于交付形态。传统电商 SaaS 给你一套固定的流程和界面，改不动；而 Medusa 给你的是一个 Node.js 后端 + 一个管理后台，业务规则、数据模型、API 都掌握在自己手里。

具体来说，Medusa 的定位是「后端电商引擎」：

• 它本身不包含前台店铺页面。安装时可选附带一个 Next.js 起点前台，或接入任何自己的前端。
• 它适合两类目标：搭 DTC/B2B 商店，以及搭更底层的系统，比如分销平台、POS、服务型业务——只要你需要商品、订单、支付这些基础原语就行。
• 核心模块全部开源，以 npm 包形式发布；仓库中另有企业版（EE）功能，主要在基于角色的访问控制（RBAC）领域，需要商业授权，仓库根目录的 ENTERPRISE-LICENSE.md 有明确标注。

一句话总结：你要的不是"一个现成的网店"，而是"一套能改的电商内核"，Medusa 就是干这个的。

管理后台内置订单、促销、价格表等模块，订单详情中可直接看到折扣与渠道信息

30 个模块加 15 个供应商：架构怎么拆的

整个仓库是一个 TypeScript monorepo（使用 Yarn workspaces），拆开看是四层东西：

1. 商业模块（packages/modules/）目前 30+ 个模块，每个都是独立包，有自己的数据模型和服务接口。常见的如 product（商品与变体）、order（订单）、cart（购物车）、payment（支付）、inventory（库存）、region（区域与税率）。模块之间通过 link 机制关联，而不是互相直接依赖，这是它可扩展性的来源。

2. 供应商实现（packages/modules/providers/）15+ 个，负责"对接外部世界"：payment-stripe 接 Stripe 收款，auth-emailpass、auth-oidc 管登录，file-local 和 file-s3 管文件存储，fulfillment-manual 处理手动发货。想接入别的支付网关或物流服务，就照着这些 provider 写一个新的。

3. 框架与编排（packages/core/）framework 是运行时（HTTP、数据库、依赖注入）；workflows-sdk 提供工作流编排，把多步业务操作（比如"创建订单 + 扣库存 + 发起支付"）组合成可重试、可补偿的流程；core-flows 里则预置了大量开箱即用的业务工作流。

4. 管理后台（packages/admin/dashboard）基于 React + Vite 的 admin 界面，模块装进来后对应的管理页面会自动出现，也可以在 admin-bundler 机制下往里面加自定义页面。

后台侧边栏按模块组织：Orders、Products、Inventory、Customers，以及可安装的 Extensions

从克隆到运行的最短路径

如果你只是要读源码：

git clone https://gitcode.com/GitHub_Trending/me/medusa

如果你要起一个自己的电商应用，不要从源码跑，用脚手架命令一条命令生成项目（要求 Node.js v20.19.0+ 或 v22.12.0+，本地装好 PostgreSQL）：

yarn dlx create-medusa-app@latest my-medusa-store

脚手架会在apps/backend里装好后端和管理后台，回答提问时可选装 Next.js 起点前台（装到apps/storefront）。装完后端跑在http://localhost:9000，管理后台在http://localhost:9000/app，前台在http://localhost:8000。之后日常开发进后端目录：

npm run dev

修改src下代码会自动重启，管理后台的自定义页面支持热更新。CLI 源码在 packages/cli/create-medusa-app，想看它替你做了哪些事可以翻一翻。

部署模型示意：本地/仓库变更推入预览（PREVIEW）环境验证，通过后再进入生产（PRODUCTION）环境

哪些团队适合用它

按"改动深度"分三档，对号入座：

• 快速上线型中小商家：用默认模块组合 + Stripe 收款 + 手动发货 provider，两周左右可以跑通"上架商品 → 下单 → 收款 → 发货"的完整链路。适合有明确品类、流程不复杂的品牌店。
• 多市场运营团队：currency 处理多币种，region 和 tax 处理区域差异化定价与税则，sales-channel 把线上线下渠道整合进同一套商品和订单体系，适合做多地区、多渠道的零售业务。
• 平台型/二开团队：要搭分销平台、POS、或者在自有系统里嵌一套订单中台的，用 link-modules 把模块关联进自己的数据模型，或参照 modules-sdk 开发自定义模块。官方仓库里的 draft-order 和 loyalty 插件则是"如何给后台加自定义功能"的现成范本。

常见问题与文档入口

Q：Medusa 是免费的吗？核心模块和框架遵循 MIT 许可，完全免费；RBAC 相关的企业版功能需要商业授权，边界在 ENTERPRISE-LICENSE.md 里写得很清楚。

Q：它强制我用 Next.js 吗？不。后台是 Node.js 服务，前台可以任意技术栈实现，只要能调它的 Store API 就行；Next.js 起点只是官方提供的便利选项。

Q：数据库用 PostgreSQL 吗？默认 PostgreSQL，数据访问基于 Mikro ORM（依赖在 packages/deps 统一管理），模块的模型定义在各模块src/models下，改模型后用模块自带的migration:create脚本生成迁移，不要手写迁移文件。

Q：业务逻辑写在哪里？单步操作走模块服务，多步流程用 workflow 编排。想抄作业的话，packages/core/core-flows/src/ 下有 800 多个文件，按领域分目录，是密度很高的参考实现。

Q：API 长什么样？路由定义集中在 packages/medusa/src/api/，按 Store（对前台）和 Admin（对后台）两组组织；完整的 API 参考文档在 www/apps/api-reference/。

Q：遇到问题找谁？仓库内 CONTRIBUTING.md 说明如何提 issue 和贡献代码；官方文档站点源码在 www/apps/book/，入门、安装、故障排查章节都在这套 MDX 里。

选 Medusa 的理由说到底只有一条：电商的核心逻辑它是现成的，而你又不想被任何一套现成逻辑锁死。模块装得上也拆得掉，这在整个开源电商领域里并不多见。

【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa