XinTheme Cache 使用文档

XinTheme Cache 文档

高级缓存配置

开启高级缓存规则后，服务器会在检测到静态 HTML 缓存文件时直接返回页面，无需再经过 WordPress 和 PHP，从而进一步提升缓存页面的访问速度。

该功能需要手动配置 Apache 或 Nginx 服务器规则，仅推荐有服务器配置经验的用户使用。一般情况下，默认缓存模式已经可以满足大多数网站的性能需求。

注意：此配置为可选增强项，并不是使用缓存功能的必要条件。由于页面会被服务器直接返回，插件将无法在该流程中判断缓存过期时间及部分排除规则。

Nginx 直出缓存配置

此处以宝塔面板示例

宝塔面板添加位置

  1. 进入宝塔面板。
  2. 打开“网站”。
  3. 找到目标站点，点击“设置”。
  4. 打开“伪静态”。
  5. 将原来的 WordPress 伪静态 location / 替换为 XinTheme Cache 规则。

宝塔 Nginx 规则示例

下面是适合站点根目录安装 WordPress 的基础示例。移动端和压缩缓存相关配置建议确认普通缓存命中后再开启。

# XinTheme Cache cache directory.
set $xintheme_cache_dir '/wp-content/cache/xintheme-cache';

# Default cache keys.
set $xintheme_cache_key_scheme      'http-';
set $xintheme_cache_key_device      '';
set $xintheme_cache_key_compression '';
set $xintheme_cache_content_encoding '';

# Scheme cache key.
if ( $scheme = https ) {
    set $xintheme_cache_key_scheme 'https-';
}

# Device cache key.
# if ( $http_user_agent ~* '(Mobile|Android|Silk/|Kindle|BlackBerry|Opera.*Mini|Opera.*Mobi)' ) {
#     set $xintheme_cache_key_device '-mobile';
# }

# Compression cache key.
# if ( $http_accept_encoding ~* 'gzip' ) {
#     set $xintheme_cache_key_compression '.gz';
#     set $xintheme_cache_content_encoding 'gzip';
# }
# if ( $http_accept_encoding ~* 'br' ) {
#     set $xintheme_cache_key_compression '.br';
#     set $xintheme_cache_content_encoding 'br';
# }

set $xintheme_cache_file_dir  ${xintheme_cache_dir}/${host}${uri};
set $xintheme_cache_file_name ${xintheme_cache_key_scheme}index${xintheme_cache_key_device}.html${xintheme_cache_key_compression};
set $xintheme_cache_file      ${xintheme_cache_file_dir}/${xintheme_cache_file_name};

location / {
    error_page 405 = @xintheme_cache_fallback;
    recursive_error_pages on;

    gzip off;
    gzip_static off;

    default_type text/html;
    add_header Content-Encoding $xintheme_cache_content_encoding always;
    add_header Vary 'Accept-Encoding' always;
    add_header X-Cache-Handler 'xintheme-cache-nginx' always;

    if ( $request_method !~ ^(GET|HEAD)$ ) {
        return 405;
    }

    if ( $http_accept !~* 'text/html' ) {
        return 405;
    }

    if ( $uri ~ /[^./]$ ) {
        return 405;
    }

    if ( $query_string ~ ^(?!(fbclid|ref|mc_(cid|eid)|utm_(source|medium|campaign|term|content|expid)|gclid|fb_(action_ids|action_types|source)|age-verified|usqp|cn-reloaded|_ga|_ke)).+$ ) {
        return 405;
    }

    if ( $http_cookie ~* '(wp-postpass|wordpress_logged_in|comment_author)_' ) {
        return 405;
    }

    try_files $xintheme_cache_file @xintheme_cache_fallback;
}

location @xintheme_cache_fallback {
    try_files $uri $uri/ /index.php?$args;
}

Gzip 与 Brotli 注意事项

浏览器通常会发送 Accept-Encoding: gzip, deflate, br。如果 Nginx 配置启用了 Brotli，它会优先查找 .br 文件。如果服务器没有生成 .br 文件，就会回退到 PHP。

如果站点全局开启了 gzip 或 gzip_static，直出缓存的 location 中应保留 gzip off; 和 gzip_static off;，避免预压缩缓存响应出现重复的 Content-Encoding。

建议按这个顺序测试：

  1. 先不开启压缩缓存键，确认普通 .html 能命中。
  2. 再只开启 Gzip，确认 .gz 能命中。

Apache 直出缓存配置

Apache 可以通过 .htaccess 直接读取 XinTheme Cache 生成的静态 HTML 文件。请将规则放在 # BEGIN WordPress 之前。

Apache 基础规则

# BEGIN XinTheme Cache

<IfModule mod_rewrite.c>
    <IfModule mod_setenvif.c>
        RewriteEngine On
        RewriteBase /

        SetEnvIf Host ^ XINTHEME_CACHE_DIR=/wp-content/cache/xintheme-cache

        SetEnvIf Host ^ XINTHEME_CACHE_KEY_SCHEME http-
        SetEnvIf Host ^ XINTHEME_CACHE_KEY_DEVICE
        SetEnvIf Host ^ XINTHEME_CACHE_KEY_COMPRESSION

        RewriteCond %{HTTPS} ^(on|1)$ [OR]
        RewriteCond %{SERVER_PORT} =443 [OR]
        RewriteCond %{HTTP:X-Forwarded-Proto} =https [OR]
        RewriteCond %{HTTP:X-Forwarded-Scheme} =https
        RewriteRule ^ - [E=XINTHEME_CACHE_KEY_SCHEME:https-]

        # SetEnvIfNoCase User-Agent "(Mobile|Android|Silk/|Kindle|BlackBerry|Opera.*Mini|Opera.*Mobi)" XINTHEME_CACHE_KEY_DEVICE=-mobile

        # <IfModule mod_mime.c>
        #     SetEnvIfNoCase Accept-Encoding gzip XINTHEME_CACHE_KEY_COMPRESSION=.gz
        #     AddType text/html .gz
        #     AddEncoding gzip .gz
        # </IfModule>

        SetEnvIf Host ^ XINTHEME_CACHE_FILE_DIR=%{ENV:XINTHEME_CACHE_DIR}/%{HTTP_HOST}%{REQUEST_URI}
        SetEnvIf Host ^ XINTHEME_CACHE_FILE_NAME=%{ENV:XINTHEME_CACHE_KEY_SCHEME}index%{ENV:XINTHEME_CACHE_KEY_DEVICE}.html%{ENV:XINTHEME_CACHE_KEY_COMPRESSION}
        SetEnvIf Host ^ XINTHEME_CACHE_FILE=%{ENV:XINTHEME_CACHE_FILE_DIR}/%{ENV:XINTHEME_CACHE_FILE_NAME}

        RewriteCond %{DOCUMENT_ROOT}%{ENV:XINTHEME_CACHE_FILE} -f
        RewriteCond %{REQUEST_METHOD} =GET
        RewriteCond %{HTTP:Accept} text/html [NC]
        RewriteCond %{REQUEST_URI} (^/$|/[^\./\?]+/(\?.*)?$)
        RewriteCond %{QUERY_STRING} !^(?!(fbclid|ref|mc_(cid|eid)|utm_(source|medium|campaign|term|content|expid)|gclid|fb_(action_ids|action_types|source)|age-verified|usqp|cn-reloaded|_ga|_ke)).+$
        RewriteCond %{HTTP_COOKIE} !(wp-postpass|wordpress_logged_in|comment_author)_ [NC]

        RewriteRule ^ - [E=XINTHEME_CACHE_HIT:1]
        RewriteRule ^ %{ENV:XINTHEME_CACHE_FILE} [L]

        <IfModule mod_headers.c>
            Header set X-Cache-Handler "xintheme-cache-apache" env=XINTHEME_CACHE_HIT
            Header append Vary "Accept-Encoding" env=XINTHEME_CACHE_HIT
        </IfModule>
    </IfModule>
</IfModule>

# END XinTheme Cache

如何判断是否生效

浏览器查看响应头，如果看到下面的响应头，说明命中了 Nginx 直出：

X-Cache-Handler: xintheme-cache-nginx

如果看到下面的响应头，说明仍然走了插件的 PHP drop-in：

X-Cache-Handler: xintheme-cache
这页内容对你有帮助吗？
有帮助 没有帮助

文章目录