PHP 靜態頁生成完整方案：輸出緩衝控制與 ThinkPHP 實戰

靜態化是高併發場景下降低資料庫壓力、提升響應速度的經典策略。本文系統講解 PHP 原生輸出緩衝（Output Control）生成靜態頁的核心原理與代碼實現，並深度解析 ThinkPHP 框架內建的 buildHtml() 靜態化機制與實戰配置。

核心原理：輸出緩衡三步曲

PHP 提供 ob_start()、ob_get_contents()、ob_end_clean() 三個函數配合實現「捕獲輸出 → 寫入檔案」：

1. ob_start()：開啟輸出緩衝，**之前不能有任何輸出**（含空白、BOM）。
2. 正常 echo、HTML 輸出、模板渲染，內容暫存於緩衝區。
3. ob_get_contents()：獲取緩衝區內容（字串），**必須在 ob_end_clean() 之前**調用。
4. ob_end_clean()：清空緩衝並關閉，返回 true/false。
5. 將獲取的字串用 file_put_contents() 寫入靜態檔案。

原生 PHP 完整範例

<?php
// 1. 開啟緩衝（必須在最頂部，無任何輸出前）
ob_start();

// 2. 業務邏輯與輸出（可包含 include 模板檔）
echo "<html><head><title>靜態頁範例</title></head><body>";
echo "生成時間：" . date('Y-m-d H:i:s');
echo "</body></html>";

// 3. 獲取內容並關閉緩衝
$html = ob_get_contents();
ob_end_clean();

// 4. 寫入檔案
$file = __DIR__ . '/static/page_' . date('Ymd_His') . '.html';
$dir = dirname($file);
if (!is_dir($dir)) mkdir($dir, 0755, true);

if (file_put_contents($file, $html) !== false) {
    echo "靜態頁生成成功：$file";
} else {
    echo "生成失敗，請檢查目錄權限";
}
?>

ThinkPHP (3.x/5.x/6.x) 內建靜態化：buildHtml() 深度解析

ThinkPHP 提供控制器方法 $this->buildHtml()，封裝了緩衝捕獲、模板渲染、檔案寫入、編碼處理全流程。

方法簽名

buildHtml(
    string $htmlFile,      // 生成的靜態檔名（如 'index.html' 或 'list/index.html'）
    string $htmlPath = '', // 靜態檔儲存目錄（預設 HTML_PATH 常數）
    string $templateFile = '', // 指定模板（模塊:操作），空則用當前操作模板
    string $charset = 'utf-8', // 編碼（注意：寫 utf-8 而非 utf-8）
    string $contentType = 'text/html'
): bool

專案配置步驟

1. 入口檔案定義靜態目錄（public/index.php）：

   define('HTML_PATH', __DIR__ . '/../runtime/html'); // 或 ./html 發布到公網目錄

2. 配置靜態副檔名（config.php）：

   'HTML_FILE_SUFFIX' => '.html',

3. 建立模板檔案：view/default/index/index.html（TP3）或 view/index/index.html（TP5/6）。
4. 控制器調用：

   <?php
   namespace app\index\controller;
   use think\Controller;
   
   class Index extends Controller {
       public function index() {
           $this->assign('title', '首頁靜態化演示');
           // 生成靜態頁：檔名 index.html，路徑 HTML_PATH，模板 index:index，編碼 utf-8
           $this->buildHtml('index.html', HTML_PATH, 'index:index', 'utf-8');
           $this->display(); // 同時輸出動態頁（或改為 redirect 到靜態頁）
       }
   }
   ?>

進階：智慧判斷是否重新生成

public function index() {
    $this->assign('data', $this->getData());
    $staticFile = 'article_' . $this->request->param('id') . '.html';
    $staticPath = HTML_PATH . '/article/';
    $fullPath = $staticPath . $staticFile;

    // 僅當靜態檔不存在時生成（可加入過期時間判斷）
    if (!is_file($fullPath)) {
        $this->buildHtml($staticFile, $staticPath, 'article:detail', 'utf-8');
    }
    // 直接導向靜態頁（最佳效能）
    $this->redirect('/html/article/' . $staticFile);
}

靜態化策略對比

常見坑點與解決

• 編碼寫成 utf-8 而非 utf-8：TP buildHtml 參數要求 'utf-8'（無連字號），否則輸出亂碼。
• 目錄權限：HTML_PATH 需 Web 使用者寫入權限（chown www:www 或 chmod 755）。
• 模板路徑錯誤：第三參數格式為 模塊:操作（TP3）或 模板檔相對路徑（TP5/6），請查閱對應版本手冊。
• 動態數據洩漏：靜態頁不應包含用戶 Session、CSRF Token、即時價格等個人化/時效性數據。使用 ESI 或 AJAX 異步載入動態片段。
• 緩衝區巢狀衝突：若模板內部也用 ob_start()，需確保正確巢狀關閉，否則內容丟失。

現代替代方案

若專案使用 Laravel、Symfony 或現代 TP6/8，建議採用：

• HTTP 快取：Cache-Control、ETag、Last-Modified、CDN 邊緣快取。
• 全頁快取：Laravel Response::cache()、Symfony HttpCache、TP think\facade\Cache。
• SSG (Static Site Generation)：構建時生成（如 Sculpin、Jigsaw、Next.js 風格），部署純靜態檔案至 CDN/S3。

理解原生 ob_* 機制與框架封裝差異，能讓你在維護舊專案、遷移新架構、排查靜態化異常時遊刃有餘。核心永遠是：「捕獲輸出 → 持久化 → 策略性分發」。