文档中心开发者技术手册MedusaJS 2.0 电商核心引擎深度集成

Medusa 2.0 商业引擎集成与工作流 (Workflows)

Medusa 2.0 是系统的电商核心大脑，驱动着购物车流转、全渠道库存调度、订单履约及多网关支付。

关于 Medusa 2.0 的重要升级说明

本套系统全面基于 Medusa v2 新生代架构构建，搭载了强大的 Workflows 编排系统，运行性能相较 v1 获得成倍提升。

1. Medusa v2 模块化架构与实时数据协同

Next.js 商城前端通过官方 JS SDK，借助安装部署期间生成的 Publishable API Key 与 Medusa 进行安全交互。

product-strapi.ts灵活管理复杂商品多规格属性、颜色色板、尺码矩阵及多货币梯度定价。

review-product.ts秒级购物车增删改查计算，支持一键叠加复合型优惠券与限时满减折扣。

wishlist-customer.ts收货地址自动校验、智能计算各国消费税率与承运人物流运费。

question-product.ts支付成功后即刻自动流转订单状态，并实时扣减预占的真实库存。

store-admin/src/links/review-product.ts

typescript

import { defineLink } from "@medusajs/framework/modules-sdk"
import ProductModule from "@medusajs/medusa/product"
import ProductReviewModule from "../modules/product-review"
 
export default defineLink(
  ProductModule.linkable.product,
  ProductReviewModule.linkable.productReview
)

2. 环境变量配置指南 (.env)

将前端商城与 Medusa 后端服务连通所需的基础环境变量：

.env 中与 Medusa 相关的连接配置

bash

npm run seed

初始化 Medusa JS Client 客户端

bash

npx medusa exec ./src/scripts/seed-30-products.ts

查询商品列表请求示例代码

bash

npx medusa exec ./src/scripts/sync-meilisearch.ts

将商品添加进购物车操作示例代码

bash

npx medusa exec ./src/scripts/delete-all-products.ts

3. 订单业务工作流 (Workflows) 与底层架构

src/lib/data/products.ts

typescript

import { sdk } from "@lib/config"
import { HttpTypes } from "@medusajs/types"
import { getAuthHeaders, getCacheOptions } from "./cookies"
import { getLocaleHeader } from "@lib/util/get-locale-header"
import { getRegion, retrieveRegion } from "./regions"
import { isNetworkFetchError, warnMedusaUnreachable } from "@lib/util/medusa-fetch"
 
export const listProducts = async ({
  pageParam = 1,
  queryParams,
  countryCode,
  regionId,
  disableAuth = false,
}: {
  pageParam?: number
  queryParams?: HttpTypes.FindParams & HttpTypes.StoreProductListParams
  countryCode?: string
  regionId?: string
  disableAuth?: boolean
}): Promise<{
  response: { products: HttpTypes.StoreProduct[]; count: number }
  nextPage: number | null
  queryParams?: HttpTypes.FindParams & HttpTypes.StoreProductListParams
}> => {
  if (!countryCode && !regionId) {
    throw new Error("Country code or region ID is required")
  }
 
  const limit = queryParams?.limit || 12
  const _pageParam = Math.max(pageParam, 1)
  const offset = _pageParam === 1 ? 0 : (_pageParam - 1) * limit
 
  let region: HttpTypes.StoreRegion | undefined | null
  if (countryCode) {
    region = await getRegion(countryCode, disableAuth)
  } else {
    region = await retrieveRegion(regionId!, disableAuth)
  }
 
  if (!region) {
    return { response: { products: [], count: 0 }, nextPage: null }
  }
 
  const headers = {
    ...(disableAuth ? {} : await getAuthHeaders()),
    ...(await getLocaleHeader(disableAuth)),
  } as Record<string, string>
 
  const next = {
    ...(disableAuth
      ? { tags: ["store-products"] }
      : await getCacheOptions("store-products")),
    revalidate: 3600,
  }
 
  try {
    return await sdk.client
      .fetch<{ products: HttpTypes.StoreProduct[]; count: number }>(
        `/store/products`,
        {
          method: "GET",
          query: {
            limit,
            offset,
            region_id: region?.id,
            fields:
              "*variants.calculated_price,+variants.inventory_quantity,*variants.images,*options,*options.values,*variants.options,+metadata,+tags",
            ...queryParams,
          },
          headers,
          next,
          cache: "force-cache",
        }
      )
      .then(({ products, count }) => {
        const nextPage = count > offset + limit ? pageParam + 1 : null
        return {
          response: { products, count },
          nextPage,
          queryParams,
        }
      })
  } catch (error) {
    if (isNetworkFetchError(error)) {
      warnMedusaUnreachable("listProducts")
      return {
        response: { products: [], count: 0 },
        nextPage: null,
        queryParams,
      }
    }
    throw error
  }
}

4. 商品全量缓存与实时价格调价策略

商品全量信息在 Next.js 前端使用形如 medusa-products 的标签高效缓存，当后端调价或改库存时自动失效重刷。

Medusa 商品缓存重新验证 (Revalidate) 范例

env

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM_ADDRESS=noreply@yourdomain.com
CONTACT_FORM_RECIPIENT=info@yourdomain.com
SENDPULSE_API_ID=your_sendpulse_id
SENDPULSE_API_SECRET=your_sendpulse_secret