PHP 輸出緩衝控制實現靜態 HTML 頁面生成完整指南

利用 PHP 輸出緩衝控制（Output Control）函數 ob_start()、ob_get_contents()、ob_end_clean() 將動態頁面捕獲並寫入靜態 HTML 檔案，是早期 PHP 高效能網站常用的「偽靜態」技術。雖然現代框架多採用模板引擎或靜態站點生成器，但理解此機制對維護舊專案、簡易快取系統仍有實務價值。

核心函數機制解析

基礎實作範例

<?php
// 1. 啟動緩衝（最早呼叫，任何輸出前）
ob_start();

// 2. 產生動態內容（這裡可包含資料庫查詢、模板渲染等）
?>
<!DOCTYPE html>
<html>
<head>
    <title>動態生成的靜態頁面</title>
</head>
<body>
    <h1>歡迎，<?php echo htmlspecialchars($username); ?></h1>
    <p>生成時間：<?php echo date('Y-m-d H:i:s'); ?></p>
    <!-- 更多動態內容 -->
</body>
</html>
<?php
// 3. 取得緩衝內容並關閉緩衡
$htmlContent = ob_get_clean();

// 4. 寫入靜態檔案
$filePath = __DIR__ . '/static/page.html';
$dir = dirname($filePath);
if (!is_dir($dir)) {
    mkdir($dir, 0755, true);
}

if (file_put_contents($filePath, $htmlContent) === false) {
    error_log("靜態檔案寫入失敗: $filePath");
    // 可選：直接輸出給瀏覽器作為 fallback
    echo $htmlContent;
} else {
    echo "靜態頁面生成成功：$filePath";
}
?>

進階：帶快取失效機制的靜態頁生成器

<?php
class StaticPageGenerator
{
    private string $cacheDir;
    private int $ttl; // 秒

    public function __construct(string $cacheDir, int $ttl = 3600)
    {
        $this->cacheDir = rtrim($cacheDir, '/');
        $this->ttl = $ttl;
        if (!is_dir($this->cacheDir)) {
            mkdir($this->cacheDir, 0755, true);
        }
    }

    /**
     * 獲取靜態頁面，若過期或不存在則重新生成
     * @param string $pageKey 頁面唯一鍵（如 'home', 'article-123'）
     * @param callable $generator 生成器回呼 function(): string
     * @return string HTML 內容
     */
    public function getPage(string $pageKey, callable $generator): string
    {
        $filePath = $this->cacheDir . '/' . $pageKey . '.html';
        
        // 檢查快取是否有效
        if (file_exists($filePath)) {
            $mtime = filemtime($filePath);
            if ((time() - $mtime) < $this->ttl) {
                return file_get_contents($filePath);
            }
        }

        // 重新生成
        ob_start();
        try {
            $content = $generator();
            // 若生成器直接輸出而非返回字串
            if ($content === null) {
                $content = ob_get_clean();
            } else {
                ob_end_clean(); // 丟棄緩衝（若有）
            }
        } catch (Throwable $e) {
            ob_end_clean();
            throw $e;
        }

        // 原子性寫入：先寫暫存檔再 rename，避免部分寫入被讀取
        $tmpFile = $filePath . '.tmp.' . bin2hex(random_bytes(4));
        if (file_put_contents($tmpFile, $content) === false) {
            throw new RuntimeException("靜態檔案寫入失敗: $filePath");
        }
        if (!rename($tmpFile, $filePath)) {
            @unlink($tmpFile);
            throw new RuntimeException("靜態檔案重命名失敗: $filePath");
        }

        return $content;
    }

    public function clearCache(string $pageKey = ''): void
    {
        if ($pageKey) {
            $file = $this->cacheDir . '/' . $pageKey . '.html';
            if (file_exists($file)) unlink($file);
        } else {
            $files = glob($this->cacheDir . '/*.html');
            foreach ($files as $file) unlink($file);
        }
    }
}

// 使用範例
$generator = new StaticPageGenerator(__DIR__ . '/cache/pages', 600); // 10 分鐘快取

// 首頁
echo $generator->getPage('index', function() {
    $articles = getLatestArticles(10); // 假設函數
    include __DIR__ . '/templates/home.php'; // 模板內直接輸出
});

// 文章頁
echo $generator->getPage('article-123', function() use ($articleId) {
    $article = getArticle($articleId);
    include __DIR__ . '/templates/article.php';
});

// 手動清除快取（如後台發文後）
// $generator->clearCache('index');
// $generator->clearCache('article-123');
?>

模板檔案範例

<!-- templates/home.php -->
<!DOCTYPE html>
<html>
<head><title>首頁</title></head>
<body>
    <h1>最新文章</h1>
    <ul>
    <?php foreach ($articles as $art): ?>
        <li><a href="/article/<?= $art['id'] ?>"><?= htmlspecialchars($art['title']) ?></a></li>
    <?php endforeach; ?>
    </ul>
</body>
</html>

關鍵最佳實踐

1. 原子性寫入：使用暫存檔 + rename() 避免讀取到半寫入的檔案（rename 在同檔案系統上是原子操作）。
2. 目錄權限：確保 PHP 程序使用者對快取目錄有寫入權限（PHP-FPM 使用者、Apache 使用者）。
3. 快取鍵設計：包含足夠資訊區分版本（如 article-123-v2 或加入語言、裝置類型）。
4. 清除策略：資料變更時（發文、編輯、刪除）主動清除相關快取，或使用短 TTL 配合隨機失效防止雪崩。
5. 避免在緩衝區內操作資料庫寫入：緩衝區內發生錯誤導致腳本中止時，資料庫可能已提交，造成不一致。
6. 大檔案記憶體考量：超大頁面（>10MB）可能耗盡 memory_limit，考慮分塊輸出或直接串流寫入檔案。

常見問題與避坑

現代替代方案對比

總結

PHP 輸出緩衝生成靜態頁面是經典且實用的技術，核心在於 ob_start() 捕獲輸出、ob_get_clean() 取得內容、原子性寫入檔案。現代專案建議優先考慮模板引擎內建快取或反向代理快取，但在輕量級場景、舊系統改造、或需要精細控制生成邏輯時，手動實作仍具優勢。關鍵點：原子寫入、權限管理、快取失效策略、記憶體限制。