解決 setcookie "headers already sent" 錯誤的根因與方案

Warning: Cannot modify header information - headers already sent by... 是 PHP 開發者最常遇到的錯誤之一。本文深度解析根因並提供多層次解決方案。

根本原因

HTTP 協議規定：響應頭必須在響應體之前發送，且頭部發送後不可修改。任何在 setcookie()/header()/session_start() 前的輸出（包括空白字符、BOM、錯誤信息、HTML）都會導致頭部提前發送。

常見觸發場景

1. <?php 前有空行/空格/BOM
2. 包含文件中有輸出（include/require 文件末尾有 ?> 後空行）
3. 錯誤/警告輸出（如 Notice、Deprecated） 4. echo/print/var_dump 在頭部函數前調用 5. HTML 代碼混雜在 PHP 邏輯之前

方案一：輸出緩衝控制（推薦、治本）

php.ini 全局開啟

output_buffering = On
; 或設置具體大小(字節)，如 4096
output_buffering = 4096

重啟 PHP-FPM/Apache 生效。所有腳本自動緩衝，頭部函數可在任意位置調用（直到緩衝區刷新）。

代碼級開啟

<?php
ob_start(); // 腳本最頂部，任何輸出前
// ... 邏輯代碼 ...
setcookie('name', 'value'); // 即使前面有 echo 也可工作
ob_end_flush(); // 可選，腳本結束自動刷新
?>

方案二：代碼規範預防（最佳實踐）

1. 純 PHP 文件省略閉合標籤?>，防止末尾空白輸出
2. 嚴格分離邏輯與輸出：先處理所有邏輯（含 setcookie/header），再統一輸出 HTML 3. 入口文件統一管理：框架單一入口天然解決此問題 4. 編碼統一 UTF-8 無 BOM：編輯器設置保存為「UTF-8 without BOM」 5. 錯誤處理：生產環境關閉 display_errors，啟用 error_log

<?php
// 登錄設置 Cookie 後重定向，避免同頁輸出衝突
setcookie('auth', $token, time()+3600, '/', '', true, true);
header('Location: /dashboard.php');
exit;
?>

<?php
// 臨時添加在報錯行前，輸出已發送頭部信息
headers_list(); // 返回已發送/準備發送的頭部數組
debug_print_backtrace(); // 追溯調用堆棧
?>