# @commercetools-frontend/mc-html-template 中文文档

规范地址：https://npmcn.com/package/%40commercetools-frontend/mc-html-template/

版本：27\.17\.1
npm 元数据更新时间：2026-11-10T16:02:33.885Z
中文译文更新时间：2026-11-10T16:05:12.635Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40commercetools-frontend/mc-html-template
原文对照：https://npmcn.com/package/%40commercetools-frontend/mc-html-template/?lang=original
项目主页：https://docs.commercetools.com/merchant-center-customizations
源码仓库：https://github.com/commercetools/merchant-center-application-kit

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

- 包体积（解压后）：131 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1
- 运行依赖：7 个
- 首次发布：2018-08-14T19:13:16.303Z
- 最新版本发布：2026-11-10T16:02:33.332Z
- 近 30 天下载量：26168（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1738（近 12 个月 203 个）

## 中文简介

为 MC 应用程序制作索引的所有相关内容

## 安装

```sh
npm install @commercetools-frontend/mc-html-template
```

也可以使用：`pnpm add @commercetools-frontend/mc-html-template`、`yarn add @commercetools-frontend/mc-html-template`、`bun add @commercetools-frontend/mc-html-template`

## README

# @ commercialtools-frontend/mc-html- template

[![Latest release (latest dist-tag)](https://badgen.net/npm/v/@commercetools-frontend/mc-html-template)](https://www.npmjs.com/package/@commercetools-frontend/mc-html-template) [![Latest release (next dist-tag)](https://badgen.net/npm/v/@commercetools-frontend/mc-html-template/next)](https://www.npmjs.com/package/@commercetools-frontend/mc-html-template) [![Minified + GZipped size](https://badgen.net/bundlephobia/minzip/@commercetools-frontend/mc-html-template)](https://bundlephobia.com/result?p=@commercetools-frontend/mc-html-template) [![GitHub license](https://badgen.net/github/license/commercetools/merchant-center-application-kit)](https://github.com/commercetools/merchant-center-application-kit/blob/main/LICENSE)

此软件包包含 utils 和脚本 `index.html` 为商贸中心的定制.

## 安装

```bash
$ npm install --save @commercetools-frontend/mc-html-template
```

## API 密码

### `generateTemplate`

这种方法将返回模板 HTML 文档,同时提供注入的 CSS/JS 脚本.

> 注意到 HTML 文档仍将有 **占位符** (见 `replaceHtmlPlaceholders`(中文(简体) )

```ts
type TGenerateTemplateOptions = {
  cssImports?: string[];
  scriptImports?: string[];
};

function generateTemplate({
  cssImports = [],
  scriptImports = [],
}: TGenerateTemplateOptions);
```

### `replaceHtmlPlaceholders`

这种方法将取代 **占位符** 在 HTML 文档中根据应用程序配置定义.

这种方法应作为最后步骤,以便充分汇编 `index.html`。 。 。 .

目前,我们界定了以下占位符:

-   `__CDN_URL__`页:1 `cdnUrl` 应用程序配置中定义的值
-   `__MC_API_URL__`页:1 `mcApiUrl` 应用程序配置中定义的值
-   `__LOADING_SCREEN_CSS__`: (中文(简体) )_内部定义_用于加载动画的CSS,以防页面加载需要更长的时间
-   `__LOADING_SCREEN_JS__`: (中文(简体) )_内部定义_(JS为加载动画,以防页面需要更长时间加载)
-   `__APP_ENVIRONMENT__`: 在全球变量中提供的已消毒的应用程序配置环境 `window.app`
-   `__CSP__`: 生成 `Content-Security-Policy` 指令,定义为 HTML 元标记

```ts
type TReplaceHtmlPlaceholdersOptions = {
  env: ApplicationRuntimeConfig['env'];
  headers: Record<string, string | undefined>;
};

function replaceHtmlPlaceholders(
  indexHtmlContent: string,
  options: TReplaceHtmlPlaceholdersOptions
): string;
```

### `compileHtml`

这种方法将汇编模板HTML文档.

```ts
type TCompileHtmlResult = {
  env: ApplicationRuntimeConfig['env'];
  headers: Record<string, string | undefined>;
  indexHtmlContent: string;
};

async function compileHtml(
  indexHtmlTemplatePath: string
): Promise<TCompileHtmlResult>;
```

### `processHeaders`

这种方法将返回用于服务器响应的安全信头,服务于 `index.html`。 。 。 .

这个 `applicationConfig.env` 将被注入到 `window.app`。 。 。 . 这个 `applicationConfig.headers` 是用户提供的已处理的应用程序头.

返回值 `processHeaders` 函数包含以下可随时使用的 HTTP 头:

```json
{
  "Strict-Transport-Security": "max-age=31536000",
  "X-XSS-Protection": "1; mode=block",
  "X-Content-Type-Options": "nosniff",
  "X-Frame-Options": "SAMEORIGIN",
  "Content-Security-Policy": "...",
  "Feature-Policies": "..."
}
```

```ts
function processHeaders(
  applicationConfig: ApplicationRuntimeConfig
): Record<string, string | undefined>;
```

## 邦德勒入境点

包会暴露出特定捆绑者用来使用HTML模板的一些特殊切入点.

#### 网络软件包

如果你使用Webpack 和 `HtmlWebpackPlugin`你可以通过 `webpack` 将 Webpack 模板参数映射到我们通用的 `generateTemplate` 方法.

```js
new HtmlWebpackPlugin({
  template: require.resolve(
    '@commercetools-frontend/mc-html-template/webpack'
  ),
  // ...
}),
```

## 常见问题

### @commercetools-frontend/mc-html-template 是什么？

为 MC 应用程序制作索引的所有相关内容

### 如何安装 @commercetools-frontend/mc-html-template？

在项目目录运行 npm install @commercetools-frontend/mc-html-template，或使用 pnpm add / yarn add / bun add。

### @commercetools-frontend/mc-html-template 支持 TypeScript 吗？

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

### @commercetools-frontend/mc-html-template 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @commercetools-frontend/mc-html-template 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @commercetools-frontend/mc-html-template 可以商用吗？

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

### @commercetools-frontend/mc-html-template 的下载量有多少？

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

### @commercetools-frontend/mc-html-template 还在维护吗？

最新版本 27\.17\.1 发布于 2026/11/11（今天）；至今共发布 1738 个版本，其中过去 12 个月发布了 203 个；首次发布于 2018/08/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。