# @ecomplus/storefront-framework 中文文档

规范地址：https://npmcn.com/package/%40ecomplus/storefront-framework/

版本：5\.20\.68
npm 元数据更新时间：2026-10-12T20:11:30.714Z
中文译文更新时间：2026-11-13T05:59:21.073Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ecomplus/storefront-framework
原文对照：https://npmcn.com/package/%40ecomplus/storefront-framework/?lang=original
项目主页：https://github.com/ecomplus/storefront/tree/master/@ecomplus/storefront-framework#readme
源码仓库：https://github.com/ecomplus/storefront

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：337 kB，29 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：34 个
- 首次发布：2019-04-26T16:02:31.645Z
- 最新版本发布：2026-10-12T20:11:30.481Z
- 近 30 天下载量：3848（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：325（近 12 个月 9 个）

## 中文简介

PWA和JAMstack电子商务模板框架,带有E-Com+API

## 安装

```sh
npm install @ecomplus/storefront-framework
```

也可以使用：`pnpm add @ecomplus/storefront-framework`、`yarn add @ecomplus/storefront-framework`、`bun add @ecomplus/storefront-framework`

## README

# 存储前置框架

[![npm version](https://img.shields.io/npm/v/@ecomplus/storefront-framework.svg)](https://www.npmjs.org/@ecomplus/storefront-framework) [![License MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[网络软件包](https://webpack.js.org/) 基于 开发和建设工具 [贾姆斯塔克](https://jamstack.org/) 打开 [巴布亚新几内亚](https://developers.google.com/web/progressive-web-apps/) 电子商务模板 [E-Com + APIs](https://developers.e-com.plus/docs/reference/)

[变化](https://github.com/ecomclub/storefront-framework/blob/master/CHANGELOG.md)

## 启动模板

`storefront-framework` 是联署材料工具 **创建新模板** 更快,有更好的发展经验, 但是如果你不想从头开始整个模板, 我们还提供 [存储前端](https://github.com/ecomclub/storefront), (中文(简体) ), 以本框架构建的 并也是开源:wink :

_存储前端_ 是一个完整的电子商务模板 少数的依附者, 您可能改变您需要自定义的内容 并设置自己的主题和脚本.

## 开始

首先, 将模块安装为 dev 依赖 :

```bash
npm i --save-dev @ecomplus/storefront-framework
```

> 注:当您可以安装和运行时 `storefront-pack` 在全球, 我们建议在本地安装.

### 图标

-   `storefront-pack serve`数字 : 在端口启动 Webpack 开发服务器 _9100个_ (http://localhost:9100);
-   `storefront-pack build`数字 : 汇编用于制作和上交电子商务网页的资产;

#### 可选论点

-   `--port=8080`数字 : 更改 Dev 服务器端口号, 您可以替换 _8080 (韩语)_ 以你们所要的盟誓;
-   `--verbose`数字 : Webpack汇编过程的详细产出;
-   `--analyze`数字 : 打开 [Webpack 软件包分析器](https://github.com/webpack-contrib/webpack-bundle-analyzer) dev 服务器;
-   `--sw`数字 : Dev 服务器上的强制设置清单和服务工作员;
-   `--prerender=index,app/index`数字 : 列出要预发的 URL( 默认为全部);
-   `--prerender-limit=50`数字 : 限制要预先提交的随机URL的数量;
-   `--no-bundler`数字 : 禁用 Webback 编译只运行视图渲染;

### 国家预防机制脚本

国家预防机制 `package.json` 脚本是运行的方便而有用的工具 本地安装的二进制不需考虑 关于他们的全道。 简单定义脚本:

```json
{
  "scripts": {
    "serve": "storefront-pack serve",
    "build": "storefront-pack build"
  }
}
```

并在您的终端/控制台运行以下功能:

```bash
npm run serve
```

生产大楼:

```bash
npm run build
```

## 内容管理系统

你应该用CMS来做店页, 我们建议 [将内容管理系统网化](https://www.netlifycms.org/) 和提供 启动器 [`config.yml`](https://github.com/ecomclub/storefront-framework/blob/master/template/public/admin/config.yml) 文档.

全体 **内容必须是JSON**,保存在 `content` 文件夹.

## 招标

我们用 [EJS (英语)](https://ejs.co/) 预览 以下模板数据:

```js
data = {
  _: {
    // Boolean development mode
    devMode,
    // Parsed object from `content/settings.json`
    settings,
    // Function to get CMS JSON content by filepath
    cms,
    // Function to get `content/dictionary/${lang}` object
    dictionary,
    // MarkdownIt instance to parse MD markup
    md,
    // Store ID number
    storeId,
    // Language code string
    lang,
    // Brand colors RGB
    primaryColor,
    secondaryColor,
    // Preloaded data from E-Com Plus APIs
    store,
    categories,
    grids,
    items,
    // Contextual route object
    route,
    // Async resolve current route and get context object
    resolveRoute,
    // Lodash utility library
    // https://lodash.com/docs/
    lodash,
    // Utility functions for e-commerce
    // https://developers.e-com.plus/ecomplus-utils/
    ecomUtils,
    // E-Com Plus APIs client
    // https://developers.e-com.plus/ecomplus-client/
    ecomClient,
    // Search engine constructor
    // https://developers.e-com.plus/search-engine/
    EcomSearch,
    // Detect local images dimensions
    // https://github.com/image-size/image-size
    tryImageSize,
    imageSize
  }
}
```

EJS 配置有支持 `asyc/await` 财务报告和审定财务报表 `includes`。 。 。 .

> 注意所有参数都在母体内 `_` (单位:千美元)_全球_, (中文(简体) ), 我们用它来方便通过原始模板参数 包括EJS在内.

### 实例

你可以把EJS的这些观点 编码到我们 [`storefront-template`](https://github.com/ecomclub/storefront-template) 复发.

### 正在装入 JSON 内容

您可以通过调用 CMS 来装入内容 `cms` 函数 文件名( 不含扩展名) 作为参数, 如:

```ejs
<% const page = _.cms('pages/about-us') %>
<%= page.title %>
```

### 解析下标的内容

你的一些CMS内容可能会被保存为减值, 在 EJS 视图上,您可以通过使用 `md.render` 函数, 例如:

```ejs
<%= _.md.render(pages.home.md_content) %>
```

### 处理弹壳和路线

模板参数将有一个 `route` 财产, 它会是一个对象 不同类型的视图:

-   储存资源(产品、类别、品牌、收藏):

```js
route = { path, resource, _id }
```

你应该用 `route._id` 获得各自身体 资源文档与 `ecomClient`· ;

-   CMS 文件夹收藏( 如: _博客_ 或者说 _页次_:

```js
route = { path, collection, slug }
```

你应该用 `route.slug` 获取已解析的 CMS 内容 与 `cms` 函数;

-   在其他情况下,例如: `index.ejs`数字 :

```js
route = { path }
```

你可以用这个 `route.path` 了解当前背景 (a) 包括环境司法服务部分;

#### 上下文对象

与 `resolveRoute` 函数可以获取上下文对象 有资源 `body` 或 CMS 收藏 `content`数字 :

```ejs
<%
const context = _.resolveRoute()
if (_.route.resource) {
  // store resource
  // context = { resource, body }
} else if (_.route.collection) {
  // cms folder collection
  // context = { collection, slug, content }
} else {
  // context = {}
}
%>
```

### 包含绝对路径

通过 _绝对路径_ (posix) 您可以导入 EJS 文件 直接从 `@ecomplus/storefront-template` (或其他配置为 `STOREFRONT_TEMPLATE` 环境) `template/pages`数字 :

```ejs
<%- await include('/@/views/home', { _ }) %>
```

## 项目结构

为配合这一框架, 您的模板项目 **必须** 具有以下文件结构:

### 基本目录树

```
├── content
└── template
    ├── assets
    ├── js
    ├── pages
    ├── public
    │   ├── admin
    │   └── img
    │       └── uploads
    └── scss
```

#### `/content`

Netlify CMS(或任何其他无头的CMS)的根目录 [收藏](https://www.netlifycms.org/docs/add-to-your-site/#collections) JSON满足. 您可以在此创建和/或编辑内容以预设 一些用于示例或默认的内容.

[`settings.json`](https://github.com/ecomclub/storefront-framework/blob/master/content/settings.json) 需要并且至少必须具备 属性预设为默认值.

#### `/template`

源模板文件. 所有JS,SCSS,图像和其他资产文件应放在这里.

#### `/template/assets`

预定义的模板资产( 如图像, 视频, 声音...) 应在内部导入 `js` 或者说 `scss` 文档.

#### `/template/js`

JS线人档案, [`index.js`](https://github.com/ecomclub/storefront-framework/blob/master/template/js/index.js) 需要, 其他文件和模块应从索引中导入.

其他联署材料 `/template/js` 目录 还将被视为额外的 [Webpack 输入点](https://webpack.js.org/configuration/entry-context/)。 。 。 .

#### `/template/public`

任何固定资产 `public` 文件夹将被简单地复制而不通过 Webpack . 你需要使用绝对路径来参考它们.

#### `/template/public/admin`

设置 [将内容管理系统网化](https://www.netlifycms.org/), (中文(简体) ), 如果您不打算使用引用的 CMS , 则可以选择 .

[`config.yml`](https://github.com/ecomclub/storefront-framework/blob/master/template/public/admin/config.yml) 应该是 [配置](https://www.netlifycms.org/docs/add-to-your-site/#configuration) 遵循您的模板选项和特性. 设置收藏( 文件) `content/settings.json`(中文(简体) ) 必须有至少预设的字段.

#### `/template/public/img`

在此放置默认的 favicon 和 app 图标 .

#### `/template/public/img/uploads`

将内容管理系统网化 [媒体](https://www.netlifycms.org/docs/add-to-your-site/#media-and-public-folders) 打开 `uploads` 文件夹,商家可以在此 上传自定义标志、旗帜、图标和其他资产 CMS仪表板.

#### `/template/scss`

[常设委员会](https://sass-lang.com/) 来编译 CSS 样式表, [`styles.scss`](https://github.com/ecomclub/storefront-framework/blob/master/template/scss/styles.scss) 需要其他文件和模块 应输入其中.

#### `/template/pages`

[EJS (英语)](https://ejs.co/) 标记以编译 HTML 页面.

需要的文件 :

```
├── index.ejs
├── #brands.ejs
├── #categories.ejs
├── #collections.ejs
└── #products.ejs
```

上述文件必须在 根数 `pages` 目录.

要完成存储前端模板, 您还应当创建其它 EJS 视图. 你想用多少页都可以, 您可以选择任何文件名.

您可能想要添加一个 `#cms` 内部文件夹 页面目录,此文件夹应包含 EJS 视图 [文件夹收藏](https://www.netlifycms.org/docs/collection-types/#folder-collections), (中文(简体) ), 女巫会产生多颗子弹.

例如, 对于文件夹上的博客文件夹收藏 `content/blog`, (中文(简体) ), 你应该有一个视图 `#cms/blog.ejs`,它将为每个生成 HTML 页面 由 CMS 保存 .

## 产出

在制作时,文件将创建于 `dist` 文件夹, `template/js/index.js` 将捆绑到 `dist/storefront.js` 财务报告和审定财务报表 `template/scss/styles.scss` 改为 `dist/storefront.css`。 。 。 .

附加切入点 `template/js/` 或者说 `template/scss/` root 将尊重原始文件名.

EJS开始 `template/pages/` 将解析为 `dist/[file].html` 或者说 `dist/[slug].html` 在储存资源或CMS的情况下 文件夹收藏.

## 与 Web 软件包合作

Webpack 配置最简单的方式是提供一个对象,由导出 `storefront.webpack.js` 在您的工程根上的文件.

对象将合并到最后 [配置](https://github.com/ecomclub/storefront-framework/blob/master/src/webpack.config.js) 使用 [网络软件包](https://github.com/survivejs/webpack-merge)。 。 。 .

### 默认 Webpack 化名

我们准备好了 `#template` 当 Webpack 解析别名为 `@ecomplus/storefront-template/template` (或如果配置为 `STOREFRONT_TEMPLATE` (原始内容存档于2018-10-21). env.

因此,你可以使用,例如:

```js
import '#template/js/'
```

```scss
@import '#template/scss/main'
```

## 用网络部署

作为JAMstack的应用程序 你的模板可能很容易和Netlife一起部署, 要做到您应该添加一个简单的 [网络化.toml](https://github.com/ecomclub/storefront-framework/blob/master/netlify.toml) 文件和 a [部署按钮](https://www.netlify.com/docs/deploy-button/) 与 **链接到您的 模板存储器** 财务报告和审定财务报表 `stack=cms` param(考虑到您正在使用Netlify CMS).

### 样本

```md
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?stack=cms&repository=https://github.com/ecomclub/storefront-framework)
```

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?stack=cms&repository=https://github.com/ecomclub/storefront-framework)

## 常见问题

### @ecomplus/storefront-framework 是什么？

PWA和JAMstack电子商务模板框架,带有E-Com\+API

### 如何安装 @ecomplus/storefront-framework？

在项目目录运行 npm install @ecomplus/storefront-framework，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 storefront-pack，可以用 npx storefront-pack 直接运行。

### @ecomplus/storefront-framework 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ecomplus\_\_storefront-framework 是否存在。

### @ecomplus/storefront-framework 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ecomplus/storefront-framework 可以商用吗？

@ecomplus/storefront-framework 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ecomplus/storefront-framework 的下载量有多少？

根据 npm 官方下载统计，@ecomplus/storefront-framework 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,848 次，日均约 128 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ecomplus/storefront-framework 还在维护吗？

最新版本 5\.20\.68 发布于 2026/10/13（1 个月前）；至今共发布 325 个版本，其中过去 12 个月发布了 9 个；首次发布于 2019/04/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。