完整安装部署 MedusaJS：从核心服务到全栈电商系统

导读#

MedusaJS 是目前最流行的开源 Headless Commerce（无头电商） 框架，被誉为“开源界的 Shopify”。它采用解耦架构，由核心引擎（Core）、管理后台（Admin）和展示前台（Storefront）三个部分组成。本文将手把手带你从零开始，在本地环境搭建起这套完整的电商基础设施。

前置环境准备#

在开始之前，请确保你的开发环境满足以下要求：

Node.js: v18.16.0 或更高版本。
Git: 用于克隆仓库。
包管理器: npm 或 yarn。

第一阶段：安装 Medusa 核心引擎#

1. 安装 Medusa CLI#

Medusa CLI 是管理项目的核心工具，负责数据库迁移、用户创建等任务。

1
npm install @medusajs/medusa-cli --global

2. 初始化项目#

我们使用官方种子模板创建一个项目。--seed 参数会自动填充一些测试商品和基础配置。

1
medusa new my-medusa-store --seed
2
cd my-medusa-store

第二阶段：基础设施配置（PostgreSQL + Redis）#

Medusa 默认使用 SQLite 进行快速启动，但在生产环境或深度开发中，PostgreSQL（存储数据）和 Redis（处理事件任务）是必选项。

1. 数据库准备 (PostgreSQL)#

确保你的 PostgreSQL 服务已启动。登录控制台创建数据库：

1
CREATE DATABASE medusa_db;
2
CREATE USER medusa_admin WITH PASSWORD 'your_password';
3
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_admin;

2. 缓存与消息队列 (Redis)#

Medusa 利用 Redis 处理后台任务（如发送邮件、同步库存）。请确保本地 6379 端口有 Redis 服务在运行。

3. 修改环境变量#

在项目根目录打开 .env，更新以下配置。注意：务必手动添加两个 Secret，否则生产环境下无法启动。

1
DATABASE_URL=postgres://medusa_admin:your_password@localhost:5432/medusa_db
2
REDIS_URL=redis://localhost:6379
3

4
# 安全配置：随机字符串即可
5
JWT_SECRET=something_very_secret
6
COOKIE_SECRET=something_very_secret

4. 同步配置#

在 medusa-config.js 中启用 Redis：

1
const REDIS_URL = process.env.REDIS_URL || "redis://localhost:6379";
2
const DATABASE_URL = process.env.DATABASE_URL;
3

4
module.exports = {
5
  projectConfig: {
6
    redis_url: REDIS_URL,
7
    database_url: DATABASE_URL,
8
    database_type: "postgres",
9
    store_cors: process.env.STORE_CORS,
10
    admin_cors: process.env.ADMIN_CORS,
11
  },
12
};

第三阶段：部署管理后台 (Medusa Admin)#

Medusa 提供了一个直观的后台界面来管理订单、产品和客户。

1. 启动集成后台#

从 Medusa v1.8 开始，后台已作为插件集成在核心服务中。你只需要在 medusa-config.js 的 plugins 数组中添加：

1
const plugins = [
2
  // ... 其他插件
3
  {
4
    resolve: "@medusajs/admin",
5
    /** @type {import('@medusajs/admin').ConfigModule} */
6
    options: {
7
      // 默认路径为 /a
8
      serve: true,
9
    },
10
  },
11
];

2. 创建管理员账号#

启动核心服务前，先创建一个登录后台的账号：

1
medusa user -e admin@example.com -p mypassword

3. 运行服务#

1
medusa develop

现在，你可以访问 http://localhost:9000/a 进入后台登录界面。

第四阶段：连接前台展示 (Storefront)#

为了让用户购物，你需要一个前台。Medusa 官方提供 Next.js 模板。

1. 克隆模板#

1
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-storefront

2. 配置环境变量#

进入 my-storefront 目录，将 .env.template 重命名为 .env.local，并确保指向核心服务的端口：

1
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

3. 启动前台#

1
npm run dev

访问 http://localhost:8000，你就能看到一个完整的电商购物网站了！

常见问题排查#

现象	解决方法
数据库连接失败	检查 `DATABASE_URL` 格式，确保 PostgreSQL 允许该用户访问。
CORS 跨域错误	在 `medusa-config.js` 中检查 `admin_cors` 和 `store_cors` 是否配置正确。
Redis 报错	确认 Redis 已启动，若本地未安装可暂时在 `.env` 中注释掉 `REDIS_URL`（仅限开发）。

总结#

通过上述步骤，你已经搭建了一个功能完备的微服务电商系统。Medusa 的强大之处在于其 “乐高式”的扩展能力：你可以随意更换前台 UI，或是通过插件接入 Stripe 支付、Algolia 搜索等第三方服务。