# @ampproject/toolbox-optimizer 中文文档

规范地址：https://npmcn.com/package/%40ampproject/toolbox-optimizer/

版本：2\.10\.1
npm 元数据更新时间：2024-06-14T00:37:03.651Z
中文译文更新时间：2026-11-06T01:25:45.181Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40ampproject/toolbox-optimizer
原文对照：https://npmcn.com/package/%40ampproject/toolbox-optimizer/?lang=original
项目主页：https://github.com/ampproject/amp-toolbox/tree/main/packages/optimizer
源码仓库：https://github.com/ampproject/amp-toolbox

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

- 包体积（解压后）：251 kB，50 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：17 个
- 首次发布：2019-06-10T18:20:59.177Z
- 最新版本发布：2024-06-14T00:37:03.180Z
- 近 30 天下载量：178903（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 0 个）

## 中文简介

AMPs的服务器端渲染.

## 安装

```sh
npm install @ampproject/toolbox-optimizer
```

也可以使用：`pnpm add @ampproject/toolbox-optimizer`、`yarn add @ampproject/toolbox-optimizer`、`bun add @ampproject/toolbox-optimizer`

## README

# AMP 优化器

[![npm version](https://badge.fury.io/js/%40ampproject%2Ftoolbox-optimizer.svg)](https://badge.fury.io/js/%40ampproject%2Ftoolbox-optimizer)

AMP Optimizer是简化创建AMP页面并改进AMP渲染性能的工具. AMP 优化工具 [AMP 业绩最佳做法](https://amp.dev/documentation/guides-and-tutorials/optimize-and-measure/optimize_amp?format=websites) 并支持 [AMP 服务器侧接](https://amp.dev/documentation/guides-and-tutorials/optimize-and-measure/server-side-rendering?format=websites)。默认情况下,它将进行以下优化:

-   [服务器端渲染 AMP 版式](https://amp.dev/documentation/guides-and-tutorials/optimize-and-measure/server-side-rendering/)。 。 。 .
-   **自动导入所有缺失的 AMP 组件脚本**。 。 。 .
-   **自动添加任何缺失的强制 AMP 标记**。 。 。 .
-   自动检测并预装出从amp-img,amp-iframe,amp-video,或amp-video-iframe得到的英雄图像.
-   删除 AMP 锅炉板( 如有可能) .
-   删除不需要的空白 .
-   将 CSS 键框动画取出并移动到页面底部 .
-   优化 AMP 框架和自定义字体加载
-   为内嵌生成 CSP [`amp-script`](https://amp.dev/documentation/components/amp-script/) 代码.

性能优化可以将页面渲染时间提高至50%. 你可以读到更多关于 潜在的业绩收益 [博客文章](https://blog.amp.dev/2018/10/08/how-to-make-amp-even-faster/)试试看,看看 [在线操场](https://toolbox-optimizer.glitch.me/)。 。 。 .

**很高兴知道:**

-   AMP优化器将产生有效的AMP.
-   AMP 优化器可以与 [AMP 软件包](https://github.com/ampproject/amppackager) 创建 SXG.

## 使用量

### API 密码

通过 :

```
npm install @ampproject/toolbox-optimizer
```

最小使用量 :

```js
const AmpOptimizer = require('@ampproject/toolbox-optimizer');

const ampOptimizer = AmpOptimizer.create();

const originalHtml = `
<!doctype html>
<html ⚡>
  ...
</html>`;

ampOptimizer.transformHtml(originalHtml).then((optimizedHtml) => {
  console.log(optimizedHtml);
});
```

您可以找到一个样本执行 [这里](https://npmcn.com/packages/optimizer/demo/simple)如果使用快递服务您的网站,您可以使用 [AMP 优化中端软件](https://npmcn.com/packages/optimizer-express)。 。 。 .

### 国 际

AMP 优化器可以通过 [AMP 工具箱 CLI](https://npmcn.com/packages/cli/README.md)数字 :

```shell
npm install @ampproject/toolbox-cli -g
amp optimize myFile.html
```

或未安装便通过 `npx`数字 :

```shell
npx @ampproject/toolbox-cli optimize myFile.html
```

### 选项

当创建新的 AMP 优化实例时, 选项会被传递 :

```js
const ampOptimizer = AmpOptimizer.create({
  verbose: true
});
...
```

可用的选项有:

-   [自定义标签](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-autoaddmandatorytags)
-   [自动扩展导入](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-autoextensionimport)
-   [esm Modules 启用](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-esmmodulesenabled)
-   [扩展长度](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-extensionversions)
-   [获取](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-fetch)
-   [格式](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-format)
-   [图像BasePath](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-imagebasePath)
-   [图像优化器](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-imageoptimizer)
-   [这是](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-lts)
-   [减值](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-markdown)
-   [缩小](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-minify)
-   [优化AmpBind](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-optimizeampbind)
-   [优化英雄形象](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-optimizeheroimages)
-   [预装英雄图像](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-preloadheroimage)
-   [动词](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-verbose)

#### `autoAddMandatoryTags`

自动注入 AMP 所需的任何缺失标记 .

-   名称 : `autoAddMandatoryTags`
-   有效选项 : `[true|false]`
-   默认 : `true`
-   用于: [添加强制标签](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/AddMandatoryTags.js)

#### `autoExtensionImport`

自动导入任何缺失的 AMP 扩展( 如 amp- carousel) .

-   名称 : `autoExtensionImport`
-   有效选项 : `[true|false]`
-   默认 : `true`
-   用于: [自动扩展导入](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/AutoExtensionImporter.js)

#### `esmModulesEnabled`

启用较小的AMP运行时间和组件的无害环境管理模块版本:

```
<script async nomodule src="https://cdn.ampproject.org/v0.js"></script>
<script async src="https://cdn.ampproject.org/v0.mjs" type="module" crossorigin="anonymous"></script>
```

**警告: 这与AMP包机不相容,除非使用包含 [这一承诺](https://github.com/ampproject/amppackager/commit/92387ecf97e420eec10b378282383c59f95ab45f)。 。 。 .**

-   名称 : `esmModulesEnabled`
-   有效选项 : `[true|false]`
-   默认 : `true`
-   用于: [重写 AmpUrls](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/RewriteAmpUrls.js)

#### `extensionVersions`

指定用于自动导入扩展的版本编号。 如果未定义, 默认为最新 .

示例

```js
const ampOptimizer = AmpOptimizer.create({
  extensionVersions: {
    'amp-twitter': '0.1',
  },
});
```

-   名称 : `extensionVersions`
-   有效选项 : `OBJECT`
-   默认 : `{}`
-   用于: [自动扩展导入](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/AutoExtensionImporter.js)

#### `format`

指定输入文件的 AMP 格式。 默认为 `AMP`。 。 。 .

-   名称 : `format`
-   有效选项 : `[AMP|AMP4EMAIL|AMP4ADS]`
-   默认 : `AMP`
-   用于: [自动扩展导入](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/AutoExtensionImporter.js), (中文(简体) ), [添加强制标签](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/AddMandatoryTags.js)

#### `imageBasePath`

指定用于在构建时解析图像的基础路径, 这可以是文件系统路径或 URL 前缀 。 您也可以通过一个函数 `(imgSrc, params) => '../img/' + imgSrc` 用于动态计算图像路径.

-   名称 : `imageBasePath`
-   有效选项 : `STRING|FUNCTION`
-   默认: 未定义
-   用于: [标记](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/Markdown.js)

#### `imageOptimizer`

启用自动图像 `srcset` 通过提供计算函数生成 `srcset` 给定图像的 URL `src`。该函数应返回指向版本的 URL `src` 带有给定的图像 `width`。如果没有图像,它应该返回一个差值.

示例

```js
const ampOptimizer = AmpOptimizer.create({
  imageOptimizer: (src, width) => `${src}?width=${width}`,
});
```

-   名称 : `imageOptimizer`
-   有效选项 : `FUNCTION`
-   默认: 未定义
-   用于: [优化图像](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/OptimizeImages.js)

#### `lts`

使用 [长期稳定的 URL](https://github.com/ampproject/amphtml/blob/main/contributing/lts-release.md) 用于下载 AMP 运行时间和组件.

-   名称 : `lts`
-   有效选项 : `[true|false]`
-   默认 : `false`
-   用于: [重写 AmpUrls](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/RewriteAmpUrls.js)

#### `markdown`

这个变压器增加了外出标记下的支持. 允许 使用 AMP 优化器转换从 Markdown 创建的 HTML 文档 文件输入有效的 AMP。 典型的转换流程是:

README.md QQ HTML AMP 优化器 QQ 有效 AMP

这个变压器唯一要做的就是转换 `<img>` 标记输入 无论是 `amp-img` 或者说 `amp-anim` 标签。 所有其他的马克下特性都是 已经由 AMP 支持 。 变压器将尝试解析图像 从实际文件的维度。 大于 320px 的图像会自动 获得内在布局。 对于图像检测工作, 可选依赖 `probe-image-size` 需要通过国家预防机制安装.

-   名称 : `markdown`
-   有效选项 : `[true|false]`
-   默认 : `false`
-   用于: [标记](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/Markdown.js)

#### `minify`

缩小生成的 HTML 输出和内置 CSS .

-   名称 : `minify`
-   有效选项 : `[true|false]`
-   默认 : `true`
-   用于: [减肥Html](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/MinifyHtml.js), (中文(简体) ), [分离键框](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/SeparateKeyframes.js)

**警告:** 在每次请求中运行 AMP 优化器时不推荐此设置, 因为执行时间可以增加 7x .

#### `optimizeAmpBind`

在 `amp-bind`通过注射 `i-amphtml-binding` 属性.

-   名称 : `optimizeAmpBind`
-   有效选项 : `[true|false]`
-   默认 : `true`
-   用于: [优化AmpBind](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/OptimizeAmpBind.js)

#### `optimizeHeroImages`

启用英雄图像优化 。 英雄图像将自动被检测到,或者您可以通过添加 `data-hero` 属性 :

```
<amp-img data-hero src="foo.jpg" ...>
```

最大可使用标记的英雄图像数 `data-hero` 实值 `2`。使用 `maxHeroImageCount` 参数.

英雄图像通过服务器端渲染优化 `img` 元素在 `amp-img` 键。 这可以显著地改善图像渲染性能,并降低 [最大内含涂料](https://web.dev/lcp/) 来自 [核心网络维度](https://web.dev/vitals/)。 。 。 .

-   名称 : `optimizeHeroImages`
-   有效选项 : `[true|false]`
-   默认 : `true`
-   用于: [优化英雄形象](https://npmcn.com/package/%40ampproject/toolbox-optimizer/lib/transformers/OptimizeHeroImages.js)

#### `preloadHeroImage`

折旧、使用 [优化英雄形象](https://npmcn.com/package/%40ampproject/toolbox-optimizer/#readme-optimizeheroimages) 换句话说.

#### `verbose`

启用带有更详细记录输出的动词模式 .

-   名称 : `verbose`
-   有效选项 : `[true|false]`
-   默认 : `false`

## 特征

### 图像优化

AMP优化器帮助您服务优化的图像. 要做到这一点, 您需要提供映射图像的函数 `src` 改为大小 `srcset` 源值。 图像调整大小需要在构建时间(如静态站点)或通过图像托管服务(如: [缩略图](https://github.com/thumbor/thumbor)。 。 。 .

以下是将图像宽度附加到 `src`数字 :

```js
const ampOptimizer = AmpOptimizer.create({
  // parameters are the amp-img `src` and the `width` of the to be generated srcset source value
  imageOptimizer: (src, width) => {
    // we cannot rename if the image does not have a file extension
    const index = src.lastIndexOf('.');
    if (index === -1) {
      // return null means we won't generate a srcset source value for this width
      return null;
    }
    const prefix = src.substring(0, index);
    const postfix = src.substring(index, src.length);
    return `${prefix}.${width}w${postfix}`;
  };
})
```

利用这一实施,AMP优化器将改变以下功能: `amp-img` 声明:

```html
<!-- Injects srcset for responsive layout -->
<amp-img src="image1.png" width="400" height="800" layout="responsive"></amp-img>
<!-- Ignores existing srcset -->
<amp-img
  layout="fill"
  srcset="image-1x.png 1x,
                             image-2x.png 2x"
></amp-img>
```

改为:

```html
<!-- Injects srcset for responsive layout -->
<amp-img
  src="image1.png"
  width="400"
  height="800"
  layout="responsive"
  srcset="image1.470w.png 470w, image1.820w.png 820w, image1.1440w.png 1440w"
></amp-img>
<!-- Ignores existing srcset -->
<amp-img
  layout="fill"
  srcset="image-1x.png 1x,
                               image-2x.png 2x"
></amp-img>
```

**重要** 使用时 `layout=responsive` 使用该 `width` 财务报告和审定财务报表 `height` 属性以指定最小图像尺寸。 例如,对于移动上的全血英雄图像,指定宽度为:`width=320`。 。 。 .

### 自动添加不完整的标记

可以通过不完整文档, AMP 优化器会添加任何 缺少有效 AMP 文件所需的标签和扩展导入.

```js
const originalHtml = `
  <h1>Hello World!</h1>
  <amp-twitter width="375"
               height="472"
               layout="responsive"
               data-tweetid="1182321926473162752">
  </amp-twitter>
`;

// you can pass the canonical URL, default is `.`
const opts = {
  canonical: '/example.html',
};
ampOptimizer.transformHtml(originalHtml, opts).then((optimizedHtml) => {
  // optimizedHtml will be a valid AMP document
  console.log(optimizedHtml);
});
```

### 自动标记下转换

AMP优化器支持将Markdown转换为AMPHTML. 典型的转换流程是:

```
README.md => HTML => AMP Optimizer => valid AMP
```

AMP 优化器转换 `<img>` 标记输入 `<amp-img>` 或者说 `<amp-anim>` 在 Markdown 模式下标记。 通过启用 Markdown 模式 `markdown : true`。AMP 优化器将尝试从实际文件中解析图像维度。 宽于 320px 的图像将自动获得一个 `intrinsic` 设置.

所有其他的Markdown特性已经得到AMP的支持.

您可以通过一个附加选项 `imageBasePath` 要指定用于在构建时解析图像的基础路径,这可以是文件系统路径或 URL 前缀.

**重要内容:** 用于图像大小检测以工作,可选依赖 `probe-image-size` 需要通过国家预防机制安装.

```shell
npm install probe-image-size --save-dev
```

示例

```js
const AmpOptimizer = require('@ampproject/toolbox-optimizer');
const md = require('markdown-it')({
  // don't sanitize html if you want to support AMP components in Markdown
  html: true,
});

// enable markdown mode
const ampOptimizer = AmpOptimizer.create({
  markdown: true,
});

const markdown = `
# Markdown 🤯

Here is an image declared in Markdown syntax:

![A random image](https://unsplash.it/800/600).

You can directly declare AMP components:

<amp-twitter width="375"
             height="472"
             layout="responsive"
             data-tweetid="1182321926473162752">
</amp-twitter>

Any missing extensions will be automatically imported.
`;

const html = md.render(markdown);

const amphtml = await ampOptimizer.transformHtml(html, {
  canonical: filePath,
});
```

你可以找到工作样本 [这里](https://npmcn.com/packages/optimizer/demo/markdown)。 。 。 .

## 扩展 AMP 用自定义转换优化器

AMP优化器支持自定义 HTML 转换 :

```js
const AmpOptimizer = require('@ampproject/toolbox-optimizer');
const {createElement, firstChildByTag, appendChild} = AmpOptimizer.NodeUtils;

class CustomTransformer {
  constructor(config) {
    this.log_ = config.log.tag('CUSTOM');
  }
  transform(tree, params) {
    this.log_.info('Running custom transformation for ', params.filePath);
    const html = firstChildByTag(tree, 'html');
    if (!html) return;
    const head = firstChildByTag(html, 'head');
    if (!head) return;
    const desc = createElement('meta', {
      name: 'description',
      content: 'this is just a demo',
    });
    appendChild(head, desc);
  }
}

// it's best to run custom transformers first
const customTransformations = [CustomTransformer, ...AmpOptimizer.TRANSFORMATIONS_AMP_FIRST];

// pass custom transformers when creating the optimizer
const optimizer = AmpOptimizer.create({
  transformations: customTransformations,
});
// you can add custom parameters on a per document basis
const transformedHtml = await optimizer.transformHtml(html, {
  filePath,
});
```

离职 [样本](https://npmcn.com/packages/optimizer/demo/simple/index.js) 学习如何自定义 AMP 优化器.

## 最佳做法

### 确保启用 AMP Boilerplate 清除

最大的业绩收益来自 [删除 AMP 锅炉板代码](https://amp.dev/documentation/guides-and-tutorials/optimize-and-measure/server-side-rendering/#why-is-it-faster?)然而,在某些情况下,无法去除锅炉板代码:

-   若为`amp-experiment`, (中文(简体) ), `amp-story` 或者说 `amp-dynamic-css-classes` 使用组件([代码](https://github.com/ampproject/amphtml/blob/62a9eab084ccd800d80a371e2cb29cd4f9e8576a/src/render-delaying-services.js#L39-L43)) (中文(简体) ).

为了找出,为什么AMP锅炉板不能被取出,启用 `verbose` 模式 :

```js
// globally
const optimizer = ampOptimizer.create({
  verbose: true,
});
```

...或单个页面:

```js
// per transformation
ampOptimizer.transformHtml(originalHtml, {
  verbose: true,
});
```

### 可能的话在构建时转换 AMP 页面

将转换应用到 AMP 文件会消耗额外的服务器资源 。 另外,由于应用变换需要整个文件,在应用时也变得无法流出响应. 为了避免服务器起落架空,如果需要转换的一组AMP文件提前知道,转换应该在构建时运行.

### 运行时缓存已转换 AMP

虽然大多数网站具有更动态的性质,但无法静态地应用转型。 对于此类情况,可以在AMP页面提供后运行转换,例如,在Express中间软件中运行。 在这种情况下,为了实现最佳的性能,最好为以后的请求缓存已转换的页面. 缓存可以在CDN级别,站点内部基础设施(如:Memcached)上进行,甚至可以在服务器本身上进行,如果一组页面小到足以与内存相适应.

### 每周至少更新一次页面

AMP优化器内置了AMP所需的CSS样式. 为了保证内置的CSS与最新的AMP发布保持同步,我们建议每周至少再生成一页Out-of-sync CSS不会打破你的页面,但理论上可能会使AMP组件与"错误"风格短暂地出现,比如当应当被隐藏时可见. 好消息是,这些故障只是暂时的,因为一旦AMP JS开始,它将检查内置的CSS,并在需要时更新.

## 实验特征

**警告:这些功能是实验性的,可能导致AMP页面无效.**

### 和平计划

当使用实验特性导致无效的AMP时,最好设置成对的AMP模式. Paired AMP 模式将添加 `<link rel=amphtml href=${ampUrl}>` 改为: `ampUrl` 需要指向此页面的有效版本.

示例

```js
const optimizer = AmpOptimizer.create({
  transformations: AmpOptimizer.TRANSFORMATIONS_PAIRED_AMP,
});
const ampFilePath = filePath.substring(1, filePath.length).replace('.html', '.amp.html');
const transformedHtml = await optimizer.transformHtml(html, {
  // needed to calculate the `<link rel=amphtml href=${ampUrl}>`
  ampUrl: ampFilePath,
});
```

### 版本的 AMP 运行时间

这个 `ampRuntimeVersion` 参数将重写所有 AMP 运行时间和扩展导入到指定的版本 。 例如:

```
https://cdn.ampproject.org/v0.js
```

改为:

```
https://cdn.ampproject.org/rtv/001515617716922/v0.js
```

版本的AMP运行时间 URL有一个主要的好处: 版本的AMP运行时间 URL服务的最大年龄比未版本的要长. 这意味着 AMP 页面服务于版本的 AMP 运行时间从更好的浏览器缓存中获益 .

**重要内容:** 当使用已版本的 AMP 运行时间 URL 时, 当发布新的 AMP 运行时间时, 保证所有缓存无效 。 这是为了确保您的 AMP 页面总是使用最新的 AMP 运行时间 .

你用得着 [@ ampproject/toolbox- runtime- 版本](https://npmcn.com/packages/runtime-version) 以获取最新版本的 AMP 运行时间。 以下是应用优化包括版本URL的样本:

```js
const ampOptimizer = require('@ampproject/toolbox-optimizer');
const ampRuntimeVersion = await runtimeVersion.currentVersion();

// The input string
const originalHtml = `
<!doctype html>
<html ⚡>
...
`;

// Additional options can be passed as the second argument
const optimizedHtml = await ampOptimizer.transformHtml(originalHtml, {
  ampUrl: 'canonical.amp.html',
  ampRuntimeVersion: ampRuntimeVersion,
});

console.log(optimizedHtml);
```

### 模糊图像占位符

添加占位符用于 `amp-img` 财务报告和审定财务报表 `amp-video` 海报。 占位符是对应原始源的模糊版本. 模糊将显示为 `<amp-img>` 正在渲染,当元素被装入时会淡出。 附加模糊的占位符的当前要求是,该元素必须是JPEG,它要么是响应性的,要么是海报 `amp-video`。 。 。 .

**重要的:模糊的图像占位符计算在计算上是昂贵的. 确保仅用于静态或缓存页面.**

此变压器支持以下选项:

-   `blurredPlaceholders`: 启用模糊的图像占位符生成 。 默认是 `false`。 。 。 .
-   `imageBasePath`: 指定用于在构建时解析图像的基础路径.
-   `maxBlurredPlaceholders`:指定模糊图像的最大数量。 默认为 5.
-   `blurredPlaceholdersCacheSize`: 指定要缓存的模糊图像的最大数量 以避免昂贵的重新计算。 如果缓存被禁用, 设置为 0 。 设为 - 1 ,如果 所有占位符都应被缓存(对静态站点有利). 默认为 30.

用法 :

```js
const optimizer = AmpOptimizer.create({
  blurredPlaceholders: true,
});
```

### 自办的AMP组件

可以重写 AMP 框架和组件导入到一个不同的域 `cdn.ampproject.org`。 。 。 .

示例

```js
const ampOptimizer = require('@ampproject/toolbox-optimizer');

// The input string
const originalHtml = `
<!doctype html>
<html ⚡>
...
`;

// Additional options can be passed as the second argument
const optimizedHtml = await ampOptimizer.transformHtml(originalHtml, {
  ampUrl: 'canonical.amp.html',
  // this will rewrite https://cdn.ampproject.org/v0.js to /amp/v0.js
  ampUrlPrefix: '/amp',
});

console.log(optimizedHtml);
```

### AMP- geo 的后退 API

理想的情况是,当自我托管AMP框架时, `amp-geo-0.1.js` 应在交付时补丁以替换 `{{AMP_ISO_COUNTRY_HOTPATCH}}` 与请求源头的ISO 3166-1α-2国家代码([参考文献](https://github.com/ampproject/amphtml/blob/main/spec/amp-cache-guidelines.md#guidelines-adding-a-new-cache-to-the-amp-ecosystem)) (中文(简体) ). 如果您的主机没有这种能力, 您可以依靠网络 API 在运行时返回国家 。 网络 API 必须安全 (HTTPS), 遵守 [AMP CORS准则](https://amp.dev/documentation/guides-and-tutorials/learn/amp-caches-and-cors/amp-cors-requests/),并以下列格式返回 JSON :

```js
{"country": "de"}
```

在这个例子中, `de` 是德国的ISO 3166-1 α-2国家代码.

示例

```js
const ampOptimizer = require('@ampproject/toolbox-optimizer');

// The input string
const originalHtml = `
<!doctype html>
<html ⚡>
...
`;

const optimizedHtml = await ampOptimizer.transformHtml(originalHtml, {
  // this will instruct amp-geo to fetch the user's country from an API
  // which returns JSON in format: {"country": "de"}
  geoApiUrl: 'https://example.com/geo',
});

console.log(optimizedHtml);
```

## 开发和测试

AMP优化者采用以快照为基础的测试方法. 要执行测试, 请在工程根中运行 :

```shell
npm run test:node
```

变形器测试位于:

```
- spec/transformers/valid/TransformerName/test-name/
    expected_output.html
    input.html
```

转换输入定义于 `input.html`,则 `expected_output.html` 包含预期 成果。 不要编辑 `expected_output.html` 换成是手动的 换成是 变压器执行,运行:

```shell
npm run test:optimizer:snapshot
```

用于在 `expected_output.html`。 。 。 .

## 常见问题

### @ampproject/toolbox-optimizer 是什么？

AMPs的服务器端渲染\.

### 如何安装 @ampproject/toolbox-optimizer？

在项目目录运行 npm install @ampproject/toolbox-optimizer，或使用 pnpm add / yarn add / bun add。

### @ampproject/toolbox-optimizer 支持 TypeScript 吗？

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

### @ampproject/toolbox-optimizer 支持 ESM 还是 CommonJS？

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

### @ampproject/toolbox-optimizer 可以商用吗？

@ampproject/toolbox-optimizer 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ampproject/toolbox-optimizer 的下载量有多少？

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

### @ampproject/toolbox-optimizer 还在维护吗？

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