Symfony 6 ESI组件无法缓存大型菜单问题求助

• 先确认ESI是否真的被触发

  • 查看响应头里是否存在Surrogate-Control: content="ESI/1.0"，没有的话说明ESI未被解析。此时需检查Web服务器配置：Nginx要添加proxy_set_header Surrogate-Capabilities "app=ESI/1.0";，Apache需启用mod_esi模块。
  • 打开Symfony Profiler的HTTP标签，确认菜单控制器的请求是否标记为ESI subrequest。如果没有，大概率是模板里写错了渲染函数——别把render_esi误写成render，后者只会直接渲染内容，不会生成ESI标签。

• 核对缓存注解与响应头的正确性

  • 菜单控制器的#[Cache]注解需明确设置public: true，仅在响应中调用setPublic()可能不够稳妥，示例代码：

    #[Cache(smaxage: 60, public: true)]
    public function menuAction(): Response
    {
        $response = $this->render('menu.html.twig', [
            'timestamp' => time(),
        ]);
        $response->setPublic();
        return $response;
    }
    

  • 检查控制器内是否有代码覆盖缓存头，比如误调用$response->setMaxAge(0)或$response->setPrivate()，这些操作会直接冲掉你的缓存配置。

• 确认Fragment配置无遗漏

  • framework.yaml中除开启esi: true，还需正确配置fragments路径：

    framework:
        esi: true
        fragments: { path: /_fragment }
    

  • 防火墙需允许匿名访问/_fragment路径，否则ESI请求会被重定向到登录页，缓存自然无法生效。

• 检查缓存池配置是否合理

  • 避免使用cache.adapter.array作为默认缓存池——它是内存级缓存，重启服务后就会失效，完全不适合生产环境。建议替换为文件或Redis适配器：

    framework:
        cache:
            app: cache.adapter.filesystem
            system: cache.adapter.filesystem
    

• 别忽略调试模式的影响

  • 若开启APP_DEBUG=1，Symfony会自动禁用所有缓存（包括ESI）。测试时可将APP_DEBUG设为0，或在调试模式下强制给缓存池设置生命周期：

    framework:
        cache:
            pools:
                cache.app:
                    adapter: cache.adapter.filesystem
                    default_lifetime: 3600
    

• 最后验证Web服务器的ESI解析能力

  • Nginx除设置Surrogate-Capabilities，还要确保proxy_pass时传递必要请求头，示例配置：

    location / {
        proxy_pass http://your-php-fpm-address;
        proxy_set_header Host $host;
        proxy_set_header Surrogate-Capabilities "app=ESI/1.0";
        proxy_ignore_headers Cache-Control;
    }
    

  • Apache需启用mod_proxy、mod_proxy_http和mod_esi模块，虚拟主机配置添加：

    ProxyPass / http://127.0.0.1:8000/
    ProxyPassReverse / http://127.0.0.1:8000/
    ProxyESI on
    

内容的提问来源于stack exchange，提问作者Jonathan Clark