FrankenPHP 高效服务大文件X-Sendfile 与 X-Accel-Redirect 完整配置指南【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp导读本文讲解 FrankenPHP 如何把发送大型静态文件这一职责从 PHP 进程委托给底层 Web 服务器Caddy执行同时保留 PHP 代码对访问控制、统计、自定义响应头等逻辑的完全掌控。读完本文你将掌握在 Caddyfile 中启用X-Accel-Redirect委托机制的完整配置学会在纯 PHP 应用与 Symfony HttpFoundation 系项目Symfony、Laravel、Drupal 等中正确发出委托请求头并理解该机制与 Caddyintercept/handle_response模块协同工作的底层原理。为什么需要把静态文件交给 Web 服务器通常静态文件可以直接由 Web 服务器Caddy以零 PHP 开销的方式返回。但在某些业务场景下发送文件之前必须先执行一段 PHP 代码访问控制与鉴权只有登录用户才能下载下载统计、审计日志注入自定义 HTTP 响应头如Content-Disposition、缓存控制如果由 PHP 直接读取并回写文件内容大型静态文件会导致明显问题PHP 进程内存占用过高文件需整体或分块进入 PHP 内存、吞吐量与并发能力下降、请求长时间占用 worker。这与直接使用 Web 服务器相比效率明显偏低。FrankenPHP 的解决方案是先执行 PHP 代码再把发送文件这一步委托回 Web 服务器。PHP 应用只需要在响应中设置一个携带目标文件路径的自定义 HTTP 头剩下的工作磁盘读取、零拷贝发送、Range 请求支持等全部交给 Caddy 完成。这一机制在 Apache 生态中被称为X-Sendfile在 NGINX 生态中被称为X-Accel-RedirectFrankenPHP 对两者均兼容下文配置以X-Accel-Redirect为例。前置假设与目录规划在进入配置之前先明确本文示例的目录约定站点文档根目录为public/对应 Caddyfile 中的root public/需要受保护的静态文件存放在文档根目录之外的private-files/目录中PHP 应用负责鉴权等逻辑文件发送交给 Caddy之所以把文件放在public/之外是为了防止 Web 服务器绕过 PHP 直接把这些文件暴露给客户端——这正是X-Sendfile类机制的核心价值文件路径对客户端不可见且只有经过 PHP 逻辑放行的请求才会被转发到内部文件发送流程。在 Caddyfile 中启用 X-Accel-Redirect以下配置片段来自 docs/x-sendfile.md你需要把它合并进站点块site block中与php_server并列root public/ # ... # Needed for Symfony, Laravel and other projects using the Symfony HttpFoundation component request_header X-Sendfile-Type x-accel-redirect request_header X-Accel-Mapping ../private-files/private-files intercept { accel header X-Accel-Redirect * handle_response accel { root private-files/ rewrite * {resp.header.X-Accel-Redirect} method * GET # Remove the X-Accel-Redirect header set by PHP for increased security header -X-Accel-Redirect file_server } } php_server各指令的作用与工作原理request_header X-Sendfile-Type x-accel-redirect向 PHP 请求上下文注入X-Sendfile-Type请求头值为x-accel-redirect。Symfony HttpFoundation 组件的BinaryFileResponse会读取该请求头决定在响应中使用哪一种委托头。设置后框架生成的响应会自动携带X-Accel-Redirect无需在业务代码里手动拼接头。request_header X-Accel-Mapping ../private-files/private-files这是 NGINX 风格的路径映射规则格式为源路径前缀目标路径前缀。HTTP 客户端PHP 侧看到的文件路径前缀../private-files会被映射为内部实际路径前缀/private-files供后续拦截规则匹配。映射规则的存在使得应用代码可以引用逻辑路径而无需暴露服务器上的真实文件系统布局。intercept { ... }Caddy 的响应拦截模块当上游这里是php_server产生的响应满足指定条件时拦截该响应并交给内部处理流程而不是直接返回给客户端。accel header X-Accel-Redirect *命名匹配器匹配响应头中存在X-Accel-Redirect任意值的响应。只有 PHP 明确设置了该头才会触发委托逻辑。handle_response accel { ... }对匹配的响应执行内部子请求处理root private-files/把内部文件查找根目录切换为private-files/rewrite * {resp.header.X-Accel-Redirect}把内部请求路径改写为 PHP 在X-Accel-Redirect头中给出的相对路径例如file.txtmethod * GET强制内部请求使用 GET 方法发送文件header -X-Accel-Redirect从最终响应中移除 PHP 设置的X-Accel-Redirect头。这一步很关键——既避免把内部路径泄漏给客户端也防止客户端伪造该头直接访问受保护文件安全增强file_server由 Caddy 的静态文件模块执行实际的文件读取与发送纯 PHP 用法手动设置响应头如果不使用框架只需在 PHP 代码中把相对路径相对于private-files/目录设为X-Accel-Redirect响应头的值header(X-Accel-Redirect: file.txt);注意这里的值必须是相对于拦截子请求中root private-files/的相对路径例如file.txt对应实际文件private-files/file.txt。随后 PHP 输出任何内容或空响应体后Caddy 会拦截该响应并代发文件。使用 Symfony HttpFoundation 的项目Symfony、Laravel、Drupal...对于使用 Symfony HttpFoundation 组件的项目框架本身已原生支持该特性详见 docs/symfony.md。在 Caddyfile 完成上述配置后Symfony 会自动确定X-Accel-Redirect头的正确值并添加到响应中业务代码只需要构造一个BinaryFileResponseuse Symfony\Component\HttpFoundation\BinaryFileResponse; BinaryFileResponse::trustXSendfileTypeHeader(); $response new BinaryFileResponse(__DIR__./../private-files/file.txt); // ...关键点trustXSendfileTypeHeader()显式信任X-Sendfile-Type请求头即 Caddyfile 注入的x-accel-redirect允许框架生成委托头BinaryFileResponse构造时的路径__DIR__./../private-files/file.txt与 Caddyfile 中X-Accel-Mapping ../private-files/private-files的映射前缀一致框架据此生成正确的X-Accel-Redirect值Laravel 的StreamedResponse/BinaryFileResponse底层同样基于 HttpFoundation因此 Caddyfile 注释中特别注明该配置Needed for Symfony, Laravel and other projects using the Symfony HttpFoundation component相关机制与验证线索在仓库中可以看到该特性的更多印证docs/symfony.md 给出了与本文 Caddyfile 配置配套的 Symfony 端完整示例适合对照阅读caddy/frankenphp/Caddyfile 展示了 FrankenPHP 默认站点块的写法root、php_server、encode等你可以在此基础上加入intercept块profiles/app/streaming.php 使用了同族的X-Accel-Buffering: no头说明 PHP 与 Caddy 之间通过响应头协商静态文件/流式行为是一套通用约定本文档在其他语言docs/cn/x-sendfile.md、docs/fr/x-sendfile.md 等中有对应译本内容一致可作交叉参考注意事项路径前缀必须一一对应X-Accel-Mapping中的源前缀../private-files必须与BinaryFileResponse传入的路径、或纯 PHP 手写路径的逻辑前缀保持一致否则映射失败会导致文件无法发出。文件必须位于文档根之外被委托的文件应存放在root public/之外如private-files/否则客户端可以直接 URL 访问委托机制将失去访问控制的意义。响应头清理header -X-Accel-Redirect务必保留防止内部路径经响应头泄漏也避免响应头被客户端用于探测。适用场景边界该机制适用于必须跑 PHP 逻辑、但文件体积大的场景纯静态内容仍建议直接由file_server或 CDN 处理让 PHP 完全不参与性能最优。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考