PHP 模板輸出空行/空白終極解決方案：BOM 頭、ob 緩衝區與 UTF-8 編碼規範

PHP 模板輸出莫名其妙出現空行、頂部空白、甚至導致 header() 失效、Session 無法啟動，是開發者常遇到的「玄學」問題。根因通常集中在三點：UTF-8 BOM 頭、包含文件多餘換行、輸出緩衝區控制不當。本文提供系統性排查與徹底解決方案。

現象與根因對照表

方案一：徹底清除 BOM（推薦根治）

1. 使用 VS Code / PhpStorm / Notepad++ / UltraEdit 另存為 UTF-8 without BOM（或「UTF-8 No BOM」）
2. 項目統一規範：所有 PHP/HTML/JS/CSS 文件均不帶 BOM
3. 批量檢查命令（Linux/Mac）：
   grep -r $'\xEF\xBB\xBF' . --include="*.php" --include="*.html"

方案二：輸出緩衝區控制（ob_start 兜底）

在入口文件最頂部（<?php 之前無任何字符）啟用緩衝，模板輸出前清理，輸出後刷新：

<?php
// 入口文件最頂部
ob_start();

// 業務邏輯...
require 'header.php'; // 可能含 BOM/空白

// 模板輸出前：清理之前的所有輸出（含 BOM、空白）
ob_end_clean();

// 正式模板輸出
require 'template.php';

// 輸出結束：刷新緩衝區到瀏覽器
ob_end_flush();
?>

原理：ob_start() 捕獲所有輸出；ob_end_clean() 丟棄捕獲內容並關閉緩衝，此後輸出直接發送給瀏覽器，實現「切除頭部雜質」。

方案三：HTML 標頭順序規範（防 IE 渲染異常）

<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="zh-CN" />
    <title>頁面標題</title>
    <!-- 其他 meta -->
</head>

關鍵：<meta charset> 必須在 <title> 之前，否則 IE 可能誤判編碼導致空白頁。

進階：自動化檢測腳本

<?php
// 部署前執行，掃描項目 BOM 文件
$files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator(__DIR__));
foreach ($files as $file) {
    if ($file->isFile() && in_array($file->getExtension(), ['php', 'html', 'css', 'js'])) {
        $content = file_get_contents($file->getPathname());
        if (str_starts_with($content, "\xEF\xBB\xBF")) {
            echo "BOM detected: " . $file->getPathname() . PHP_EOL;
        }
    }
}
?>

總結檢查清單

• [ ] 所有文件保存為 UTF-8 無 BOM
• [ ] 入口文件 <?php 前無任何字符（含空行）
• [ ] 關鍵入口加入 ob_start() / ob_end_clean() 兜底
• [ ] HTML <meta charset> 放在 <title> 前
• [ ] 關閉 PHP 短標籤 short_open_tag=Off 避免衝突

「空白輸出」本質上是「過早輸出」。統一編碼規範 + 緩衝區兜底 = 徹底告別空行困擾。