用途:当框架没有 Commerce Engine 一方封装时使用。已有封装:Next.js 用 @commercengine/storefront/nextjs,TanStack Start 用 /tanstack-start,Astro 用 /astro,SvelteKit 用 /sveltekit,均应改用对应封装;仅 Nuxt 等未支持框架使用本技能。
主要能力:@commercengine/ssr-utils 提供 CookieAdapter(把框架 Cookie API 归一到 get/set/delete)、ServerTokenStorage(基于 CookieAdapter 实现 TokenStorage)、createCookieAdapter 辅助函数(适用于 Cookie 存储已具备兼容 get/set/delete 的框架)。SDK 将公开读取与实时会话分离:PublicStorefrontSDK / storefront.public() 用于构建或预渲染读取(仅 API key,不做令牌引导、刷新或写 Cookie);SessionStorefrontSDK / storefront.session(...) 用于实时匿名或登录用户流程,可读写请求 Cookie、引导匿名认证并刷新令牌。
必要用法:安装 npm install @commercengine/storefront @commercengine/ssr-utils。构建 CookieAdapter(以 Nuxt/h3 的 getCookie、setCookie、deleteCookie 为例)后创建 ServerTokenStorage 并传入 prefix、maxAge、path、sameSite 等选项,再创建 SessionStorefrontSDK(需 storeId、apiKey、tokenStorage)。公开渲染读取使用 PublicStorefrontSDK,不经过 ServerTokenStorage。需要在实时请求开始时立即建立会话可用 await sdk.ensureAccessToken();普通会话调用(如 sdk.cart.getWishlist()、addToWishlist()、getUserCart()、customer.listAddresses())无需先调用,会话中间件自动处理。若存在 Hosted Checkout,应以 Storefront SDK 为会话所有者,通过 onTokensUpdated 在客户端同步令牌。
限制与注意:SSR 代码中禁用 BrowserTokenStorage,须用 ServerTokenStorage;构建或预渲染公共页面不得使用会话 SDK;不要在上述已有封装框架中直接使用 ssr-utils;客户端与服务端 Cookie 的 prefix、path、secure、sameSite 与编码需保持一致;避免在各功能代码中散落 ensureAccessToken(),如需即时引导应集中在一处请求引导辅助中。访问 https://llm-docs.commercengine.io 的请求须带 Accept: text/markdown 头或在路径后加 .md。前置条件为已完成 SDK 初始化(见 setup/)。其他使用细节及具体定价、平台支持等资料暂未提供。