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

本指南將引導您設定 Shopify 商務的 Next.js 店面。我們將使用由 Blazity 開發的開放原始碼 Enterprise Ecommerce starter，它附帶一個 CLI，可讓您快速入門。

概述

下圖概述了我們應用程式的架構。

應用程式堆疊由 4 個主要組件組成

• 資料來源 — Shopify 管理員、個人化工具等。
• 搜尋引擎 — Meilisearch
• 全端應用程式 — Next.js 應用程式
• 第三方整合 — 分析、CRM 等。

在此架構中，Meilisearch 資料庫會彙總來自多個來源的資料，以便 Next.js 應用程式可以存取這些資料。

我們最終的應用程式將如下所示：即時預覽✨

先決條件

本指南需要

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

設定

此設定階段會為您的應用程式提供必要的憑證，以便與 Meilisearch 和您的 Shopify 商店互動。

這些憑證對應於安裝階段所需的環境變數。為了清楚起見，本指南將使用「✅」表情符號表示每個變數。

建立 Shopify 商店

如果您還沒有商店，請前往 Shopify 並建立一個新商店。Shopify 會將一個稱為「商店網域」的唯一 ID 與每個商店建立關聯。

若要尋找您的 Shopify 商店網域，請前往設定 > 網域。您的商店網域看起來像這樣：your-domain.myshopify.com。

✅ Shopify 商店網域

安裝 Shopify 無頭應用程式

在 Shopify Marketplace 中，找到 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 管理員 API 金鑰

Shopify 應用程式使用一組兩個金鑰

• 一個管理員 API 金鑰 — 用於管理 Shopify 管理員，例如，編輯您的產品目錄
• 一個店面 API 金鑰 — 用於讀取產品目錄、建立購物車等。

我們可以在您的 Shopify 應用程式的組態索引標籤中設定這些 API 金鑰的存取範圍。在此區段中，我們將為我們的管理員 API 金鑰啟用必要的範圍。

若要設定管理員 API 金鑰的範圍，請依照下列步驟

• 在「管理員 API 整合」區段中，按一下「設定」
• 啟用以下範圍
  • write_product_listings
  • read_product_listings
  • read_products
  • write_products
• 在Webhook 訂閱下，選取 2024-01 API 版本
• 儲存：)

在定義了我們的權杖 API 範圍之後，我們可以返回到API 憑證索引標籤並安裝我們的應用程式。按一下安裝應用程式以產生您的 API 存取權杖。

安裝您的 Shopify 應用程式後，您將可以存取您的管理員 API 存取權杖。基於安全考量，此權杖只會向您揭露一次—請務必儲存它。

✅ Shopify 應用程式管理員 API 權杖

建立您的 Meilisearch 資料庫

Meilisearch 是一個開放原始碼搜尋引擎，可提供全文、向量和混合搜尋功能。我們的 Shopify 產品資料將會與 Meilisearch 同步，使前端應用程式能夠為終端使用者獲得快速、相關的搜尋結果。

如果您還沒有帳戶，請建立一個 Meilisearch Cloud 帳戶。如有必要，您可以先學習如何 開始使用 Meilisearch Cloud。

首先，建立一個新的專案，例如 Shopify 商店。這將建立一個新的 Meilisearch 資料庫，應該需要幾秒鐘才能完成。

然後，您可以瀏覽至您專案的「設定」頁面，以尋找您的資料庫 URL（您的主機）和預設管理員 API 金鑰。

✅ Meilisearch 主機 URL

✅ Meilisearch API 權杖

設定您的 Meilisearch

建立資料庫後，我們將建立索引。您可以為它們選擇任何名稱，但您必須相應地設定您的環境變數。讓我們建立兩個索引

• 一個用於我們產品的索引，例如 products
• 一個用於我們產品類別的索引，例如 categories

✅ Meilisearch 產品索引名稱

✅ Meilisearch 分類索引名稱

索引建立完成後，我們現在可以設定它們。Meilisearch 的預設值對於大多數設定來說都運作良好。對於每個索引，我們只會設定可篩選的屬性（filterable attributes）和可排序的屬性（sortable attributes）。

產品索引 — 可篩選的屬性

[
	"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

就是這樣！您可以在 https://127.0.0.1:3000 訪問您的應用程式 🎉

您也可以在這裡查看一個實時範例：https://commerce.blazity.com/

更進一步

本指南並未涵蓋 Blazity 範本中的所有可用功能。對於更進階的設定，您可以參考 Blazity 文件，了解如何設定階層式分類、實作高度可擴展的重定向等等。

此外，以下是一些資源可協助您將新的 Shopify 商店與 Meilisearch 和 Next.js 整合

• Meilisearch 文件
• Next.js 文件
• 將 Meilisearch Cloud 與 Vercel 整合

訂閱我們的每月電子報，隨時掌握 Meilisearch 的最新消息。要了解更多關於 Meilisearch 未來的資訊並參與塑造它，請查看我們的路線圖並參與我們的產品討論。

如有其他問題，請加入我們在 Discord 上的開發人員社群。