Medusa 开源电商框架指南：用 30+ 模块化组件快速搭建可定制的 Commerce 系统
【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa
Medusa 是一个开源的电商（commerce）平台，仓库以 TypeScript monorepo 组织，核心思路是把产品、订单、购物车、支付、库存、促销等常见电商能力拆成 30 多个可独立启用的模块，再由一个轻量框架层负责 HTTP、数据库和工作流编排。对新手来说，它的价值在于：你不需要从零理解"电商系统由哪些部分构成"，只需要挑出自己要用的模块，然后在其上写业务。
为什么多数电商项目卡壳的地方，它直接给成了模块
自建商店最常见的困境不是写商品列表页，而是后面那一串边界问题：购物车里价格变了怎么算、库存扣减和下单是否原子、退款走部分还是整单、多货币多区域的价格从哪取。这些问题在传统做法里散落在订单服务、库存服务和一堆 if/else 里，改一处就要回归测试一大片。
Medusa 的处理方式是把每个领域单独做成一个模块，模块之间通过 link-modules/ 做关系关联。粗略分四组：
- 交易主链路：product/、order/、cart/、inventory/
- 钱和规则：payment/、pricing/、promotion/、tax/、currency/
- 运营与履约：fulfillment/、stock-location/、region/、sales-channel/
- 平台底座：auth/、user/、rbac/、api-key/、search/、translation/、notification/
还有一类容易被忽略但很实用的横切模块：caching/、event-bus-local/、locking/ 这类基础设施模块，同样提供 inmemory 与 Redis/Postgres 两套实现，小规模本地跑和上生产用的是同一套代码路径，只是换一个 provider。
框架层怎么组织：framework、workflows、modules 三层关系
理解 Medusa 的目录，关键是分清"运行时、编排、业务"三层，它们分别对应不同的包：
- 运行时：packages/core/framework/ 提供 HTTP 服务、数据库接入（MikroORM）和依赖注入，packages/medusa/src/api/ 下的路由分为
admin、store、auth几个命名空间，管理端与客户端 API 天然隔离。 - 编排：packages/core/workflows-sdk/ 定义工作流原语，packages/core/core-flows/ 则内置了 800 多个现成流程——"加入购物车""下单""发起退款"这类操作都是可组合的工作流，支持失败回滚。
- 业务：
packages/modules/里的每个模块用统一的 SDK 开发（packages/core/modules-sdk/），对外暴露服务、订阅事件、声明自己拥有的数据模型。
这种分层的实际好处是：写自定义业务时，多数情况是组合已有 core-flows 而不是重写领域逻辑；只有当你的业务确实超出模块边界（比如分销商结算）时，才需要自己新增模块或写自定义工作流。
三步跑通本地环境
前置要求是 Node.js v20.19+ 或 v22.12+（仓库@medusajs/medusa包声明的 engines 字段即为此），数据库由脚手架默认配好，无需单独安装 PostgreSQL 也能先跑起来。
- 克隆仓库阅读源码（想先看实现的话）：
git clone https://gitcode.com/GitHub_Trending/me/medusa - 用官方脚手架创建自己的应用（注意：新建应用和浏览这个 monorepo 是两回事，日常开发不需要依赖整个仓库）：
npx create-medusa-app@latest my-medusa-store - 进入目录执行
npm run dev（底层是medusa develop）。服务跑在http://localhost:9000，管理后台同端口下的/app路径，安装脚本会自动打开后台引导你创建第一个管理员账号。
值得留意的是，medusa develop同时构建并运行管理后台（packages/admin/dashboard/ 是 Vite + React 应用），意味着开箱即用就有订单、产品、库存、客户管理界面，第一周不必为后台 UI 分心。
模块是接口，providers 目录是插拔件
每个模块定义能力契约，具体实现放在 providers/ 下，按"一个能力多个实现"的方式排布，这也是 Medusa 和很多电商系统最明显的差异——切换实现不改业务代码：
- 支付：
payment-stripe内置，其他网关可以按 provider 接口自行扩展 - 认证：
auth-emailpass、auth-github、auth-google、auth-oidc，支持邮箱密码与主流 OAuth 并存 - 文件存储：
file-local本地磁盘、file-s3对象存储 - 搜索：
search-postgres用 Postgres 做全文检索，无额外中间件 - 通知与分析：
notification-sendgrid、analytics-posthog等
选型上的取舍逻辑通常是：开发期用 local/inmemory 系（零配置），生产按成本与团队熟悉度选 Redis/S3/Postgres 系，切换只发生在配置层。如果功能超出内置集合，两条路：plugins/ 下的现成插件（目前有draft-order草稿订单和loyalty会员积分两个），或基于 modules-sdk 自己写模块并注册 API 路由——packages/cli/http-types-generator/ 可以根据 OpenAPI 定义生成前端类型，保证前后端契约一致。
部署侧官方文档在www/apps/book/下，覆盖 Docker、多环境、CI/CD 等场景；仓库里还有一层 www/apps/api-reference/ 由 OAS 生成，核对接口字段时比翻源码快。
下一步该先做什么
跑通本地环境后，建议的深入顺序是：先用内置后台走一遍"建商品 → 下单 → 退款"完整流程并观察数据库变化，建立对模块数据的直觉；再读一个 core-flow（比如下单流程）看工作流如何组合模块服务；最后才是决定要不要加自定义模块。另一个值得早想的问题是：你的业务里哪部分最不像标准电商——那部分通常就是未来自建模块的候选地，Medusa 的架构会替你守住其余部分的稳定性。
【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
