PHP需绕过框架直接输出文件流：清空缓冲、设200状态及Content-Type/Length/Disposition头（中文名用RFC5987编码）、readfile()输出、exit终止；注意open_basedir权限、无BOM空行、禁用session与输出缓冲。
PHP 直接输出文件流给小程序（不跳转、不重定向）
小程序的 downloadFile API 要求后端返回标准的文件响应（200 + 正确 Content-Type + Content-Disposition），不能是 302 跳转或 HTML 页面。PHP 必须绕过框架路由/模板渲染，直接输出二进制流并终止脚本。
- 务必在输出前调用
ob_end_clean()清空所有已缓冲内容，否则会混入 HTML 或空白字符导致小程序解析失败 - 设置三类关键 header：
Content-Type（根据文件扩展名推断，如application/pdf）、Content-Length（用filesize()精确计算）、Content-Disposition: attachment; filename="xxx"（注意 filename 不带路径，且中文需 UTF-8 编码 + RFC5987 格式） - 用
readfile()输出（适合中小文件），或fopen()+fpassthru()（大文件更省内存），禁止 echo 文件内容 - 最后必须调用
exit或die，防止后续代码输出干扰流
处理中文文件名兼容 iOS 微信小程序
iOS 微信对 Content-Disposition 的中文 filename 支持极差，直接写 UTF-8 字符串大概率被截断或乱码。必须按 RFC5987 规范编码：
Content-Disposition: attachment; filename="filename.pdf"; filename*=UTF-8''%E6%96%87%E4%BB%B6%E5%90%8D.pdf
- PHP 中可用
rawurlencode()对原始文件名 UTF-8 编码，再拼接filename*=UTF-8''前缀 - 不要同时设置
filename和filename*，iOS 只认后者；Android 多数只认前者，所以建议两个都设（前者用 ASCII 文件名兜底） - 示例代码片段：
header('Content-Disposition: attachment; filename="' . basename($safe_name) . '"; filename*=UTF-8\'\'' . rawurlencode($original_name));
避免 open_basedir 或权限导致的 readfile 失败
小程序下载接口常因 PHP 配置限制报错：readfile(): open_basedir restriction in effect 或 failed to open stream: Permission denied。
- 确认文件路径在
open_basedir白名单内（如/var/www/uploads/），不要用../跳出根目录 - 文件必须可被 Web 用户（如 www-data）读取，检查
ls -l权限，常见错误是上传后权限为 600（仅属主可读） - 不要用
file_get_contents()加载大文件到内存，极易 OOM；改用readfile()或分块fread()+echo - 若文件存在但返回空响应，用
error_log('size: ' . filesize($path), 3, '/tmp/download.log')排查是否路径错误或权限不足
与 ThinkPHP/Laravel 等框架共存时的注意事项
框架默认会拦截请求并走路由+中间件，容易在响应头里塞入 Cache-Control、X-Powered-By 等干扰字段，或提前开启 session 导致 header 发送失败。
立即学习“PHP免费学习笔记（深入）”；
- 将下载逻辑放在独立 PHP 脚本（如
/api/download.php），绕过框架入口，避免任何自动 header 注入 - 若必须集成进框架，ThinkPHP 要调用
response()->send()并禁用 layout；Laravel 需用Response::stream()并手动 setStatusCode(200) - 确保 session 未启动——小程序下载无需 session，且
session_start()会触发 cookie header，破坏文件流 - 禁用所有输出缓冲相关中间件（如压缩、调试工具栏）
