Hugo 配置 HTTP 缓存

Hugo 配置 HTTP 缓存。

此配置仅在使用 resources.GetRemote 函数时相关。

分层缓存

Hugo 使用分层缓存系统。

Dynacache: 使用最近最少使用 (LRU) 驱逐策略的内存缓存。当发生更改、匹配缓存清除模式或内存不足时，条目将从缓存中移除。
HTTP 缓存: 远程资源的 HTTP 缓存，如 RFC 9111 中指定。当资源包含适当的 HTTP 缓存头时可实现最佳性能。HTTP 缓存使用文件缓存来存储和检索缓存的资源。
文件缓存: 详见配置文件缓存。

HTTP 缓存涉及两个关键方面：确定缓存哪些内容（缓存过程本身）和定义检查更新的频率（轮询策略）。

HTTP 缓存

HTTP 缓存行为为一组配置的资源定义。即使配置的服务时间 (TTL) 尚未过期，过期的资源也会从文件缓存刷新。如果资源禁用了 HTTP 缓存，Hugo 将绕过缓存直接访问文件。

这是 HTTP 缓存的默认配置：

HTTPCache:
  cache:
    for:
      excludes:
      - '**'
      includes: null
  polls:
  - disable: true
    for:
      excludes: null
      includes:
      - '**'
    high: 0s
    low: 0s
  respectCacheControlNoStoreInRequest: true
  respectCacheControlNoStoreInResponse: false

[HTTPCache]
  respectCacheControlNoStoreInRequest = true
  respectCacheControlNoStoreInResponse = false
  [HTTPCache.cache]
    [HTTPCache.cache.for]
      excludes = ['**']
  [[HTTPCache.polls]]
    disable = true
    high = '0s'
    low = '0s'
    [HTTPCache.polls.for]
      includes = ['**']

{
   "HTTPCache": {
      "cache": {
         "for": {
            "excludes": [
               "**"
            ],
            "includes": null
         }
      },
      "polls": [
         {
            "disable": true,
            "for": {
               "excludes": null,
               "includes": [
                  "**"
               ]
            },
            "high": "0s",
            "low": "0s"
         }
      ],
      "respectCacheControlNoStoreInRequest": true,
      "respectCacheControlNoStoreInResponse": false
   }
}

respectCacheControlNoStoreInRequest: New in v0.151.0; (bool) 在使用 resources.GetRemote 函数获取远程资源时，是否尊重服务器 Cache-Control 请求头中的 no-store 指令。默认值是 true。
respectCacheControlNoStoreInResponse: New in v0.151.0; (bool) 在使用 resources.GetRemote 函数获取远程资源时，是否尊重服务器 Cache-Control 响应头中的 no-store 指令。默认值是 false。
cache.for.excludes: ([]string) 从缓存中排除的 glob 模式切片。在默认配置中，HTTP 缓存排除所有文件。
cache.for.includes: ([]string) 要缓存的 glob 模式切片。
polls: 轮询配置切片。
polls.disable: (bool) 是否禁用此配置的轮询。默认值是 true。
polls.high: (string) 最大轮询间隔，表示为持续时间。当资源被认为稳定时使用。默认值是 0s。
polls.low: (string) 最小轮询间隔，表示为持续时间。在最近更改后使用，并逐渐增加到 polls.high。默认值是 0s。
polls.for.excludes: ([]string) 从轮询中排除的 glob 模式切片。
polls.for.includes: ([]string) 包含在轮询中的 glob 模式切片。

HTTP 轮询

轮询用于监视模式（如 hugo server）以检测远程资源的变化。即使禁用了 HTTP 缓存，也可以启用轮询。检测到的更改会触发使用受影响资源的页面重建。可以为特定资源禁用轮询，通常是那些已知是静态的资源。

默认配置禁用所有内容：

HTTPCache:
  polls:
  - disable: true
    for:
      excludes: []
      includes:
      - '**'
    high: 0s
    low: 0s

[HTTPCache]
  [[HTTPCache.polls]]
    disable = true
    high = '0s'
    low = '0s'
    [HTTPCache.polls.for]
      excludes = []
      includes = ['**']

{
   "HTTPCache": {
      "polls": [
         {
            "disable": true,
            "for": {
               "excludes": [],
               "includes": [
                  "**"
               ]
            },
            "high": "0s",
            "low": "0s"
         }
      ]
   }
}

polls: 轮询配置切片。
polls.disable: (bool) 是否禁用此配置的轮询。默认值是 true。
polls.high: (string) 最大轮询间隔，表示为持续时间。当资源被认为稳定时使用。默认值是 0s。
polls.low: (string) 最小轮询间隔，表示为持续时间。在最近更改后使用，并逐渐增加到 polls.high。默认值是 0s。
polls.for.excludes: ([]string) 从轮询中排除的 glob 模式列表。
polls.for.includes: ([]string) 包含在轮询中的 glob 模式列表。

行为

轮询和 HTTP 缓存的交互如下：

启用轮询时，仅通过实际更改触发重建，通过 eTag 更改检测（如果服务器未提供，Hugo 会生成 MD5 哈希）。
如果启用了轮询但禁用了 HTTP 缓存，则仅在文件缓存的 TTL 过期后检查远程更改（例如，maxAge 为 10h 且轮询间隔为 1s 是低效的）。
如果启用了轮询和 HTTP 缓存，则即使在文件缓存的 TTL 过期之前也会检查更改。缓存的 eTag 和 last-modified 值分别在 if-none-match 和 if-modified-since 头中发送，并在 HTTP 304 上返回缓存的响应。

Last updated: January 1, 0001

Improve this page