PHP UTF-8 BOM 導致空白頁、Session 失效完整解析與解決方案

什麼是 BOM？

Byte Order Mark (BOM) 是 UTF-8 檔案開頭的三個隱藏位元組 `EF BB BF`，用於告知編輯器檔案編碼。PHP 不會忽略 BOM，會將其視為輸出內容的一部分，導致嚴重副作用。

三大經典症狀

1. 頁面頂端莫名空白：HTML 輸出前已送出 3 個位元組，CSS `margin-top:0` 無效。
2. Cookie / Session 完全失效：`setcookie()`、`session_start()` 需在輸出前呼叫，BOM 導致「Header already sent」警告。
3. API 回傳 JSON 解析失敗：回應開頭多出 BOM，`JSON.parse()` 拋錯。

檢測方法

命令列快速掃描

# Linux/macOS
grep -rl $'\xEF\xBB\xBF' --include="*.php" .

# Windows PowerShell
Get-ChildItem -Recurse -Filter *.php | Where-Object { (Get-Content -Raw -Encoding Byte $_)[0..2] -eq 0xEF,0xBB,0xBF }

PHP 掃描腳本 (可自動移除)

<?php
// scan_bom.php
$dir = __DIR__;
$removed = 0;
$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir));
foreach ($it as $file) {
    if ($file->isFile() && $file->getExtension() === 'php') {
        $content = file_get_contents($file->getPathname());
        if (substr($content, 0, 3) === "\xEF\xBB\xBF") {
            file_put_contents($file->getPathname(), substr($content, 3));
            echo "已移除 BOM: {$file->getPathname()}\n";
            $removed++;
        }
    }
}
echo "完成，共處理 $removed 個檔案。\n";

編輯器設定：永久杜絕 BOM

緊急修復：已上線專案無法重新部署時

在入口檔案 `index.php` 最頂端插入（不推薦長期使用，治標不治本）：

<?php
// 必須在任何輸出之前
if (isset($_SERVER['SCRIPT_FILENAME'])) {
    $content = file_get_contents($_SERVER['SCRIPT_FILENAME']);
    if (substr($content, 0, 3) === "\xEF\xBB\xBF") {
        // 僅移除當前腳本 BOM，無法修正 include 的檔案
    }
}

最佳實務總結

1. 團隊統一使用 **不加 BOM 的 UTF-8** 編碼。
2. Git 設定 `.gitattributes`：`*.php text eol=lf` 強制 LF 換行、無 BOM。
3. CI/CD 流程加入 BOM 檢測步驟，失敗即阻擋部署。
4. 所有 `include`/`require` 檔案**嚴禁**在 `

原文摘自 cyuyan112233 專欄