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

导读

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

前置环境准备

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

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

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

1. 安装 Medusa CLI

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

npm install @medusajs/medusa-cli --global

2. 初始化项目

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

medusa new my-medusa-store --seed
cd my-medusa-store

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

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

1. 数据库准备 (PostgreSQL)

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

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

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

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

3. 修改环境变量

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

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

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

4. 同步配置

在 medusa-config.js 中启用 Redis：

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

module.exports = {
  projectConfig: {
    redis_url: REDIS_URL,
    database_url: DATABASE_URL,
    database_type: "postgres",
    store_cors: process.env.STORE_CORS,
    admin_cors: process.env.ADMIN_CORS,
  },
};

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

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

1. 启动集成后台

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

const plugins = [
  // ... 其他插件
  {
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').ConfigModule} */
    options: {
      // 默认路径为 /a
      serve: true,
    },
  },
];

2. 创建管理员账号

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

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

3. 运行服务

medusa develop

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

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

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

1. 克隆模板

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

2. 配置环境变量

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

NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

3. 启动前台

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 搜索等第三方服务。