企业官网建设流程全解析

Medusa开源电商框架：从0到1搭好你的第一套完整商城

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

Medusa是一个开源的电商平台框架：你不用从零写购物车、订单、支付这些核心逻辑，它能直接跑起来，业务差异部分由你自己定制。想象一下这个场景：你手上有个200个SKU的配饰品牌，老板要求两周内上线官网商城，还要能对接本地支付。如果选一套现成SaaS，定制自由度有限；自己从零写，两周内根本不可能。Medusa走的是中间路线——商品、订单、库存、支付这些"电商基建"全部提供好，你只需要在它的模块上加自己的业务。

一、项目定位速读

• 模块化商城底座：商品、订单、购物车、客户、履约、库存等核心能力以独立模块提供，开箱即用，见packages/modules/
• 自带管理后台：Vite + React 构建的 Admin Dashboard，装完就能管理商品、订单、库存，不需要另外搭后台
• 工作流引擎：下单、退款等多步骤操作用可回滚的 Workflow 编排，某一步失败可自动补偿
• 插件体系：官方提供会员积分（loyalty）、订单草稿（draft-order）等插件，位于packages/plugins/
• 前后端分离：后端是 Node.js 服务，前台可搭配官方 Next.js Starter Storefront，也可换成任意技术栈

二、架构怎么拆的

从使用者视角看，Medusa 分成三层，各层能力可以独立开关：

模块之间通过事件和 Link 协作：订单模块产生事件，库存、物流等模块各自监听处理，互不侵入。也就是说，你改订单逻辑时，不会被迫碰库存代码。

三、5分钟跑通本地环境

注意一个新手容易搞混的点：这个仓库是框架源码（monorepo），不是可直接运行的商城。启动应用要用官方 CLI 生成项目。

1. 准备环境

需要 Node.js v20.19.0+（LTS）、Git 和运行中的 PostgreSQL。

2. 生成应用

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

它会在 monorepo 里生成apps/backend（后端+Admin），可选项里还能带上 Next.js Starter Storefront（放到apps/storefront），并自动创建同名 PostgreSQL 数据库。

3. 看到第一个结果

安装成功后浏览器会自动打开 Admin 让你创建管理员账号。之后在 backend 目录执行npm run dev，后端跑在localhost:9000，Admin 在localhost:9000/app，前台在localhost:8000。

4. 动手改点东西

在 Admin 里创建第一个产品、下一个订单，验证核心链路。想加自定义功能（比如品牌模块），代码写在生成项目的src/modules/、src/api/下，改动热重启生效。

四、适合谁 / 不适合谁

适合：

• 有明确定制需求的 DTC 品牌、B2B 商城、分销平台，愿意投入开发换取自由度
• 已有 Node.js 技术栈、想统一前后端语言的前端团队
• 需要多币种、多区域差异化运营（packages/modules/region/、packages/modules/currency/都是现成的）

不适合：

• 只想"选个主题当天开卖"的卖家——SaaS 型平台更省时间
• 只需要展示型官网、没有真实交易流的场景，用它属于杀鸡用牛刀
• 团队完全没有 Node.js 背景且预算紧张的，学习成本会放大

五、新手容易踩的坑

现象：create-medusa-app中途报数据库连接错误。原因：本机 PostgreSQL 没启动，或同名库已存在。解法：先确认 PG 在运行；库名冲突时给项目换个名（库名规则是medusa-项目名）。

现象：Node 版本报错或 npm 安装异常缓慢。原因：要求 Node v20.19.0+ 或 v22.12.0+ 的 LTS 版本，且官方建议用 yarn/pnpm。解法：升级 Node，改用yarn dlx或pnpm dlx执行。

现象：找不到管理后台，一直在访问错误端口。原因：新版 Admin 跑在后端同端口localhost:9000/app，不是独立服务。解法：认准9000/app，前台才是 8000。

现象：直接 clone 这个仓库想运行，发现跑不起来。原因：这是框架源码 monorepo，应用要用 CLI 生成。解法：仓库用于阅读源码和模块参考（如packages/modules/product/），项目启动永远走create-medusa-app。

装好后去仓库packages/modules/目录挑一个模块读它的 service 和 model，是理解整套架构最快的路径。

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