Skip to content

内置优化插件

优化插件在构建您的项目时自动识别并优化所有媒体文件，使用常见的压缩和转换技术。因此，您的网站加载速度显著提高，并在搜索引擎中获得更好的排名。

目标

工作原理

该插件扫描docs目录中的媒体文件和资产，自动优化它们以减少site目录的最终大小。这导致加载时间更快，因为您向用户传送的数据量更少，同时也减少了离线可用文档的下载量。

优化后的图像会被智能缓存[intelligent caching]，这就是为什么插件只会优化自上次构建以来发生变化的媒体文件。这使得您可以更换或更新图像，而不必担心优化它们，或者更糟的是，忘记这样做。

为了优化媒体文件，您的系统需要具备一些依赖项。

何时使用

通常建议使用该插件，因为媒体文件会自动优化，无需干预，确保您的网站尽可能快速加载。优化后的媒体文件是搜索引擎中高且稳定排名的关键组成部分之一。

此外，该插件可以与Material for MkDocs提供的其他内置插件结合使用，以创建针对您项目的复杂构建管道：

  •   内置隐私插件

    隐私插件使得使用未优化的外部资产变得简单，在将它们复制到site目录之前，将其传递给优化插件。

    外部媒体文件可以自动下载和优化

  •   内置离线插件

    离线插件增加了构建离线可用文档的支持，因此您可以将site目录作为可以下载的.zip文件进行分发。

    您的文档可以作为更小的.zip下载进行分发

配置

9.7.0 optimize – built-in

与所有内置插件一样，使用优化插件非常简单。只需将以下行添加到mkdocs.yml中，观察媒体文件如何自动优化：

plugins:
  - optimize

优化插件内置于Material for MkDocs中，无需安装。

但是，为了优化所有媒体文件，必须安装图像处理的依赖项，如果它们尚未在您的系统上可用。链接的指南包含多个操作系统的说明，并提到了一些替代环境。

一般

以下设置可用：

enabled

9.7.0 true

使用此设置在构建您的项目时启用或禁用插件。如果您想禁用插件，例如用于本地构建，可以在mkdocs.yml中使用环境变量：

plugins:
  - optimize:
      enabled: !ENV [CI, false]

此配置仅在持续集成（CI）期间启用插件。

concurrency

9.7.0 available CPUs - 1

在可用的CPU更多时，插件可以并行处理更多工作，从而更快地完成媒体文件优化。如果您想完全禁用并发处理，请使用：

plugins:
  - optimize:
      concurrency: 1

默认情况下，插件使用所有可用的CPU - 1，最少为1。

缓存

该插件实现了智能缓存机制，确保只有在媒体文件或资产的内容发生变化时，才会通过优化管道。如果您更换或更新图像，插件会检测到并更新媒体文件的优化版本。

以下设置可用于缓存：

cache

9.7.0 true

使用此设置指示插件绕过缓存，以重新优化所有媒体文件，即使缓存可能并未过期。通常不需要指定此设置，除非在调试插件本身时。可以通过以下方式禁用缓存：

plugins:
  - optimize:
      cache: false

cache_dir

9.7.0 .cache/plugin/optimize

通常不需要指定此设置，除非您想更改媒体文件在根目录中的缓存路径。如果您想更改它，请使用：

plugins:
  - optimize:
      cache_dir: my/custom/dir

如果您使用多个实例的插件，为两个实例设置不同的缓存目录可能是个好主意，以免它们相互干扰。

优化

文档通常使用屏幕截图或图表来更好地可视化事物，这两者都是优化的主要候选对象。该插件使用pngquant自动优化.png文件，使用Pillow优化.jpg文件。

以下设置可用于优化：

optimize

9.7.0 true

使用此设置启用或禁用媒体文件优化。目前，插件的唯一目的是优化媒体文件，因此它等同于enabled设置，但在不久的将来，可能会添加其他功能。如果您想禁用优化，请使用：

plugins:
  - optimize:
      optimize: false

optimize_png

9.7.0 true

使用此设置启用或禁用对.png文件的优化。通常不需要指定此设置，但如果您想禁用对.png文件的优化，请使用：

plugins:
  - optimize:
      optimize_png: false

optimize_png_speed

9.7.0 3 of 1-10

使用此设置指定pngquant在优化.png文件时应用的速度/质量权衡。数字越低，表示pngquant将更积极地进行优化：

plugins:
  - optimize:
      optimize_png_speed: 1

plugins:
  - optimize:
      optimize_png_speed: 10

10的因子质量降低5%，但速度比默认的3快8倍。

optimize_png_strip

9.7.0 true

使用此设置指定pngquant是否应从.png文件中剥离不需要显示图像的可选元数据，例如EXIF。如果您想保留元数据，请使用：

plugins:
  - optimize:
      optimize_png_strip: false

optimize_jpg

9.7.0 true

使用此设置启用或禁用对.jpg文件的优化。通常不需要指定此设置，但如果您想禁用对.jpg文件的优化，请使用：

plugins:
  - optimize:
      optimize_jpg: false

optimize_jpg_quality

9.7.0 60 of 0-100

使用此设置指定Pillow在优化.jpg文件时应用的图像质量。如果图像看起来模糊，建议微调并更改此设置：

plugins:
  - optimize:
      optimize_jpg_quality: 75

optimize_jpg_progressive

9.7.0 true

使用此设置指定Pillow在优化.jpg文件时是否应使用渐进编码，以便在慢速连接上更快呈现。如果您想禁用渐进编码，请使用：

plugins:
  - optimize:
      optimize_jpg_progressive: false

optimize_include

9.7.0

使用此设置为项目的特定目录启用媒体文件优化，例如，当使用多个实例的插件以不同方式优化媒体文件时：

plugins:
  - optimize:
      optimize_include:
        - screenshots/*

此配置为包含在docs目录中的screenshots文件夹及其子文件夹中的所有媒体文件启用优化。

optimize_exclude

9.7.0

使用此设置为项目的特定目录禁用媒体文件优化，例如，当使用多个实例的插件以不同方式优化媒体文件时：

plugins:
  - social:
      optimize_exclude:
        - vendor/*

此配置禁用对包含在docs目录中的vendor文件夹及其子文件夹中的所有媒体文件的优化。

报告

以下设置可用于报告：

print_gain

9.7.0 true

使用此设置控制插件是否应打印优化每个文件后获得的字节数。如果您想禁用此行为，请使用：

plugins:
  - optimize:
      print_gain: false

print_gain_summary

9.7.0 true

使用此设置控制插件是否应打印优化所有文件后获得的总字节数。如果您想禁用此行为，请使用：

plugins:
  - optimize:
      print_gain_summary: false