README

按需的静态网站性能！

此插件将为您的常规Kirby安装提供静态网站生成器的性能。无需庞大的设置或复杂的部署步骤，您可以在任何服务器上运行Kirby网站——便宜的共享主机、VPS，您想要的任何东西——并启用静态缓存，按需获得惊人的速度。

通过自定义忽略规则，您甚至可以将静态和动态内容混合在一起。保持一些页面静态，而其他页面则由Kirby实时提供。

每当在面板中更新内容时，静态缓存将自动刷新。这确实是两者的最佳结合。

针对我们的Starterkit主页的粗略基准比较

无页面缓存：~70毫秒
有页面缓存：~30毫秒
有静态缓存：~10毫秒

限制

静态缓存的页面将阻止任何Kirby逻辑的执行。这意味着Kirby不能再区分访客和登录用户。每个请求都将直接由您的Web服务器提供，即使响应会根据cookie或其他请求头而不同。

如果您的网站在控制器、页面模型、模板、代码片段或插件中有任何逻辑，这些逻辑会导致根据请求产生不同的页面响应，那么这种逻辑将自然与Staticache不兼容。

如果只有特定的页面受到影响，您可以将其添加到缓存忽略列表（见下文），并为网站的其他部分使用Staticache。否则，使用Kirby的默认页面缓存将是更好的选择，因为Kirby将自动检测哪些响应可以被缓存，以及哪些缓存可用于当前请求。

安装

下载

下载并将此存储库复制到/site/plugins/staticache。

Composer

composer require getkirby/staticache

Git子模块

git submodule add https://github.com/getkirby/staticache.git site/plugins/staticache

设置

缓存配置

基本设置

Staticache是一个缓存驱动器，可以为页面缓存激活

// /site/config/config.php

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'type'   => 'static'
    ]
  ]
];

忽略规则

如果您想保留一些页面为动态的，您可以配置忽略规则，就像原生页面缓存一样：https://getkirby.com/docs/guide/cache#caching-pages

// /site/config/config.php

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'type'   => 'static',
      'ignore' => function ($page) {
        return $page->template()->name() === 'blog';
      }
    ]
  ]
];

所有未忽略的页面将在第一次访问时自动缓存。当面板中的更改时，Kirby会自动清除缓存。

请注意，已缓存的页面不受ignore选项更改的影响。您的Web服务器将获取已创建的文件，而不会检查页面是否可缓存。如果您看到忽略页面的缓存结果，请手动清除您的缓存目录。

另外，请注意，Kirby的默认缓存逻辑适用于手动忽略的页面。如果您的模板使用任何依赖于用户会话或请求头的函数（例如$kirby->session()、csrf()...），则您的页面将不会被缓存。

自定义缓存注释

默认情况下，Staticache会在每个缓存的HTML文件末尾添加一个HTML注释，如。您可以在缓存配置中覆盖或禁用此注释。

// /site/config/config.php

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'type'   => 'static',

      // disabled comment
      'comment' => '',

      // OR string value (only for HTML)
      'comment' => '<!-- your custom comment -->',

      // OR a custom closure
      'comment' => fn ($contentType) => $contentType === 'html' ? '<!-- comment -->' : ''
    ]
  ]
];

自定义根目录

渲染的HTML文件存储在site/cache/example.com/pages/文件夹中，就像原生页面缓存一样。不同的是，这个文件夹中的所有路径都与您网站的URL结构相匹配。为每个根URL设置单独的目录确保了即使在多域名设置中，您渲染的HTML中的链接和引用也能正常工作。

如果您使用的是自定义的Web服务器设置，您可以像这样覆盖缓存根目录：

// /site/config/config.php

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'type'   => 'static',
      'root'   => '/path/to/your/cache/root',
      'prefix' => null
    ]
  ]
];

如果您的网站只在一个域名上提供服务，您可以像这样禁用根URL前缀，同时保持通用存储位置在site/cache目录中：

// /site/config/config.php

return [
  'cache' => [
    'pages' => [
      'active' => true,
      'type'   => 'static',
      'prefix' => 'pages'
    ]
  ]
];

如果您使用自定义的根目录和/或前缀，请相应地修改以下服务器配置示例。

如果您的自定义根目录位于服务器文档根之外，用户已经成功使用以下解决方案：

从您的自定义根目录到一个文档根内部路径创建一个符号链接（symlink）。然后在服务器配置中使用文档根内部的路径。为了使此方法正常工作，服务器需要设置成可以跟踪符号链接。
在Apache设置中：将%{DOCUMENT_ROOT}变量替换为服务器上您的自定义根目录的绝对路径。例如：RewriteCond /var/www/yourPath/%{REQUEST_URI}/...

在任何情况下，请确保您的Web服务器可以读取自定义根目录中的缓存文件，否则它将无法处理带有静态缓存文件的请求。

Web服务器集成

此插件将自动生成和存储缓存文件，但是您需要配置您的Web服务器来提取这些文件，并将它们优先于PHP的动态结果。

配置取决于您使用的Web服务器。

Apache

将以下行添加到您的Kirby .htaccess文件中，在RewriteBase规则之后直接添加。

RewriteCond %{DOCUMENT_ROOT}/site/cache/%{SERVER_NAME}/pages/%{REQUEST_URI}/index.html -f
RewriteRule ^(.*) %{DOCUMENT_ROOT}/site/cache/%{SERVER_NAME}/pages/%{REQUEST_URI}/index.html [END]

RewriteCond %{DOCUMENT_ROOT}/site/cache/%{SERVER_NAME}/pages/%{REQUEST_URI} -f
RewriteRule ^(.*) %{DOCUMENT_ROOT}/site/cache/%{SERVER_NAME}/pages/%{REQUEST_URI} [END]

Caddy

Staticache的简单Caddy配置可能如下所示：

example.com

root * /path/to/your/site

file_server
php_fastcgi unix//var/run/php-fpm.sock {
  try_files {path} site/cache/{host}/pages/{path}/index.html site/cache/{host}/pages/{path} index.php
}

nginx

标准的PHP nginx配置将为此所有请求有这个位置块：

location / {
  try_files $uri $uri/ /index.php?$query_string;
}

将其更改为在最后一个/index.php回退之前添加/site/cache/$server_addr/pages/$uri/index.html

location / {
  try_files $uri $uri/ /site/cache/$server_addr/pages/$uri/index.html /site/cache/$server_addr/pages/$uri /index.php?$query_string;
}

PHP加载器

如果您无法访问服务器配置，您可以从Kirby的index.php中加载静态缓存。与Kirby内置的页面缓存相比，这种方法避免了每次请求都加载Kirby，但所有请求仍然传递给PHP。这使得这种方法比直接集成到Web服务器慢，但仍然比内置页面缓存快得多。

要从PHP加载静态缓存文件，请将以下代码片段放置在您的index.php文件顶部（直接在<?php标签之后）：

(function /* staticache */ () {
  $root = __DIR__ . '/site/cache';

  // only use cached files for static responses, pass dynamic requests through
  if (in_array($_SERVER['REQUEST_METHOD'], ['GET', 'HEAD']) === false) {
    return;
  }

  // check if a cache for this domain exists
  $root .= '/' . $_SERVER['SERVER_NAME'] . '/pages';
  if (is_dir($root) !== true) {
    return;
  }

  // determine the exact file to use
  $path = $root . '/' . ltrim($_SERVER['REQUEST_URI'] ?? '', '/');
  if (is_file($path . '/index.html') === true) {
    // a HTML representation exists in the cache
    $path = $path . '/index.html';
  } elseif (is_file($path) !== true) {
    // neither a HTML representation nor a custom
    // representation exists in the cache
    return;
  }

  // try to determine the content type from the static file
  if ($mime = @mime_content_type($path)) {
    header("Content-Type: $mime");
  }

  die(file_get_contents($path));
})();

如果您想使用PHP加载器，我们建议与头部支持（见下文）一起使用。存储头部可以提高性能，并为您提供更精确的响应。

头部支持

Staticache默认只存储响应体。HTTP状态码以及您页面设置的头部在此模式下不被保留。这确保了与所有Web服务器的兼容性。

如果您的Web服务器支持从静态文件中读取头部，您可以使用headers选项启用头部支持。

// /site/config/config.php

return [
  'cache' => [
    'pages' => [
      'active'  => true,
      'type'    => 'static',
      'headers' => true
    ]
  ]
];

您需要相应地调整您的Web服务器配置。

Apache

Apache中的头部支持需要mod_asis。请确保您的Apache安装已安装并启用了此模块。

之后，将以下块添加到您的.htaccess文件中，以便Apache使用mod_asis为缓存文件。

<Directory "/var/www/your-site/site/cache">
  SetHandler send-as-is
</Directory>

PHP加载器

将加载器函数的最后六行替换为以下代码：

  // split the file into headers (before two line breaks) and body
  $file    = file_get_contents($path);
  $divide  = mb_strpos($file, "\n\n");
  $headers = mb_substr($file, 0, $divide);
  $body    = mb_substr($file, $divide + 2);

  foreach (explode("\n", $headers) as $header) {
    if (mb_substr($header, 0, 7) === 'Status:') {
      http_response_code((int)trim(mb_substr($header, 8)));
    } else {
      header($header);
    }
  }

  die($body);

什么是Kirby？

getkirby.com – 了解CMS。
试用 – 使用我们的在线演示进行试驾。或者下载我们的套件开始使用。
文档 – 阅读官方指南、参考和食谱。
问题 – 报告错误和其他问题。
反馈 – 你对 Kirby 有什么想法？分享一下吧。
论坛 – 遇到难题时，不要犹豫，随时提出问题和寻求支持。
Discord – 加入社区，交流互动。
Mastodon – 传播信息。
Instagram – 分享你的作品：#madewithkirby。

getkirby / staticache

维护者

详细信息