# @amboras-dev/storefront-core 中文文档 规范地址：https://npmcn.com/package/%40amboras-dev/storefront-core/ 版本：2026\.11\.9 npm 元数据更新时间：2026-11-13T15:14:37.640Z 中文译文更新时间：2026-11-13T15:15:52.355Z 软件包许可：UNLICENSED 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40amboras-dev/storefront-core 原文对照：https://npmcn.com/package/%40amboras-dev/storefront-core/?lang=original 项目主页：https://github.com/Amboras/storefront-sdk#readme 源码仓库：https://github.com/Amboras/storefront-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.6 MB，572 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.10\.0 - 运行依赖：1 个 - peer 依赖：next \>=16\.3\.0，react \>=19\.0\.0，sonner \>=2\.0\.7，react-dom \>=19\.0\.0，posthog-js \>=1\.200\.0，lucide-react \>=1\.0\.1，react-hook-form \>=7\.72\.0，@medusajs/js-sdk \>=2\.13\.4，@stripe/stripe-js \>=8\.11\.0，@tanstack/react-query \>=5\.17\.19，@stripe/react-stripe-js \>=5\.6\.1 - 首次发布：2026-11-02T12:36:42.468Z - 最新版本发布：2026-11-13T15:14:37.332Z - 近 30 天下载量：7694（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：19（近 12 个月 19 个） ## 中文简介 每个安博拉斯商店前端的平台:推车,取出,支付,认证,订单,订阅,目录数据,分析,同意,插件插槽,边缘代理和下个配置. 商店只保留设计;它们导入了这个. 无害环境管理,反应19,下16个. ## 安装 ```sh npm install @amboras-dev/storefront-core ``` 也可以使用：`pnpm add @amboras-dev/storefront-core`、`yarn add @amboras-dev/storefront-core`、`bun add @amboras-dev/storefront-core` ## README # @amboras-dev/ storefront-core (英语) 每个安博拉斯商店前台的一半:推车、退货逻辑、付款、代理、订单, 订阅、目录数据、分析、同意、插件插槽、边缘代理和下一个 相会. 一个商店只保留它的设计。 这里的每件东西都曾被复制到 ~73k 商店在分叉时间重置,然后从那里漂出. 一个版本包是指作为版本起伏的固定船,分期推出,而不是文件 重写每个部署. **此发行( 2026.11.0) 仅会移动逻辑 .** 科雷自己的UI(`/ui`, shopify 式检查) 进入第三阶段。 在此之前,商店通过自己的支付方式(见 `paymentUi`) (中文(简体) ). ## 店里怎么用着的 ### 1\. 配置一次: `lib/amboras.ts` 下一条内线 `process.env.NEXT_PUBLIC_*` 只有应用源,所以商店读它们和手 改为核心: ```ts import { configureCore } from '@amboras-dev/storefront-core/config' configureCore({ medusaUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL, publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY, storeId: process.env.NEXT_PUBLIC_STORE_ID, analyticsEndpoint: process.env.NEXT_PUBLIC_ANALYTICS_ENDPOINT, analyticsIngestUrl: process.env.NEXT_PUBLIC_ANALYTICS_INGEST_URL, analyticsKey: process.env.NEXT_PUBLIC_ANALYTICS_KEY, googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY, }) ``` Core在呼叫时会读取相貌懒散,所以模块顺序并不重要. 在制作中,缺失的美杜莎URL抛出 `MissingMedusaUrlError` 在第一个配置读取. 只有开发和测试才回到 `http://localhost:9000`。 。 。 . ### 2\. Shims保留每一个导入路径 每个文件核心作为一行再导出保留在商店中,所以现有的设计文件(AI-respected) 包括) 继续编译: ```ts // hooks/use-cart.ts export * from '@amboras-dev/storefront-core/client/use-cart' ``` `core-manifest.json` 列出每一个shim路径及其目标。 管弦乐手构建 AI 锁列表 从它和它的版本地板检查 确保每个shim存在. | 存储路径 | 核心导入 | | --- | --- | | `hooks/.ts` | `@amboras-dev/storefront-core/client/` | | `lib/.ts` | `@amboras-dev/storefront-core/lib/` | | `types/index.ts` | `@amboras-dev/storefront-core/types` | | `components/ClientPluginSlot.tsx` | `@amboras-dev/storefront-core/shell/client-plugin-slot` | | `components/PluginSlot.tsx` | `createPluginSlot` 从 `@amboras-dev/storefront-core/server/plugin-slot` | | `proxy.ts` | `proxy` 从 `@amboras-dev/storefront-core/edge` | ### 3\. 登记和付款 核心从不进口商店产生的 `app/_generated/plugin-registry` 或它的取出组件. ```tsx // components/PluginSlot.tsx (server) import { PLUGIN_REGISTRY } from '@/app/_generated/plugin-registry' import { createPluginSlot } from '@amboras-dev/storefront-core/server/plugin-slot' export const PluginSlot = createPluginSlot(PLUGIN_REGISTRY) export default PluginSlot ``` ```tsx // app/providers.tsx (client) import { CoreProvider } from '@amboras-dev/storefront-core/client' import { PLUGIN_REGISTRY } from '@/app/_generated/plugin-registry' import { StripePaymentForm } from '@/components/checkout/stripe-payment-form' // … SavedMethodSelector, SaveMethodConsent, PayPalSmartButtons ; {children} ``` 付款插件添加适配器 `registerPaymentProvider(config)` 从 `@amboras-dev/storefront-core/lib/payment-providers/registry`。 。 。 . ### 压住钩子 在 shim 旁边的本地导出 `export *` 只改变商店的进口。 核心的钩子 直接导入对方,从而改变钩芯本身的调用,将其传递给 `CoreProvider`数字 : ```tsx // app/providers.tsx. Module scope: overrides are read once. const overrides: CoreHookOverrides = { useCart: (base) => { const cart = base() return { ...cart /* … */ } }, } ; {children} ``` 可超过 : `useCart`, (中文(简体) ), `useRegion`, (中文(简体) ), `useAuth`, (中文(简体) ), `useListingParams`, (中文(简体) ), `usePaymentProviders`, (中文(简体) ), `usePaymentMethodsConfig`, (中文(简体) ), `useStripeErrorCopy`, (中文(简体) ), `useExpressCheckout`。所有其他的钩子都叫 只能通过商店代码, 所以它的shim已经是覆盖. `/lib` 函数不能压倒一切。 一个 覆盖是钩: 呼叫 `base` 在每一个变形或没有. `overrides` 第一次读取 渲染:保持其稳定(模块范围),因为以后增加或去除一个会改变钩子顺序. ### 4\. 下个配置和尾风 ```js // next.config.mjs import { fileURLToPath } from 'node:url' import { dirname } from 'node:path' import { resolveAmborasImageHosts, withAmborasCore } from '@amboras-dev/storefront-core/next-config' const __dirname = dirname(fileURLToPath(import.meta.url)) const imageHosts = await resolveAmborasImageHosts() /** @type {import('next').NextConfig} */ const nextConfig = { /* store options */ } export default withAmborasCore(nextConfig, { root: __dirname, imageHosts }) ``` **保持这个形状.** 管弦乐器(e2b预览, `check_build`)和 Shopify 复制器补丁 `next.config.mjs` 以白银盟誓 `const nextConfig = {`这是 地点 `allowedDevOrigins` (审查)和 `distDir: process.env.NEXT_DIST_DIR` (单位:千美元)`check_build`是因为 被注入。 将商店的选项保存在该字面对象中, 只应用核心 在导出线上. `const nextConfig = withAmborasCore({...})` 匹配所有模式, 所以 预览和 `check_build` 悄悄地失去了他们的补丁. `withAmborasCore` 扩展对象,所以 注入的键存活下来. `test/core/next-config-patchers.test.ts` 管理管弦乐团和 克隆人的真实模式 与这个片段相对应 用顶级解析主机 `await`从来没有 导出一个同步函数. `withAmborasCore` 将核心添加到 `transpilePackages`针头 `turbopack.root`,并构建 `images.remotePatterns` 从确切的主机。 主机是平台数据,而不是代码. `resolveAmborasImageHosts()` 在配置负载时,从第一个答案源读取一次: 1. 平台: `GET /api/v1/public/storefront/image-hosts?store=`, (中文(简体) ), 与2s超时. `` 实值 `AMBORAS_PLATFORM_API_URL`,其他来源于美杜莎宿主 (单位:千美元)`api[-env].amboras.com` 变成 `core[-env].amboras.com`页:1 `https://core.amboras.com`· ; 2. `AMBORAS_IMAGE_HOSTS`: JSON 阵列或精确主机名的逗号列表; 3. 烤起的倒车 `AMBORAS_FALLBACK_IMAGE_HOSTS` (模板的13个主机). 确切的东道主是 `NEXT_PUBLIC_MEDUSA_BACKEND_URL` 总是添加,本地端的主机是 不在Vercel上时添加. 和模板的算法一样 `amboras:image-hosts-reader` 块。 无 `imageHosts`, (中文(简体) ), `withAmborasCore` 用途 `AMBORAS_IMAGE_HOSTS` 或倒置列表(它不调用网络). 包含任何主机名 `*` 抛出,不管它是 `**` 或者说 `*.cloudfront.net`,因为通配符 `/_next/image` 打开 代理服务器. **释放命令 :** 管弦乐团的影像主机端点必须先活在制作中,然后才能出现 生产店采用2026.11.2. 没有它,一个生产建筑 使用倒计时列表。 以1%计 产品图像生产样本,约4%在商家主机上显示清单没有 包括,这样他们就会失败 `/_next/image`。 。 。 . 添加 `@source "../node_modules/@amboras-dev/storefront-core";` 改为 `app/globals.css` (见 `presets/tailwind.md`) (中文(简体) ). ### 5\. 代理匹配者 下一个读 `config` 从 `proxy.ts` 静地,所以它不能来自一个包。 店里有个 文字副本 `proxyConfig` 从 `@amboras-dev/storefront-core/edge`数字 : ```ts export { proxy } from '@amboras-dev/storefront-core/edge' export const config = { matcher: [ /* copy of proxyConfig.matcher */ ], } ``` `amboras-check proxy-matcher` 当复制件与安装的核心匹配器不同时失败 . ### 6\. 特性开关:未知开关未关闭 `useStoreConfig()` (客户)和 `getStoreConfig()` (服务器)读作"美杜莎" `GET /store/config`每一个 特性旗为 `true`, (中文(简体) ), `false` 或者说 `null`,以及 `null` 意为未知. 一切不明时 在老美杜莎、503和网络出错上加载,在读取器失败的旗帜上加载 美杜莎就是个 `null` 我也一样。 门 UI 与 `isFeatureOff(feature)`美杜莎说 `false`。从未读取 `features.x` 作为布尔,因为 `null` 变幻无常,会隐藏一个特征 没有人关闭. `checkout_settings` 财务报告和审定财务报表 `brand` 为: `null` 当未知. `useCheckoutSettings` 然后掉头 `/store/checkout-settings`。 。 。 . ### 7\. 建造大门 ```bash npx amboras-check # plugin slots, store quirks, redirect boundaries, consent scroll, proxy matcher npx amboras-check slots # one gate ``` ## 入境点 | 条目 | 什麽 | `"use client"` | | --- | --- | --- | | `/client` | `CoreProvider` (登记、支付UI、钩子覆盖), `ClientPluginSlot`配置 | 对 | | `/client/` | 一个勾钩文件,与模板的导出相同 | 每个文件 | | `/server` | `createPluginSlot`, (中文(简体) ), `PluginSlot`, (中文(简体) ), `getPluginConfigs`, (中文(简体) ), `medusaFetch`, (中文(简体) ), `getStoreConfig`配置 | 没有 | | `/lib/` | 逻辑模块( 退出、 推车、 付款提供者、 分析、 同意...) | 每个文件 | | `/edge` | `proxy`, (中文(简体) ), `proxyConfig` | 没有 | | `/next-config` | `withAmborasCore`, (中文(简体) ), `resolveAmborasImageHosts` | 没有 | | `/config` | `configureCore`, (中文(简体) ), `getCoreConfig` | 没有 | | `/types`, (中文(简体) ), `/types/plugins` | 共享类型、槽类型 | 没有 | `dist/` 实值 `tsc` 输出, 文件: 每 `"use client"` 留在档案里. ## 版本数 卡尔维尔 `YYYY.M.N` (单位:千美元)`npm run version:next`) (中文(简体) ). 插件声明 `peerDependencies['@amboras-dev/storefront-core']: '>=2026.11.0'`。过期名称暂出 至少两个未成年人. `api/*.api.md` 是一个公共表面 `/client`, (中文(简体) ), `/server` 财务报告和审定财务报表 `/next-config`; CI 不更新报告而更改时失败 . `api/shim-exports.json` 列出后面的导出名称 `/client/*` 财务报告和审定财务报表 `/lib/*`; CI 删除或重命名时失败 . 见 [捐款额](https://npmcn.com/package/%40amboras-dev/storefront-core/CONTRIBUTING.md) 发展与发行. ## 常见问题 ### @amboras-dev/storefront-core 是什么？ 每个安博拉斯商店前端的平台:推车,取出,支付,认证,订单,订阅,目录数据,分析,同意,插件插槽,边缘代理和下个配置\. 商店只保留设计;它们导入了这个\. 无害环境管理,反应19,下16个\. ### 如何安装 @amboras-dev/storefront-core？ 在项目目录运行 npm install @amboras-dev/storefront-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=16\.3\.0）、react（\>=19\.0\.0）、sonner（\>=2\.0\.7）、react-dom（\>=19\.0\.0）、posthog-js（\>=1\.200\.0）、lucide-react（\>=1\.0\.1）、react-hook-form（\>=7\.72\.0）、@medusajs/js-sdk（\>=2\.13\.4）、@stripe/stripe-js（\>=8\.11\.0）、@tanstack/react-query（\>=5\.17\.19）、@stripe/react-stripe-js（\>=5\.6\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 amboras-check，可以用 npx amboras-check 直接运行。 ### @amboras-dev/storefront-core 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @amboras-dev/storefront-core 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @amboras-dev/storefront-core 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.10\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @amboras-dev/storefront-core 可以商用吗？ @amboras-dev/storefront-core 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。 ### @amboras-dev/storefront-core 的下载量有多少？ 根据 npm 官方下载统计，@amboras-dev/storefront-core 在 2026/10/07 – 2026/11/05 这 30 天内被下载 7,694 次，日均约 256 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @amboras-dev/storefront-core 还在维护吗？ 最新版本 2026\.11\.9 发布于 2026/11/13（今天）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。