PHP SSE 实时进度流怎么做：EventSource、心跳与缓冲边界

后台导入、报表生成这类耗时长的任务，如果一直等到 PHP 脚本完全执行结束才返回结果，页面只会一直显示转圈状态。更合适的做法是让 PHP 输出 Server-Sent Events（SSE），浏览器用 EventSource 持续接收进度；但只写几行基础的 flush() 并不保证用户马上看到内容，事件格式、PHP 输出缓冲、反向代理和浏览器缓冲都要一起核对调整。

EventSource 适合单向进度通知

SSE 是服务器向浏览器推送文本事件的长连接方式，客户端不需要反复轮询接口。它特别适合导入、导出、构建和报表这类任务：页面先创建后台任务，再打开一个只读的进度查询地址；服务器持续发送百分比、当前执行阶段和最终完成状态。如果需要双向高频通信的场景，还是要评估 WebSocket 方案更合适。

浏览器端最小写法如下，收到命名事件后更新进度条；连接异常时先保留当前已拿到的进度状态，避免把一次短暂的网络抖动误显示成任务失败。

const source = new EventSource('/progress.php?job=job-42');

source.addEventListener('progress', (event) => {
  const item = JSON.parse(event.data);
  progressBar.value = item.percent;
  statusText.textContent = `${item.percent}% ${item.message}`;
});

source.addEventListener('done', () => {
  statusText.textContent = '已完成';
  source.close();
});

source.onerror = () => {
  statusText.textContent = '连接暂时中断，浏览器将尝试重连';
};

PHP 输出事件时要守住格式边界

服务端必须先声明 Content-Type: text/event-stream，然后按对应字段规则输出。一条事件可以包含 event、id 和 data；事件块结束时要再输出一个空行。JSON 内容放在 data: 后面，换行也要严格按 SSE 规则处理。

 0) {
        ob_flush();
    }
    flush();
}

sendEvent('progress', 1, ['percent' => 20, 'message' => '正在读取数据']);
sendEvent('progress', 2, ['percent' => 80, 'message' => '正在写入结果']);
sendEvent('done', 3, ['percent' => 100, 'message' => '任务完成']);

示例里的 X-Accel-Buffering 只对使用 Nginx 的场景有意义，其他网关服务要用对应适配的配置。不要把“已经调用了 flush”当成“浏览器已经收到内容并显示”的证明。

心跳和 Last-Event-ID 解决两类不同问题

任务可能几十秒都没有新进度更新，此时可以发送注释行保持连接活跃：

echo ": keep-alive\n\n";
flush();

注释内容不会触发 message 事件，但能让中间层看到连接仍有数据流动，不会主动断开。真正的进度事件则使用递增的 id 标记。浏览器重连时可能带上 Last-Event-ID，服务端可以据此从任务持久化记录中补发尚未确认的进度；如果任务状态只存在内存里，断线续接就不能当成可靠的自动恢复方案。

看不到实时内容时按三层缓冲排查

PHP 官方文档明确提醒，flush() 不能覆盖所有 Web 服务器和客户端缓冲场景。排查时先用浏览器 Network 面板查看响应是否分段到达，再检查代理配置，最后才调整 PHP 的输出缓冲；否则很容易在错误的层面反复加空格或者重复调用刷新函数，做很多无用功。

上线前的最小验收清单

• 事件流响应状态为 200，类型为 text/event-stream，没有被额外缓存。
• 每个事件都能在空行处正确分隔，JSON 能被浏览器正常解析，完成事件会主动关闭连接。
• 空闲阶段有合理心跳，长任务超时、取消和权限失败都有明确事件提示或对应 HTTP 响应。
• 用 Network、代理日志和 PHP 日志分别确认“已写出、已转发、已收到”三个环节的结果符合预期。

常见问题

PHP SSE 能代替 WebSocket 吗？

只能在服务器单向推送的场景下替代。需要浏览器持续向服务器发送消息、多房间广播或双向实时协作时，应重新评估 WebSocket 或其他更适配的方案。

为什么调用 flush 后浏览器仍然不动？

PHP 刷新操作只处理它能控制的缓冲，PHP-FPM、反向代理、压缩层和浏览器都可能继续聚合数据再统一返回。先看 Network 的响应增量情况，再逐层关闭或调整缓冲配置。

EventSource 断线会自动恢复进度吗？

它可以尝试自动重连，但是否能恢复业务进度取决于服务端是否持久化事件 ID，并根据 Last-Event-ID 补发记录。自动重连不等于自带可靠消息队列的能力。

总结

PHP SSE 的关键不是在循环里反复把结果 echo 出去，而是把事件格式、心跳、事件 ID 和多层缓冲这些环节一起纳入设计。先用一个可观察的进度接口跑通流程，再在代理和异常恢复路径上做完整验收，才能让“实时”从日志里的假象变成浏览器里可见的增量更新。