esi是基于http标准的边缘缓存协议，用于实现页面分片缓存：主页面与动态区块（如未读消息）可设不同缓存策略，需网关缓存支持、响应头声明esi-enabled、twig中使用render_esi()。
Symfony 的 ESI（Edge Side Includes）机制，是用来解决“整页缓存但局部动态”这一经典难题的。它不改变你应用的逻辑结构，而是让网关缓存（如 Varnish、Symfony 内置反向代理）能分别缓存页面的不同片段，并按需组装响应。
ESI 是什么，为什么需要它
普通 HTTP 缓存对整个响应生效：要么全缓存，要么全不缓存。但真实页面常含混合内容——比如首页主体可缓存 1 小时，用户头像区域需每 5 分钟刷新，登录状态栏甚至要实时渲染。ESI 允许你在 HTML 中插入特殊标签，告诉缓存层：“这部分请单独请求、单独缓存、单独过期”。它不是 Symfony 独创，而是基于 HTTP 标准的边缘缓存协议。
启用 ESI 的前提条件
必须满足三个基础环节，缺一不可：
- 使用网关缓存：Symfony 自带的反向代理（
SymfonyComponentHttpKernelHttpCacheHttpCache）或外部服务（Varnish、Cloudflare）必须启用并配置为支持 ESI；仅靠浏览器或中间 CDN 默认不处理 ESI 标签 - 响应头明确声明支持：控制器返回的 Response 必须设置
X-Symfony-Response-Header: esi-enabled（Symfony 5.4+ 可自动推断），且响应状态码为 200 - 模板中使用 ESI 标签：Twig 模板里用
{{ render_esi() }}替代{{ render() }}，触发子请求走 ESI 流程
在 Twig 中嵌入 ESI 片段
假设你有一个实时显示用户未读消息数的侧边栏，希望独立缓存 60 秒：
第一步，在控制器中定义一个专用动作：
// src/Controller/WidgetController.phppublic function unreadCount(): Response
{
return $this->render('widget/unread_count.html.twig', [
'count' => $this->getUnreadMessageCount(),
]);
}
第二步，在主模板中调用 ESI 渲染（不是普通 render）：
{# templates/base.html.twig #}{{ render_esi(controller('App\Controller\WidgetController::unreadCount')) }}
第三步，确保该动作返回的响应设置了合理的缓存策略：
public function unreadCount(): Response{
$response = $this->render('widget/unread_count.html.twig', [...]);
$response->setSharedMaxAge(60); // 关键：控制 ESI 片段缓存时长
return $response;
}
调试与验证 ESI 是否生效
最直接的方式是查看最终响应的 HTML 源码和响应头：
- 若 ESI 正常工作，源码中会看到类似
<include src="/widget/unread-count"></include>的原始标签（由网关缓存解析，非浏览器渲染） - 主响应头应包含
X-Symfony-Cache: GET /: stale, invalid，而 ESI 子请求响应头中应有X-Symfony-Cache: GET /widget/unread-count: fresh - 禁用网关缓存后，
render_esi()会自动退化为普通render()，页面仍可运行但失去分片缓存效果
