Yii 2 页面缓存实战指南:用 PageCache 过滤器缓存整页输出

原创2026-09-22 23:01:501,650 阅读
文章标签:后端Web框架

Yii 2 页面缓存实战指南:用 PageCache 过滤器缓存整页输出

页面缓存(Page Caching)是 Yii 2 在服务器端缓存整页输出的机制:当同一页面再次被请求时,直接返回缓存内容,而不再重新执行控制器逻辑、渲染视图生成页面。本文以官方指南 caching-page.md(含日文版 docs/guide-ja/caching-page.md)为核心,结合框架源码 PageCache 与单元测试 PageCacheTest,讲解如何用 yii\filters\PageCache 动作过滤器配置缓存时长、语言变体与数据库依赖,并深入剖析其底层工作原理与实战注意事项。读完本文,你将能够为指定 action 快速启用整页缓存,并针对多语言、数据变更等场景进行精细化控制。

什么是页面缓存

页面缓存指在服务器端缓存整个页面的内容。与数据缓存(缓存数据库查询结果、配置等基础数据)和片段缓存(只缓存页面中的某个片段)不同,页面缓存直接保存最终渲染出的完整 HTML 输出。当后续请求到达时,系统直接从缓存中取出内容返回,省去了再次执行 action、查询数据库、渲染视图的整个链路,是提升高流量页面响应速度的有效手段。

Yii 2 官方缓存体系包含四个层次,详见 caching-overview.md:

  • 数据缓存(Data Caching)
  • 片段缓存(Fragment Caching)
  • 页面缓存(Page Caching,本文主题)
  • HTTP 缓存(HTTP Caching)

页面缓存在 Yii 2 中由 <a href="https://link.gitcode.com/i/06daa1e9b674d267a5aea37ae77440d1" target="_blank">[yii\filters\PageCache]] 实现,它是一个[动作过滤器(action filter),通过响应控制器(controller)的 EVENT_BEFORE_ACTION 事件参与 action 执行流程,在 action 执行前判断缓存是否有效,并在响应发送后把内容写入缓存。

基础用法:在控制器中启用页面缓存

页面缓存以动作过滤器的形式在控制器类的 behaviors() 方法中声明。官方指南给出的最小可用示例:

public function behaviors()
{
    return [
        [
            'class' => 'yii\filters\PageCache',
            'only' => ['index'],
            'duration' => 60,
            'variations' => [
                \Yii::$app->language,
            ],
            'dependency' => [
                'class' => 'yii\caching\DbDependency',
                'sql' => 'SELECT COUNT(*) FROM post',
            ],
        ],
    ];
}

这段配置的含义:

  • only => ['index']:页面缓存仅作用于 index action;
  • duration => 60:页面内容最多缓存 60 秒;
  • variations => [\Yii::$app->language]:按当前应用语言区分缓存版本,不同语言各存一份;
  • dependency:配置一个基于 SQL 查询结果的依赖(yii\caching\DbDependency),当 post 表的总行数发生变化时,缓存自动失效。

上述全部配置项都能在 PageCache.php 的公共属性中找到对应声明,下面逐一深入讲解。

核心属性逐项解析

作用范围:only 与 except

only 和 except 定义过滤器作用于哪些 action,它们继承自基类 ActionFilter:

  • only:过滤器仅应用于列出的 action ID;未设置时应用于所有 action;
  • except:过滤器不应用于列出的 action ID;
  • 若某 action 同时出现在 only 与 except 中,则不生效(except 优先);
  • 自 2.0.9 起支持通配符,例如 'only' => ['site/*']。

匹配逻辑实现在 ActionFilter::isActive(),内部通过 StringHelper::matchWildcard() 进行通配符匹配。注意:当过滤器挂载在模块上时,action ID 需包含子模块 ID 和控制器 ID。

缓存时长:duration

duration 指定缓存数据的有效秒数,默认值为 60。在 PageCache.php 的注释中明确:设置为 0 表示缓存永不过期。该值最终作为参数传给缓存组件的 set() 方法(见 cacheResponse() 中 $this->cache->set($this->calculateCacheKey(), $data, $this->duration, $this->dependency);)。

使用 duration => 0 时,缓存内容只有在 dependency 发生变化时才会失效,务必配合依赖使用,否则页面将长期停留在旧版本。

缓存变体:variations

variations 指定导致缓存内容产生差异的因素列表,每个因素是一个标量值(如语言、GET 参数)。例如多语言应用中同一份视图代码会生成不同语言的页面,就可以按 Yii::$app->language 区分缓存:

'variations' => [
    \Yii::$app->language,
],

自 2.0.48 起,variations 还可以传入匿名函数动态生成变体,这在需要读取 User 组件(其解析时机早于 PageCache 过滤器)时尤其有用:

'variations' => function () {
    return [
        Yii::$app->language,
        Yii::$app->user->id,
    ];
},

回调必须返回数组。该能力在 calculateCacheKey() 中实现:若 variations 是 Closure 则先执行回调取回数组,再与缓存键合并;单元测试 testClosureVariations() 验证了闭包返回数组与字符串两种情况的键拼接行为。

缓存依赖:dependency

dependency 可以是 yii\caching\Dependency 对象,也可以是创建依赖对象的配置数组。依赖用于在数据变化时主动使缓存失效,而不必等待 duration 到期。官方示例使用 DbDependency:

'dependency' => [
    'class' => 'yii\caching\DbDependency',
    'sql' => 'SELECT MAX(updated_at) FROM post',
],

这个配置会让输出缓存依赖于所有文章的最近修改时间——只要有任何文章被修改,缓存立即失效。

从源码看,DbDependency 提供三个属性:db(数据库连接对象或应用组件 ID,默认 'db')、sql(查询语句,必填,缺省会抛出 InvalidConfigException)、params(绑定到 SQL 的参数数组)。其原理是执行 sql 取第一行结果作为"依赖数据":写入缓存时保存该结果,读取时重新执行 SQL 并比较结果是否变化,这由基类 Dependency::isChanged() 完成。

提示:当同时启用 cacheCookies 或 cacheHeaders 时,依赖会被求值两次(cookie/header 与页面内容分开存储)。此时建议为依赖开启 reusable 属性,使同一请求内依赖数据只生成一次,以节省性能开销,见 PageCache.php 与 Dependency。

开关:enabled

enabled(默认 true)用于按条件整体开关页面缓存。典型场景是"表单页只在首次 GET 请求时缓存,POST 提交后的页面不缓存(避免缓存到含用户输入的表单)":

'enabled' => Yii::$app->request->isGet,

在 beforeAction() 开头,若 enabled 为 false 则直接放行(PageCache.php)。单元测试 cacheTestCaseProvider 中的 disabled 用例验证了关闭后缓存不会被写入。

按路由区分:varyByRoute

varyByRoute(默认 true)决定缓存是否按路由(controller ID + action ID)区分。在 calculateCacheKey() 中,缓存键以 <a href="https://link.gitcode.com/i/13e7bc9b4b6377a7d254a33350fd03e5" target="_blank">'yii\filters\PageCache'] 开头,若 varyByRoute 为 true 则追加 Yii::$app->requestedRoute。测试 [testVaryByRoute() 证明:开启时不同 action 的缓存互不干扰,关闭时则共享同一份缓存。

缓存组件:cache

cache 指定使用的缓存对象或应用组件 ID,默认值为 'cache'(即 Yii::$app->cache 组件)。在 beforeAction() 中通过 Instance::ensure() 解析为实现了 yii\caching\CacheInterface 的实例。自 2.0.2 起也支持直接传入配置数组来创建缓存对象,见 PageCache.php。

Cookie 与 Header 的缓存:cacheCookies / cacheHeaders

  • cacheCookies(默认 false):是否缓存全部 Cookie,或传一个 Cookie 名称数组指定白名单。缓存 Cookie 需极其谨慎,可能把敏感或私有数据泄露给不该看到它的用户;
  • cacheHeaders(默认 true):是否缓存全部 HTTP 响应头,或传一个区分大小写的 Header 名称数组指定白名单。若 Header 含敏感信息,应只白名单化可缓存的 Header。

这两个特性自 2.0.4 引入,存储与恢复逻辑分别在 insertResponseCookieCollectionIntoData() / insertResponseHeaderCollectionIntoData() 与 restoreResponse() 中实现。测试 PageCacheTest 用多组用例覆盖了 allCookies、someCookies、noCookies、allHeaders、someHeaders、noHeaders、originalNameHeaders 以及二者组合的全部场景。

视图组件:view

view 指定用于缓存/渲染的视图组件,默认取应用级 Yii::$app->view(在 init() 中赋值,见 PageCache.php)。动态内容(见下文)的占位符替换依赖该视图组件。

缓存键的构成原理

页面缓存的键由 calculateCacheKey() 生成,格式为:

['yii\filters\PageCache', 请求路由(varyByRoute=true 时), ...variations 变体...]

测试 testCalculateCacheKey() 给出了明确的键形:

  • 设置 variations => ['ru'] 且路由为 test 时,键为 ['yii\filters\PageCache', 'test', 'ru'];
  • 未设置 variations 时,键为 ['yii\filters\PageCache', 'test']。

此外,写入缓存的每条数据都带有 cacheVersion 字段(常量 PAGE_CACHE_VERSION = 1),用于在缓存数据结构不兼容时自动淘汰旧版本数据(PageCache.php)。

底层工作流程:缓存命中与未命中

PageCache 是动作过滤器,其核心逻辑在 beforeAction() 与 cacheResponse() 中:

  1. 缓存未命中(beforeAction() 返回 true,PageCache.php):

    • 将当前过滤器注册为动态内容感知对象(pushDynamicContent);
    • 开启输出缓冲 ob_start();
    • 在 Response::EVENT_AFTER_SEND 事件上挂接 cacheResponse;
    • action 正常执行并渲染页面;
    • 响应发送完毕后,cacheResponse() 捕获缓冲内容,连同响应格式、版本、状态码、状态文本、Header、Cookie 及动态内容占位符一起存入缓存,键为 calculateCacheKey(),过期时间为 duration,并携带 dependency。
  2. 缓存命中(beforeAction() 返回 false):

    • 调用 restoreResponse()(PageCache.php)从缓存数据中恢复 format、version、statusCode、statusText、content 等响应属性,并合并 Header 与 Cookie;
    • 若存在动态内容占位符,则重新执行动态 PHP 代码替换占位符;
    • 由于 beforeAction() 返回 false,action 主体不再执行,页面直接由缓存输出。

值得一提的扩展点:自 2.0.11 起可重写 beforeCacheResponse()(返回 false 取消本次缓存,返回数组则额外存入自定义数据)与 afterRestoreResponse()(恢复完成后、响应发送前的收尾钩子),见 PageCache.php。

页面缓存与片段缓存的异同

页面缓存与片段缓存非常相似,都支持 duration、dependencies、variations、enabled 等选项。二者的核心区别在于实现形态:

维度 页面缓存 片段缓存
实现载体 动作过滤器(yii\filters\PageCache) 小部件 Widget(yii\widgets\FragmentCache)
缓存粒度 整个页面 页面中的某个片段
使用位置 控制器 behaviors() 视图模板(beginCache() / endCache())
生效时机 action 执行前拦截 视图渲染过程中

页面缓存可以与片段缓存、动态内容组合使用。在页面缓存内部使用片段缓存时,内层片段有自己的缓存键与失效策略;即使外层页面缓存有效,内层动态内容(View::renderDynamic() 注入的 PHP 代码片段)也会在每个请求重新执行。这一机制建立在 yii\base\DynamicContentAwareInterface 与 DynamicContentAwareTrait(自 2.0.14 起)之上,PageCache 通过 DynamicContentAwareTrait 实现占位符的注册与替换:缓存时以占位符代替动态内容,恢复缓存时重新执行占位符对应的 PHP 语句,详见 PageCache::restoreResponse() 与 updateDynamicContent()。

适用前提与实战注意事项

  • 只缓存 GET 类请求:页面缓存会把首次生成的响应整体保存并复用,对包含表单提交、写操作、个性化数据的页面需谨慎,可通过 enabled 按请求类型开关;
  • 敏感数据隔离:默认不缓存 Cookie(cacheCookies => false),但会缓存 Header(cacheHeaders => true);凡涉及用户私有数据的场景,应显式配置白名单或关闭对应开关;
  • 多语言站点:务必通过 variations 按语言区分缓存,避免不同语言用户看到彼此的缓存页面;
  • 频繁变化的数据:用 dependency(如 DbDependency)代替短 duration,在数据变化时即时失效,兼顾新鲜度与命中率;
  • duration => 0 与依赖配合:永不过期缓存必须配合可靠依赖,否则内容无法更新;
  • 运行环境要求:本框架面向 PHP 应用,页面缓存依赖服务器端会话与缓存组件(如 caching-data.md 所述的文件、数据库、Memcache、Redis 等缓存后端),生产环境需先配置好 cache 应用组件。

源码与测试验证路径

如果你想深入验证以上结论,可以按如下路径继续阅读当前仓库:

登录后查看全文
yii2