使用 Blazity 构建您的 Next.js Shopify 店面

本指南将引导您为 Shopify 商务平台设置 Next.js 店面。我们将使用 Blazity 开发的开源 Enterprise Ecommerce 启动器，该启动器附带 CLI，可让您快速上手。

概述

下图概述了我们应用程序的架构。

应用程序堆栈由 4 个关键组件组成

• 数据源 — Shopify 管理员后台、个性化工具等。
• 搜索引擎 — Meilisearch
• 全栈应用 — Next.js 应用程序
• 第三方集成 — 分析、客户关系管理等。

在此架构中，Meilisearch 数据库聚合来自多个来源的数据，使其可供 Next.js 应用程序访问。

我们的最终应用程序将如下所示：实时预览 ✨

先决条件

本指南需要

• Node.js ≥ 20.x
• Yarn ≥ 4.x
• Meilisearch ≥ 1.8
• 一个 Shopify 商店

设置

此设置阶段为您提供了应用程序与 Meilisearch 和您的 Shopify 商店交互所需的凭据。

这些凭据与安装阶段所需的环境变量相匹配。为清楚起见，本指南将使用“✅”表情符号来标记每个此类变量。

创建 Shopify 商店

如果您还没有 Shopify 商店，请访问 Shopify 并创建一个新商店。Shopify 为每个商店关联一个唯一的 ID，称为 商店域名。

要查找您的 Shopify 商店域名，请前往 设置 > 域名。您的商店域名如下所示：your-domain.myshopify.com。

✅ Shopify 商店域名

安装 Shopify Headless

在 Shopify 应用商店中，找到 Headless 应用程序并安装。安装后，点击 创建店面。

接下来，我们将更新 API 访问。在 管理 API 访问 部分，点击 店面 API 旁的 管理。

编辑店面 API 权限以添加以下内容

• unauthenticated_read_product_inventory
• unauthenticated_read_customer_tags

保存权限后，您可以复制**私有访问令牌**。

✅ Shopify 应用店面 API 令牌

创建 Shopify 应用

现在，我们将为我们的商店创建一个 Shopify 应用。Shopify 应用允许您为您的商店构建自定义集成。此应用将使我们能够获取 API 密钥，以读取和管理 Shopify 商店中的数据。

创建 Shopify 应用的步骤：

• 导航到您商店的 Shopify 管理后台
• 打开商店的 设置 并导航到 应用和销售渠道 标签页
• 点击 开发应用
• 如果有提示，请按照步骤允许为您的商店开发自定义应用
• 创建一个应用并输入名称，例如“Next.js 应用”

创建应用后，导航到 API 凭据标签页以找到您的 Shopify 应用的 API 密钥（不是 API 密钥秘密！）

✅ Shopify 应用 API 密钥

配置 Shopify Admin API 密钥

Shopify 应用使用两组密钥

• 一个 **管理员 API 密钥** — 用于管理 Shopify 后台，例如编辑您的产品目录
• 一个 **店面 API 密钥** — 用于读取产品目录、创建购物车等

我们可以在 Shopify 应用的 配置 标签页中配置这些 API 密钥的访问范围。在此部分中，我们将启用 Admin API 密钥所需的范围。

要配置 Admin API 密钥的范围，请遵循以下步骤：

• 在 Admin API 集成 部分，点击 配置
• 启用以下范围：
  • write_product_listings
  • read_product_listings
  • read_products
  • write_products
• 在 Webhook 订阅 下，选择 2024-01 API 版本
• 保存 :)

定义了令牌 API 范围后，我们可以返回到 API 凭据 标签页并安装我们的应用。点击 安装应用 以生成您的 API 访问令牌。

安装 Shopify 应用后，您将获得您的 Admin API 访问令牌。出于安全原因，此令牌只会向您显示 一次 — **请务必保存它**。

✅ Shopify 应用 Admin API 令牌

创建您的 Meilisearch 数据库

Meilisearch 是一个开源搜索引擎，提供全文、向量和混合搜索功能。我们的 Shopify 产品数据将与 Meilisearch 同步，使前端应用能够为最终用户提供快速、相关的搜索结果。

如果您没有 Meilisearch Cloud 账户，请创建一个Meilisearch Cloud账户。如有必要，您可以先了解如何开始使用 Meilisearch Cloud。

首先，创建一个新的 项目，例如“Shopify 商店”。这将创建一个新的 Meilisearch 数据库，大约需要几秒钟完成。

然后，您可以导航到项目设置页面，找到您的 数据库 URL（您的主机）和 默认 Admin API 密钥。

✅ Meilisearch 主机 URL

✅ Meilisearch API 令牌

配置您的 Meilisearch

创建数据库后，我们将创建索引。您可以为它们选择任何名称，但您需要相应地配置您的环境变量。让我们创建两个索引：

• 我们的产品索引，例如 products
• 我们的产品类别索引，例如 categories

✅ Meilisearch 产品索引名称

✅ Meilisearch 类别索引名称

创建索引后，我们现在可以配置它们。Meilisearch 的默认设置适用于大多数情况。对于每个索引，我们只配置可过滤属性和可排序属性。

产品索引 — 可过滤属性

[
	"collections",
	"collections.handle",
	"collections.id",
	"flatOptions",
	"handle",
	"minPrice",
	"tags",
	"variants.availableForSale",
	"vendor",
	"hierarchicalCategories",
	"hierarchicalCategories.lvl0",
	"hierarchicalCategories.lvl1",
	"hierarchicalCategories.lvl2",
	"avgRating"
]

产品索引 — 可排序属性

[
	"minPrice",
	"updatedAtTimestamp",
	"avgRating"
]

类别索引 — 可过滤属性

[
	"handle",
	"id"
]

所有其他属性设置可以保留其默认值。

安装

掌握所有凭据后，我们准备启动安装向导。让我们使用 Blazity 的 commerce CLI 创建项目。

# with NPM
npm create commerce

# with Yarn
yarn create commerce

第一个提示将要求您选择要启用的服务。对于本指南，我们只启用默认值：Shopify 和 Meilisearch。

然后，CLI 将要求您提供一系列凭据。如果您遵循了“设置”部分，您应该已经拥有所有必要的凭据。提供所有凭据后，CLI 将在新的文件夹中搭建您的项目。

创建后，导航到您的项目目录。您的 apps/web/.env.local 应该如下所示

# apps/web/.env.local

SHOPIFY_STOREFRONT_ACCESS_TOKEN=shpat_a-very-long-token
SHOPIFY_ADMIN_ACCESS_TOKEN=shpat_another-very-long-token
SHOPIFY_STORE_DOMAIN=your-domain.myshopify.com
SHOPIFY_APP_API_SECRET_KEY=a-32-characters-long-api-key
SHOPIFY_HIERARCHICAL_NAV_HANDLE=hierarchical-categories
MEILISEARCH_PRODUCTS_INDEX=products
MEILISEARCH_CATEGORIES_INDEX=categories
MEILISEARCH_ADMIN_KEY=your-meilisearch-admin-api-key
MEILISEARCH_HOST=https://edge.meilisearch.com
LIVE_URL=https://your-domain.myshopify.com
FLAGS_SECRET=randomly-generated-secret
CRON_SECRET=another-randomly-generated-secret

同步 Meilisearch 和 Shopify

Blazity 提供了一个 CLI 用于同步 Shopify 和 Meilisearch 之间的数据。在本节中，我们将看到如何使用 commerce-cli 实现此目的。

要将您的 Shopify 数据与 Meilisearch 同步，请导航到您的项目文件夹并运行

npx commerce-cli@latest sync

此命令将从您的 Shopify 商店拉取所有必要数据，并将其同步到您的 Meilisearch 数据库中。

启动您的应用

初始化应用程序并同步 Shopify 和 Meilisearch 之间的数据后，您就可以启动应用程序了。

要在开发模式下启动您的应用程序，请运行

# with NPM
npm run dev

# with Yarn
yarn dev

就是这样！您可以在 http://localhost:3000 访问您的应用程序 🎉

您也可以在此处查看实时示例：https://commerce.blazity.com/

进一步探索

本指南并未涵盖 Blazity 模板中的所有可用功能。如需更高级的配置，您可以访问Blazity 文档，了解如何设置分层类别、实现高可伸缩重定向等。

此外，以下资源可帮助您将新的 Shopify 商店与 Meilisearch 和 Next.js 集成

• Meilisearch 文档
• Next.js 文档
• 将 Meilisearch Cloud 与 Vercel 集成

订阅我们的每月新闻通讯，了解 Meilisearch 的最新动态。要了解 Meilisearch 的未来并帮助塑造它，请查看我们的路线图并参与我们的产品讨论。

如有其他需求，请在 Discord 上加入我们的开发者社区。