Cannot modify header information 报错排查:output_buffering 到底该设 On 还是 4096
一、报错原文自己说了什么
打开 Apache 的错误日志,PHP 抛出的这条警告通常会完整写清"输出是从哪开始的":
PHP Warning: Cannot modify header information - headers already sent by
(output started at /var/www/html/login.php:1) in /var/www/html/login.php on line 23
php.net 手册的正文开门见山:header() 必须在任何实际输出被发送之前调用(原文 "Remember that header() must be called before any actual output is sent"),并且把"输出"的三种来源列了出来:普通 HTML 标签、文件里的空行、以及来自 PHP 的输出。它还专门点了一句非常常见的场景 —— 读一段带 include、require 或其它文件访问函数的代码时,发现那些文件在 header() 之前输出了空格或空行;"使用单个 PHP/HTML 混合文件时也存在同样的问题"。
而官方给出的反例,注释里就直接写着 "This will give an error. Note the output above, which is before the header() call":
<?php
/* 上面这行注释之前如果有任何空白/输出,这里就会报错 */
header('Location: http://www.example.com/');
exit;
?>
这里有两个必须理解的点:① 报错行号显示的是 header() 被调用的位置,而括号里的 output started at 文件:行号 才是真正的元凶位置;② 跳转之后必须紧跟 exit,Location 头发出去后脚本还会继续往下跑、继续输出,这是"点了没反应但又下载了半张页面"的成因。

二、四类真实成因,逐个排查
1. BOM:三个不可见字节
把 PHP 文件存成 "UTF-8 with BOM" 时,文件开头会多出 EF BB BF。这三个字节对编辑器不可见,但它们就是输出,会随响应体一起发出,于是所有 header() 调用必然失败。用支持无 BOM 的编辑器另存为一次即可。校验方式很直接:
# Linux/macOS:看前 16 字节,出现 efbbbf 即有 BOM
xxd -l 16 login.php
sed -i '1s/^\xEF\xBB\xBF//' login.php # 批量去 BOM
2. ?> 之后的换行
这是纯 PHP 类文件最常见的坑。手册把"文件里的空行"列为输出来源之一,而 ?> 紧跟的一个回车就是一个空行 —— 它会随每个被 include 的文件累积一次。工程做法是纯 PHP 文件不写闭合标签,从根上避免。
3. 公共文件被提前 include
模板头、页脚、配置里带了一句 echo 或者一段 HTML,就会让后面的 header()/setcookie()/session_start() 全部违规。把"设置响应头"的逻辑集中到一个在任何输出之前就被调用的入口里。
4. 压缩/编码类 output handler 与缓冲顺序冲突
如果开了 zlib.output_compression 之类全站 handler,输出会提前进入发送流程;php.net 明确写了设置任何 output handler 都会自动打开输出缓冲,且若干 handler 之间不能并用(见第五节)。这类"本地正常、线上报错"的问题多出自这里。
三、headers_sent():官方的探测函数与那两个引用参数
手册给出的函数签名是:
function headers_sent(string &$filename = null, int &$line = null): bool
对它的用途,原文的表述很有信息量:一旦 header 块已经发送,你无法再用 header() 追加任何头行,用 headers_sent() 至少能避免拿到与 HTTP 头相关的错误信息;而另一个可选方案就是"使用输出缓冲(Output Buffering)"。
两个引用参数是本页最有价值的细节。手册说明:传入可选的 filename 与 line 后,函数会把输出起始所在的 PHP 源文件名与行号写进这两个变量,并特别强调"它们是为后续使用而传进去的,不要事先赋值"。官方给的完整范例正好是一段防御式跳转:
if (!headers_sent($filename, $linenum)) {
header('Location: http://www.example.com/');
exit;
} else {
echo "Headers already sent in $filename on line $linenum\n" .
"Cannot redirect, for now please click this " .
"href=\"http://www.example.com\">link instead\n";
exit;
}
三句话总结官方定义:返回值方面,没有头被发送返回 false,否则返回 true,别把条件写反;有一个 Note 值得单独记住 —— 如果输出在执行该 PHP 源文件之前就已经开始(例如由 startup error 造成),filename 会被设置为空字符串,此时元凶不在当前文件,要往 auto_prepend_file、扩展加载失败输出等启动阶段去找;另一条 Note 是"只有在使用支持 HTTP 头的 SAPI 时,头才可被访问和输出",纯 CLI 下这套语义不适用。
配套的还有 headers_list()(返回已发送或待发送的头列表)与 header_remove(),排查时用它们能看到头到底带了什么。
四、output_buffering:全站级的开关,值不只是 On/Off
php.net 的 outcontrol.configuration(输出控制 ini 设置)页对这条指令写得非常具体,三句话照抄过来就是完整规则:
- 把该指令设为
"On",可以为所有文件开启输出缓冲; - 想限制缓冲区大小,可以用一个数字(最大允许字节数)代替 "On",例如
output_buffering=4096; - 该指令在 PHP-CLI 下永远是 Off —— 别指望在命令行脚本里靠 ini 得到缓冲行为。
作用域方面,从手册的 ini 汇总表可见 output_buffering 标记为 INI_PERDIR,即只能写在 php.ini、.htaccess、httpd.conf 或 FPM 池配置里,不能用 ini_set() 在运行时改,且改完必须重启 php-fpm/Apache 才生效。
同页还有两条常被一起误配:
implicit_flush:默认 false;置为 true 时,PHP 会要求输出层在每个输出块之后自动 flush,等价于在每次 print、echo、以及每个 HTML 块之后都调一次 flush()。手册的告诫相当直白 —— 在 Web 环境下打开它有严重的性能影响,一般只推荐用于调试目的;并且在 CLI SAPI 下它本来就默认为 true。
output_handler:可把脚本输出重定向到一个函数,例如设为 mb_output_handler() 会透明地把字符编码转换为指定编码。手册强调设置任何 output handler 都会自动开启输出缓冲,并给出两组不能混用的组合:mb_output_handler() 与 ob_iconv_handler() 不能同时使用;ob_gzhandler() 和 zlib.output_compression 不能与 mb_output_handler()、ob_gzhandler()、zlib.output_compression、以及"URL-Rewriter"处理器(涉及 session.use_trans_sid 与 output_add_rewrite_var())中的任意一个并用。另外一条硬性限制:该指令只能填内建函数,要挂自定义函数必须改用 ob_start()。
顺带一句 url_rewriter.tags 默认值是 "form=",而自 PHP 7.1.0 起该设置只影响 output_add_rewrite_var()(7.1 之前它还承担透明会话 ID 改写,那部分已移交 session.trans_sid_tags);url_rewriter.hosts 则从 PHP 7.1.0 起才可用,默认取 $_SERVER['HTTP_HOST']。
五、局部控制:ob_start() 与三个"收尾"函数
不想动服务器配置,就在文件第一行开缓冲。手册的输出控制函数一览(Output Control Functions)给出了完整表,几个易混的函数分别是:
ob_start()— Turn on output buffering(开启缓冲)ob_flush()— Flush(发送)活动缓冲区的内容并保留缓冲区ob_end_flush()— 发送内容并关闭该层缓冲ob_end_clean()— 清空(丢弃)内容并关闭缓冲ob_clean()— 清空当前缓冲区内容但不关闭缓冲flush()— Flush system output buffer(把 PHP 输出层的数据真正交给 Web 服务器)
这组里最容易搞混的是 ob_flush() 与 flush(),前者是 PHP 自己的缓冲区,后者才是把数据推给 Web 服务器;手册在 implicit_flush 的说明里也把"等价于每次输出后调用 flush()"作为 flush 的定义,可作交叉印证。
最小可用写法(适合放在公共入口文件顶部):
<?php
ob_start(); // 之后任意位置调用 header()/setcookie() 都不会再报 headers already sent
header('Content-Type: text/plain; charset=utf-8');
echo str_repeat('x', 4096);
if (!headers_sent($f, $l)) {
header('X-Buffer: ok');
} else {
error_log("output started at $f:$l");
}
ob_end_flush(); // 或 flush() + ob_end_clean(),按是否需要保留缓冲层选择
需要分段流式输出(长任务进度、SSE)时,正确组合是 ob_flush() 后再 flush(),两层都要推,只调其中一个经常表现为"进度条不动"。
六、Location 头的两个坑,手册都写明了
坑一:会话 ID 不会随 Location 传递。手册有一段独立的 Note 明确说:Session ID is not passed with Location header even if session.use_trans_sid is enabled,必须用 SID 常量手工拼进 URL。这解释了为什么开透明会话的站点跳转后掉登录态。
坑二:相对路径要自己拼成绝对 URI。官方给的兼容写法(用 HTTP_HOST + dirname() 组装):
$host = $_SERVER['HTTP_HOST'];
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
$extra = 'mypage.php';
header("Location: http://$host$uri/$extra");
exit;
状态码那行头有讲究。手册说有两个特殊调用的头。第一个是以 HTTP/ 开头的头(大小写不敏感),用来推断要发送的 HTTP 状态码,典型场景是用 Apache 的 ErrorDocument 让 PHP 处理 404。值得注意的是当前文档在这个示例里补了一段"更好的替代写法"注释:相比硬写 header("HTTP/1.1 404 Not Found"),更推荐 header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found")(照顾仍用 HTTP/1.0 的客户端),或者干脆用 http_response_code(404)。
贡献者笔记区一条获得 248 赞的经验正是这个坑:作者在 Apache/2.0.59(Unix)上误加 HTTP/1.1 200 Ok 头,结果多数页面正常,但部分页面被追加了怪内容 —— 页面顶部多出一段 4 位十六进制码(同一页面、同一浏览器时值相同,像校验和),页面底部多出一个 0;改用 SERVER_PROTOCOL 拼接后消失。
301 与 302 靠参数区分,而不是靠头本身。98 赞笔记给的标准写法(用 header() 的第三个参数 $response_code):
header("Location: /foo.php", TRUE, 301); // Moved Permanently
header("Location: /foo.php", TRUE, 302); // Found(不传则默认 302)
header("Location: /foo.php", TRUE, 303); // See Other
header("Location: /foo.php", TRUE, 307); // Temporary Redirect
170 赞的另一条则解决"想告诉用户 5 秒后跳转"的矛盾:既然 header() 前不能有输出,提示文案就没法先打印。方案是改用 refresh 头,头之后再 echo:
<?php
header('refresh:5;url=wherever.php');
echo "You'll be redirected in about 5 secs. If not, click here.";
?>
至于 $replace 参数:手册签名里默认 bool $replace = true,true 会替换同名的前一个头,传 false 才能发多行同名头(典型是多次 Set-Cookie 或 Link 预加载)。
七、disable_functions:另一种"让它发不出去"
与安全相关的 php.ini 指令 disable_functions 也属于"修改头/执行函数失败"类问题的高频元凶。php.net 的 core ini 汇总表明确标注:disable_functions 默认值为空字符串,作用域是 INI_SYSTEM only —— 只能写在 php.ini 里,.htaccess 和 FPM 池以外的 per-dir 配置对它无效;与之相邻的 disable_classes 是 php.ini only,且自 PHP 8.5.0 起已被移除。
写法是逗号分隔的函数名列表:
; /etc/php/8.3/fpm/php.ini
disable_functions = "exec,passthru,shell_exec,system,proc_open,popen,curl_multi_exec,show_source"
被禁用后调用会报 Warning: system() has been disabled for security reasons;用 php -r "var_dump(function_exists('system'));" 可确认是否真的被禁。改完 ini 必须重启 php-fpm 或 Apache,否则不生效。
八、排查顺序(按这个走,不要乱试)
- 先读警告括号里的
output started at X:行号,定位到真正开始输出的文件,而不是只盯着报错那一行。 - 用
headers_sent($f, $l)在文件最顶端打印一次,确认污染发生在当前文件还是启动阶段($f为空串 → 往 BOM 之外的 auto_prepend_file、扩展加载输出查)。 xxd -l 16检查 BOM;去掉?>之后的换行,或干脆省略闭合标签。- 临时验证:文件第一行加
ob_start()。报错消失 → 确属顺序问题;仍报错 → 检查是不是 handler/压缩配置冲突。 - 查
output_buffering(INI_PERDIR,改了要重启)、implicit_flush(生产必须 false)、zlib.output_compression与自定义 handler 是否并用。 - 别忘了
setcookie()、session_start()、header_remove()、http_response_code()受同一条"任何输出之前"规则约束,要一起改。 - 确认部署链:Git 换行符(
core.autocrlf)、FTP 文本模式、打包解压都可能悄悄引入空白输出 —— 这是"本地好好的,线上报错"最常见的外部原因。
九、常见问题
Q:能不能靠关闭 display_errors 把这条警告"解决"掉?
A:不能。生产环境本就不该回显错误,但警告消失不代表逻辑正确:头已经发出,你的 Location/Set-Cookie 事实上没生效,用户会被卡在原页面。这条开关只改变可见性,不改变协议层的既成事实。
Q:output_buffering 设成 4096 和 On 有什么区别?
A:手册的定义是 —— "On" 为所有文件开启缓冲;填数字则是限制缓冲区大小(最大允许字节数)。达到上限时 PHP 会把缓冲内容发出去,因此小缓冲等于"分段发送",与"一次性延迟到脚本结束"在语义上并不相同。
Q:命令行脚本里为什么 ob_start 表现不一样?
A:手册明确 output_buffering 在 PHP-CLI 下恒为 Off,且 implicit_flush 在 CLI SAPI 下默认为 true。CLI 也没有 HTTP 响应头这一层("Headers will only be accessible and output when a SAPI that supports them is in use"),所以这里讨论的整套 header()/headers_sent() 语义在 CLI 下不适用。
Q:Nginx + PHP-FPM 下还能用 .htaccess 开缓冲吗?
A:output_buffering 是 INI_PERDIR,可以在 .htaccess(Apache)或 php_admin_value / FPM 池配置里设;Nginx 本身没有 per-dir 概念,须写在 FPM 池。Apache 侧还要确认 AllowOverride Options 允许 php_value 覆盖,否则指令被忽略而报错照旧。
