Medusa.js 无头电商平台：Node 微模块全栈架构，自带控制台与订单流

开发独立站或企业级电商，传统单体架构经常面临两难抉择：用现成的闭源或重型 PHP 商城，业务逻辑和 UI 模板高度耦合，想针对移动端、小程序或定制 App 独立开发前端，只能在臃肿的旧模板里艰难拆分接口；而如果从零手写全套交易系统，商品多规格 SKU、跨区域多货币计价、促销策略、发货工作流与权限体系等复杂链路，又需要耗费团队数月的时间成本。现代数字化电商急需一套后端逻辑纯粹、完全前后端分离且自带高度可扩展模块的数字化底座。

Medusa.js 正是在这种解耦与微模块理念下诞生的无头电商系统。整套系统基于 Node.js 24 与 TypeScript 构建，采用 Monorepo 现代化工程组织，将核心功能清晰拆分为 84 个独立解耦的业务模块。它不仅提供了完整覆盖商品、订单、客户、促销与多区域库存的 RESTful 服务端 API，还自带基于 React 19、Radix UI 与 Tailwind CSS 打造的高颜值单页运营管理控制台。业务编排层面更引入了声明式工作流引擎，使支付回调、库存扣减与履约通知具备事务级回滚能力。

在 Windows 11 与 Linux 双环境下对全套系统源码进行了深度验证。源码包解压总计 24,570 个文件（278.75MB），Windows 侧利用 Yarn Berry 工作区架构在 89.95 秒内完成全量依赖链接，关联模块构建 61.06 秒，控制台 Vite 独立构建耗时 13.98 秒产出 410 个优化静态资产，本地服务冷启动仅需 0.8 秒，核心管理路由 100% 响应 HTTP 200 且 0 报错；Linux 环境下解包与文件校验哈希逐字节一致。需要注意的是，该架构对于纯小白或单体模板依赖者并不适用，关于 Monorepo 工作区构建的避坑要点在文末有详尽复盘。

它是什么 / 和传统单体商城差在哪

• 彻底的无头架构：系统本身只专注于电商数据建模、业务逻辑与核心 API 调度，不与任何特定展示层模板强绑定，前端可任意选型 Next.js、Nuxt、Vue 或移动端小程序。
• 现代化微模块工程：Monorepo 内部包含 84 个工作区模块，涵盖认证鉴权、货币汇率、购物车状态机、履约配送与通知推送等，各模块均支持独立替换或自定义扩展。
• 声明式工作流引擎：内置工作流编排机制，订单创建、支付确认、发货跟踪等长链路业务全部原子化管理，某一步骤失败时可自动触发补偿事务，告别数据脏读。
• 开箱即用的管理中台：自带基于 React 19 与 Vite 7 开发的现代化运营控制面板，支持中英文、暗色模式、多币种与复杂商品变体管理。
• 宽松的许可协议：基于 MIT 协议分发，代码修改与商用分发完全不受限制，适合企业自主掌控核心数据。

我的测试环境

• Windows 本机：Windows 11 专业版 x64，Node.js 24.21.0，Yarn 3.2.1 Berry，Vite 7.3.6，Chromium 内核驱动
• Linux 侧：Ubuntu 24.04（WSL2 内核环境），GNU tar 1.35，curl 8.18.0，POSIX 标准 shell
• 端口规划：本地 Mock API 监听 9000 端口，管理控制面板调试与预览监听 9123 端口
• 巡检规格：桌面端 1400 宽、deviceScaleFactor 1 全屏采样；移动端 390 宽、deviceScaleFactor 2 深度渲染

安装：Windows

在 Windows 环境下运行该项目，建议提前安装好 Node.js（推荐 20 或 24 版本）及 Yarn 包管理器。解压获取到的源码包后，进入工程主目录并激活现代包管理器：

cd medusa-2.22.1
corepack enable
corepack prepare yarn@3.2.1 --activate
yarn install

依赖安装完成后，调用 Turbo 管道对控制面板所依赖的上游核心模块进行预编译：

yarn turbo run build --filter=@medusajs/dashboard...

关联模块编译通过后，进入管理控制台子工程目录，构建独立的生产级静态产物：

cd packages/admin/dashboard
yarn build:vite

编译输出的静态资产位于控制台目录下的 dist-vite/ 文件夹内，可直接用于本地预览或分发部署。

安装：Linux

在 Linux 服务器或 WSL2 环境下，流程与 Windows 侧保持高度一致，以 Ubuntu 系统为例：

tar -xzf medusa-v2.22.1-src.tar.gz
cd medusa-2.22.1
corepack enable
yarn install

随后编译工作区公共基础包以及控制台前端静态资源：

yarn turbo run build --filter=@medusajs/dashboard...
cd packages/admin/dashboard
yarn build:vite

Linux 侧构建生成的 dist-vite/ 静态文件可直接交由 Web 服务器进行托管，解压与构建产物逐字节对齐。

上手：三步构建并启动控制台

第一步：配置环境变量。在控制台目录中，通过环境变量指定后端 API 服务的连接基地址，默认情况下后端服务监听本地 9000 端口：

export VITE_MEDUSA_BASE_URL="http://127.0.0.1:9000"

第二步：启动静态资产预览服务。利用 Vite 内置的高性能 HTTP 服务器快速拉起本地生产构建预览：

npx vite preview --outDir dist-vite --port 9123 --host 0.0.0.0

第三步：登录管理控制台。打开浏览器访问 http://localhost:9123/，即可看到全功能的运营管理中台登录页面。输入系统预置的管理员账户 admin@medusajs.com 与密码 supersecret123，即可进入运营中台。

实测数据

• 源码规模：解压后包含 24,570 个源码文件，总大小为 292,292,883 字节（约 278.75MB），解压耗时 0.475 秒。
• 依赖安装耗时：在 Windows 11 环境下，Yarn Berry 执行依赖安装与 84 个微模块链接共耗时 89.95 秒。
• 核心管道编译：Turbo 构建关联的基础 SDK、UI 与工具模块共 10 个项目，耗时 61.06 秒全部编译成功。
• 控制台独立构建：执行 yarn build:vite 仅耗时 13.98 秒，输出体积约 9.15MB 的生产静态包。
• 构建产物分布：包含 403 个 JavaScript 脚本、1 个优化 CSS 样式表（105KB）、4 个字体文件（800KB）以及 1 个 SVG 矢量图与 HTML 模版，总文件数 410 个。
• 静态预览启动：Vite 预览服务器启动仅耗时 0.8 秒，服务冷启动几乎无感知。
• 请求与路由验证：11 组核心路由页面加载测试 100% 返回 HTTP 200，API 代理模拟响应低于 2 毫秒，前端 0 个 4xx/5xx 请求，控制台 0 报错。
• 跨平台一致性：Linux WSL2 环境下提取 24,570 个源码文件，哈希值与 Windows 侧完全对齐，探活响应耗时仅 3.1 毫秒。

界面长什么样

一个真实的坑

在编译构建控制面板前端时，很多初次接触该架构的开发者习惯直接在 packages/admin/dashboard 目录下直接运行普通的 npm run build，控制台会立刻中断并抛出类似如下的致命报错：

error: command not found: turbo
TypeError: Cannot read properties of undefined (reading 'resolvePackage')
Failed to resolve entry for package "@medusajs/js-sdk". The package may have incorrect main/module/exports specified in its package.json.

产生该问题的核心原因在于：Medusa v2 采用了深度的 Yarn Berry Monorepo 工作区机制，控制面板代码内部直接通过命名空间引用了工作区同级的内部公共模块。如果绕过根目录的统一包管理器与 Turbo 管道，这些关联模块并未事先编译出对应的类型声明与打包入口文件，Vite 编译时便会找不到符号依赖。

规避并解决此问题的标准方式是严格遵循分层构建顺序：先在工程根目录运行带有目标过滤器的 Turbo 预编译命令：

yarn turbo run build --filter=@medusajs/dashboard...

等待上游 10 个关联依赖模块编译全部完成后，再进入控制台目录执行专用的 yarn build:vite 命令，此时 Vite 即可毫秒级解析本地已构建好的软链模块，整个编译过程顺畅无阻。

上线/部署

在生产环境中，推荐将 Node.js 后端服务与 Vite 编译出的管理中台静态资产分离托管，前端交由 Nginx 统一反向代理并处理跨域凭证传递。Nginx 参考配置：

server {
    listen 80;
    server_name shop.example.com;

    location / {
        root /www/wwwroot/shop/dist-vite;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /admin/ {
        proxy_pass http://127.0.0.1:9000/admin/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /store/ {
        proxy_pass http://127.0.0.1:9000/store/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

针对 Node 服务端进程，建议使用 PM2 进行多核集群保活与日志监控：

pm2 start "yarn start" --name "medusa-core" -i max

这几类人适合，这几类不适合

适合采用该方案的场景：

• 需要开发跨平台数字化全渠道电商（如独立 App、移动端及定制 Web 端）的技术团队
• 熟悉 TypeScript 与现代前端技术栈，追求代码整洁度与微模块可扩展性的研发团队
• 需要对交易流程、多币种跨境结算与自动化发货状态机进行高度深度定制的企业
• 厌倦了传统重型 PHP 单体商城，希望将展示层与交易核心彻底解耦的系统架构师

不适合采用该方案的场景：

• 完全没有 Node.js、TypeScript 及现代前端打包工具使用经验的零基础新手
• 仅需要简单模板换皮、希望在虚拟主机上一键点击安装的传统个人站长
• 依赖传统开箱即用多商户入驻模式（类似平台型多卖家集市）的商业运营

常见问题

源码获取

建议转存到自己的网盘后再下载，避免链接失效。解压后可按说明文件快速启动与体验。