开源电商平台 Medusa 新手入门指南

2025-06-07

开源电商平台 Medusa 新手入门指南

Medusa是面向 JavaScript 开发者的领先开源 Node.js 电商平台。它提供与 Shopify 类似的开箱即用核心功能，同时其基于开放抽象和无头架构的设计，使开发者能够随着业务需求的变化更轻松地进行定制和维护。

Medusa 已完成大部分繁重工作，让您能够在短时间内打造一个可投入生产的商店。Medusa 的抽象架构还允许开发人员轻松扩展和定制平台，以适应其用例。

本文将带您了解 Medusa 的架构，并为您提供 Medusa 服务器的总体概述，以便您更好地理解其工作原理。

Medusa 架构概述

Medusa 项目的三个主要组成部分

Medusa 项目的三个主要组成部分

Medusa 的完整架构由三个主要组件组成：无头 Node.js 电商服务器、管理面板和店面。模块化和无头架构使这三个组件完全独立，并且可以不受任何限制地部署到不同的环境中。

要进一步了解每个组件是什么：

  1. Medusa 服务器（无头）
    • 这是核心组件，也是您在线商店的大脑。它是一个 Node.js 电子商务服务器。作为无头服务器，它可以通过 REST API 访问。店面和管理面板都是与服务器交互的呈现层。
    • 您在管理仪表板中配置的所有内容或消费者在店面上执行的操作均由 Medusa 服务器处理。
  2. 管理仪表板
  3. 店面
    • 店面是消费者到达、搜索并购买商品的地方。亚马逊网站就是一个店面的例子。您可以拥有一个跨平台店面（例如 Web 应用程序），也可以拥有多个店面（例如 Web、iOS 和 Android 原生应用程序）。
    • Medusa 提供了两个入门店面，一个使用Next.js构建，另一个使用Gatsby构建。您还可以通过与REST API交互来构建自己的店面。

本文仅关注 Medusa 服务器，因为它是 Node.js 电子商务平台的核心。

开发环境

Medusa 主要依赖于 Node.js 的安装。您需要 14 或更高版本。

Medusa 还使用其他技术和工具，例如 PostgreSQL 和 Redis。

本文介绍了如何在 Medusa 服务器中以及何时使用这些组件。您可以参考本文档了解如何安装每个环境要求。

如何安装 Medusa 服务器？

要安装 Medusa 服务器，您需要使用 Medusa CLI 工具。您可以使用以下命令安装 Medusa CLI 工具：

npm install -g @medusajs/medusa-cli
Enter fullscreen mode Exit fullscreen mode

然后，使用以下命令安装 Medusa 服务器：

medusa new my-medusa-store --seed
Enter fullscreen mode Exit fullscreen mode

您的服务器现在位于该my-medusa-store文件夹中。该--seed选项会在项目根目录创建一个 SQLite 数据库。该 SQLite 数据库用于保存服务器的虚拟数据，例如示例产品、区域等。种子数据仅用于开发环境中的测试目的。

由于使用 SQLite 数据库在开发中，尤其是在生产中会带来很多限制，因此建议安装和设置 PostgreSQL 数据库。

由什么my-medusa-store制成？

如果您之前使用过NestJS或Angular，那么这个文件夹结构可能看起来很熟悉。导航到my-medusa-store，您可以看到下面的内容。

在 my-medusa-store 文件夹中

在 my-medusa-store 文件夹中

对于初学者来说，您要关注的四个主要目录和文件是data、、和dist。srcmedusa-config.js

  1. data--seed目录包含虚假数据，可以使用选项或命令来填充您的演示商店npm run seed。
  2. medusa-config.js文件是您定义项目配置的地方，例如数据库信息、服务 API 密钥、插件等。
  3. src文件夹包含自定义文件的实现，从自定义端点（在 中api）到全局服务（在 中services）以及事件监听器（在 中subscribers）。这三个子文件夹将在接下来的几节中讨论。
  4. dist仅在运行npm run build或后才会出现该目录medusa develop。该目录包含目录中原始的已编译文件src。运行服务器时将使用这些已编译的文件。

对于产品图像上传，您需要安装和集成文件服务插件，例如MinIO、Amazon S3或DigitalOcean Spaces。

medusa-config.js 文件中有什么？

默认情况下，服务器包含以下变量。

ADMIN_CORS 和 STORE_CORS

Medusa 中的组件是解耦的。因此，Node.js 电商无头服务器、管理面板和店面可以来自不同的来源（例如，不同的域名，或同一域名的不同端口）。这会导致跨域资源共享 (CORS) 问题，并阻止组件之间的通信。

使用 CORS 变量是解决此问题的一种方法。默认情况下，无头服务器在端口 上运行9000，管理仪表板在端口7000或上运行7001，而店面在端口 上运行8000。如果您决定更改前端的来源或将组件部署到不同的环境，则必须相应地调整 CORS 值。

# .env
# CORS when consuming Medusa from admin
ADMIN_CORS=http://localhost:7000

# CORS to avoid issues when consuming Medusa from a client
STORE_CORS=http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

数据库网址

这是 PostgreSQL 实例的连接字符串。

PostgreSQL 是一款成熟的开源关系数据库，已被世界各地的开发人员采用。凭借其卓越的性能、可靠性和严格的数据完整性，PostgreSQL 甚至可以在全球范围内支持您的在线商店。

关于连接字符串的构造，请参考PostgreSQL官方文档。

# .env
# Sample of typical PostgreSQL connection string format
# postgres://<DB_USER>:<PASSWORD>@<HOST>:<PORT_NUMBER>/<DB_NAME>
DATABASE_URL=postgres://adminuser:password123@localhost:5432/my-medusa-database
Enter fullscreen mode Exit fullscreen mode

REDIS_URL

这是 Redis 实例的连接字符串。

Redis 是一种高性能开源内存数据结构。在 Medusa 中，它被用作事件队列，因此所有与事件相关的功能都需要正确配置 Redis。本指南稍后将详细介绍 Medusa 如何使用 Redis。

对于连接字符串，请参阅本指南。

# .env
# Sample of typical Redis connection string format
# redis://<REDIS_USER>:<PASSWORD>@<HOST>:<PORT_NUMBER>/<INSTANCE_NAME>
REDIS_URL=redis://superuser:redispassword@localhost:6379/my-redis-instance
Enter fullscreen mode Exit fullscreen mode

插件

在许多电商解决方案中，扩展功能通常需要专门的团队和服务器资源。然而，Medusa 解决了这个问题，它允许您通过插件将新功能集成到核心服务器进程中，从而消除了额外的资源需求。

由于 Medusa 是一个 Node.js 电商平台，因此插件本质上就是一个 NPM 包。安装后，只需将插件（包）的名称放入变量中plugins即可。从现在开始，插件可以使用所有其他 Medusa 服务，甚至可以访问数据库。

const plugins = [
  `plugin-without-options`,
  {
    resolve: `plugin-with-options`,
    options: {
      api_key: YOUR_PLUGIN_API_KEY,
      ...
    },
  },
];
Enter fullscreen mode Exit fullscreen mode

如何运行 Medusa 服务器？

在 Medusa 服务器根目录下使用以下命令运行服务器：

medusa develop
Enter fullscreen mode Exit fullscreen mode

服务器将在 上运行localhost:9000。您可以查看API 参考，了解可用于与服务器交互的端点列表。

Medusa 中的自定义端点是什么？

假设你想允许业务合作伙伴访问你的库存，该怎么做？当然，受保护的 API 是最佳选择。

在 Medusa 服务器中，您可以在/src/api文件夹中实现自定义端点。由于 Express 是内部使用的，因此从某种意义上说，Medusa 实例可以充当通用的公共 Express 服务器。端点数量没有限制。您的端点可以组织到一个或多个文件中。

按照惯例，管理员端点以 为前缀admin，而店面端点以 为前缀store。

例如：

/** 
 * /src/api/index.js 
 */

import { Router } from "express"

export default () => {
  const router = Router()

  router.get("/admin/hello", (req, res) => {
    res.json({
      message: "Welcome to Your Store!",
    })
  })

  return router
}
Enter fullscreen mode Exit fullscreen mode

实现 API 需要一定的 Express 知识，本文不作讨论。如需深入了解 Medusa 中的端点，请参阅如何为Admin和Storefront添加端点的文档。

美杜莎的服务是什么？

现在您知道 Medusa 服务器可以创建自定义端点，让我们重新审视 B2B 示例：

您希望让业务合作伙伴访问您的库存。

如上所述，需要受保护的 API，以便只有您的合作伙伴才能访问私人库存，并且您知道 API 在哪里实现，但是“私人库存访问”功能位于哪里？

遵循SOLID 原则，其中 S 代表单一职责，中的文件/src/api是负责管理 HTTP 请求/响应并决定应调用哪部分代码的控制器。

另一方面，私有库存访问被视为一项服务。Medusa 中的服务位于 中/src/services。它们代表一个特定的实体及其相关的功能。

服务示例：

/** 
 * /src/services/privateInventoryAccess.js 
 */

import { BaseService } from "medusa-interfaces"

class PrivateInventoryAccessService extends BaseService {
  getUnreleasedProducts() {
    ...
  }
}

export default PrivateInventoryAccessService
Enter fullscreen mode Exit fullscreen mode

您可以在 Medusa 服务器上的任何位置访问服务。例如，要PrivateInventoryAccessService在端点中使用：

/** 
 * /src/api/index.js 
 */

// File name of service is "privateInventoryAccess.js", so its registration name
//  is a camel-cased version: "privateInventoryAccessService"
// The service is accessible via req.scope.resolve(serviceRegistrationName)
const privateInventoryAccessService = req.scope.resolve("privateInventoryAccessService")

res.json({
  unreleasedProducts: privateInventoryAccessService.getUnreleasedProducts(),
})
Enter fullscreen mode Exit fullscreen mode

有关服务创建的完整教程，您可以从官方 Medusa 文档开始。

Medusa 中的订阅者是什么？

Medusa 处理 Node.js 电商平台的一些特定但基本的操作，例如下单或重置用户密码。当某个操作发生时，会触发相应的事件（例如，下单会触发一个order.placed事件）。

订阅者负责监听这些事件并处理它们。在内部，事件依赖于Redis 事件队列。事件被推送到此队列，然后 Redis 将这些事件发送给正在监听它们的订阅者。

如果没有安装和配置 Redis，事件将无法发出，订阅器也无法工作。您可以从 Redis 的官方网站下载。

您可以使用订阅器实现高度可定制的工作流程。许多插件（例如SendGrid或Mailchimp）内部都使用订阅器，您可以将它们用作即插即用的工作流扩展。

您可以在 Medusa 的文档中查看完整的事件列表。

自定义订阅者位于/src/subscribers。以下是订阅者的示例：

/**
 * /src/subscribers/orderPlacementLogger.js
 */

class OrderPlacementLoggerSubscriber {
  constructor({ eventBusService }) {
    eventBusService.subscribe("order.placed", this.writeLog);
  }

  writeLog = async (data) => {
    console.log(...)
  };
}

export default OrderPlacementLoggerSubscriber;
Enter fullscreen mode Exit fullscreen mode

有关订阅者及其工作原理的完整教程，请查看Medusa 的文档。

后续步骤

本文应该能帮助您掌握 Medusa 服务器的基础知识。然而，Medusa 还能发挥更多功能。

以下是一些可供参考的额外资源：

不要忘记加入Medusa 的 Discord，如果您有任何疑问，团队会随时为您提供帮助。

文章来源：https://dev.to/medusajs/a-guide-for-beginners-into-medusa-the-open-source-ecommerce-platform-2m08
Devto 翻译
PREV
您是否为开源项目做出贡献？
NEXT
使用 Link 向 React Router 传递数据