萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 出現空白頁面 (白屏) 終極排查指南

現象

瀏覽器訪問 PHP 頁面,完全空白,無任何輸出,查看頁面源碼也為空。這通常意味著 PHP 引擎遇到致命錯誤並終止執行,且錯誤顯示被關閉。

核心排查步驟 (按優先級)

1. 開啟錯誤報告 (最關鍵)

在腳本**最頂部** (

<?php
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL); // PHP 8.0+ 可用 E_ALL | E_STRICT
?>

或修改 php.ini:

display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /var/log/php_errors.log

生產環境請關閉 display_errors,僅記錄日志!

2. 檢查 Web 服務器錯誤日志

  • Apache: /var/log/apache2/error.log 或 /var/log/httpd/error_log
  • Nginx: /var/log/nginx/error.log (FastCGI 錯誤常在這裡)
  • PHP-FPM: /usr/local/php/var/log/php-fpm.log 或配置的 error_log 路徑

搜索關鍵字:PHP Fatal error、PHP Parse error、500 Internal Server Error。

3. 常見導致白屏的代碼錯誤類型

類型典型原因示例解決
語法錯誤漏分號、括號不匹配、關鍵字拼寫錯誤$a = 1 // 缺分號IDE 實時檢查、php -l file.php 語法檢查
致命錯誤調用未定義函數/類、內存耗盡、執行超時、require 失敗Call to undefined function foo()檢查拼寫、引入文件、擴展安裝、調大 memory_limit/max_execution_time
邏輯錯誤導致無輸出條件分支全不滿足、循環不進入、輸出被緩存未刷新if($x>10) echo 'hi'; // $x=5添加默認輸出、ob_end_flush()、Xdebug 斷點調試
Header 已發送輸出內容前發送 Header (重定向、Session、Cookie)<?php echo ' '; header('Location:...');確保 Header 前無任何輸出 (含 BOM、空白)、使用輸出緩存 ob_start()
濫用錯誤抑制符 @@include('missing.php') 隱藏致命錯誤包含文件有語法錯誤但被 @ 抑制移除 @,修復底層錯誤;生產環境用自定義錯誤處理器

4. 檢查文件編碼與 BOM

  • 文件必須保存為 **UTF-8 無 BOM** 編碼。BOM (EF BB BF) 會導致 header()、session_start() 失效並輸出空白。
  • 編輯器設置:VS Code (右下角編碼選 UTF-8)、PhpStorm (File → File Encoding → UTF-8)、Notepad++ (編碼 → 轉為 UTF-8 無 BOM)。

5. 權限問題

  • PHP 進程用戶 (www-data, apache, php-fpm user) 對腳本文件、目錄、上傳目錄、緩存目錄、日志目錄需有讀/寫/執行權限。
  • SELinux/AppArmor 可能阻止訪問,檢查 audit.log 或暫時設為 Permissive 模式測試。

6. PHP-FPM / Apache 模塊崩潰

  • 查看系統日志 dmesg | grep -i php 或 journalctl -u php-fpm,看是否有 Segfault (段錯誤)。
  • 可能原因:擴展不兼容 (如 xdebug 版本不匹配)、OpCache 損壞 (重啟 php-fpm)、代碼觸發 Zend Engine Bug。

7. 輸出緩存問題

<?php
ob_start(); // 腳本開頭開啟緩存
// ... 業務邏輯 ...
ob_end_flush(); // 結束時刷新輸出
?>

某些框架/服務器配置默認開啟輸出緩存,若腳本中途 exit/die 未刷新緩存,導致白屏。

調試工具推薦

  1. Xdebug:斷點、步進、變量檢查、堆棧追蹤、性能分析。IDE 整合 (PhpStorm, VS Code + PHP Debug)。
  2. VarDumper (Symfony):dump($var) 替代 var_dump,美觀、可折疊、不中斷執行。
  3. Laravel Telescope / Clockwork:請求監控、查詢、異常、隊列可視化。
  4. 命令行測試:php -l file.php (語法檢查)、php file.php (直接運行 CLI 模式)。

預防白屏清單 (部署前自檢)

  • [ ] 代碼通過 php -l 語法檢查
  • [ ] 關鍵路徑有 try/catch 並記錄日志
  • [ ] 生產環境 display_errors = Off, log_errors = On
  • [ ] 無 BOM 編碼
  • [ ] 文件/目錄權限正確
  • [ ] 依賴擴展已安裝並啟用
  • [ ] OpCache 生產環境優化配置 (opcache.validate_timestamps=0 等)
  • [ ] 監控告警配置 (日志錯誤率、5xx 比率、內存/CPU)

結語

白屏本質是「錯誤被吞沒」。建立「開啟報告 → 看日志 → 定位行 → 修復代碼 → 驗證 → 完善預防」的肌肉記憶,配合現代調試工具,能將排查時間從小時級壓縮到分鐘級。

copyright © 萬盛學電腦網 all rights reserved