萬盛學電腦網

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

PHP CSS 靜態資源版本更新類:自動為 CSS 中圖片引用添加版本號防緩存

一、問題背景

CSS 文件中引用的背景圖、圖標等靜態資源更新後,瀏覽器緩存導致用戶看到舊版本。解決方案:為圖片 URL 自動添加版本查詢參數(如 bg.png?v=20240115),部署時批量更新 CSS 文件。

二、CSSUpdate 類設計

核心功能:

  • 掃描 CSS 模版目錄(支持遞歸子目錄)
  • 匹配 url(...) 中的圖片路徑
  • 為匹配的圖片副檔名添加/更新版本參數
  • 輸出到目標 CSS 目錄,保持目錄結構

三、完整類實現

<?php
/**
 * CSSUpdate - CSS 靜態資源版本更新器
 * 遍歷模版目錄,為 CSS 中圖片引用添加版本號,輸出到目標目錄
 */
class CSSUpdate {
    private $csstmpl_path;    // CSS 模版源目錄
    private $css_path;        // 目標輸出目錄
    private $replacetags = []; // 需要處理的圖片副檔名
    private $search_child = false; // 是否遞歸子目錄
    private $convert_num = 0;  // 處理文件計數
    private $is_ready = 0;     // 初始化狀態

    /** 初始化
     * @param string $csstmpl_path 源 CSS 目錄
     * @param string $css_path 目標 CSS 目錄
     * @param array $replacetags 圖片副檔名 ['png','jpg','gif']
     * @param bool $search_child 是否遞歸子目錄
     */
    public function __construct($csstmpl_path, $css_path, array $replacetags = [], $search_child = false) {
        if (!is_dir($csstmpl_path) || !is_dir($css_path) || empty($replacetags)) {
            $this->is_ready = 0;
        } else {
            $this->csstmpl_path = rtrim($csstmpl_path, '/');
            $this->css_path = rtrim($css_path, '/');
            $this->replacetags = array_map('strtolower', $replacetags);
            $this->search_child = $search_child;
            $this->is_ready = 1;
        }
    }

    /** 執行更新 */
    public function update() {
        if ($this->is_ready === 0) {
            $this->response('配置錯誤:源目錄、目標目錄或副檔名列表無效');
            return;
        }
        
        $this->convert_num = 0;
        $this->traversing($this->csstmpl_path);
        $this->response("處理完成,共更新 $this->convert_num 個 CSS 文件");
    }

    /** 遞歸遍歷目錄 */
    private function traversing($path) {
        $handle = opendir($path);
        if (!$handle) return;
        
        while (($file = readdir($handle)) !== false) {
            if ($file === '.' || $file === '..') continue;
            $curfile = $path . '/' . $file;

            if (is_dir($curfile)) {
                if ($this->search_child) {
                    $this->traversing($curfile);
                }
            } elseif ($this->checkExt($curfile)) {
                // CSS 文件:生成目標路徑並處理
                $dfile = str_replace($this->csstmpl_path, $this->css_path, $curfile);
                $this->create($curfile, $dfile);
                $this->response("$curfile -> $dfile 更新成功");
                $this->convert_num++;
            }
        }
        closedir($handle);
    }

    /** 檢查是否為 CSS 文件 */
    private function checkExt($file) {
        $ext = strtolower(pathinfo($file, PATHINFO_EXTENSION));
        return $ext === 'css';
    }

    /** 核心處理:讀取模版、替換圖片 URL、寫入目標 */
    private function create($tmplfile, $dfile) {
        $css_content = file_get_contents($tmplfile);
        
        foreach ($this->replacetags as $ext) {
            // 匹配 url("xxx.ext") url('xxx.ext') url(xxx.ext)
            // 版本號格式:?v=時間戳 或 ?v=哈希
            $version = 'v=' . time(); // 或文件哈希:md5_file($img_path)
            
            $pattern = '/url\([\'"]?([^\'")]+\.' . $ext . ')([\'"]?)\)/i';
            $css_content = preg_replace_callback($pattern, function($matches) use ($version) {
                $url = $matches[1];
                // 已有版本參數則替換,否則追加
                if (strpos($url, '?') !== false) {
                    $url = preg_replace('/\?v=[^&]*/', '?' . $version, $url);
                } else {
                    $url .= '?' . $version;
                }
                return 'url("' . $url . '")'; // 統一雙引號
            }, $css_content);
        }
        
        // 確保目標目錄存在
        $dstDir = dirname($dfile);
        if (!is_dir($dstDir)) mkdir($dstDir, 0755, true);
        
        file_put_contents($dfile, $css_content, LOCK_EX);
    }

    /** 日誌輸出(可擴展寫文件) */
    private function response($msg) {
        echo date('[Y-m-d H:i:s] ') . $msg . "\n";
    }
}
?>

四、使用示例

部署腳本調用

<?php
require 'CSSUpdate.class.php';

// 配置
$tmplDir = __DIR__ . '/css_src';      // 開發環境 CSS 源碼
$distDir = __DIR__ . '/public/css';   // 生產環境輸出
$imageExts = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'ico'];

$updater = new CSSUpdate($tmplDir, $distDir, $imageExts, true); // true=遞歸子目錄
$updater->update();
?>

處理前後對比

/* 處理前 (css_src/style.css) */
.header { background: url(../images/logo.png); }
.icon { background: url('sprite.jpg?v=123'); }

/* 處理後 (public/css/style.css) */
.header { background: url("../images/logo.png?v=1705312800"); }
.icon { background: url("sprite.jpg?v=1705312800"); }

五、進階優化策略

1. 基於文件內容哈希的版本號(精確緩存控制)

// 替換 create() 中的版本生成邏輯
private function getVersion($imgRelPath) {
    // 解析圖片絕對路徑
    $imgPath = $this->resolveImagePath($imgRelPath);
    if (file_exists($imgPath)) {
        return 'v=' . substr(md5_file($imgPath), 0, 8); // 8位哈希
    }
    return 'v=' . time(); // 回退時間戳
}

// 正則回調中使用
$version = $this->getVersion($matches[1]);

2. 支持 @import 和 sourceMappingURL

// 在 create() 中添加
// 處理 @import
$css_content = preg_replace_callback(
    '/@import\s+[\'"]([^\'"]+\.css)[\'"]/i',
    function($m) { return '@import "' . $this->processImport($m[1]) . '";'; },
    $css_content
);

// 保留 sourceMappingURL 不處理
// 或更新 sourcemap 對應關係

3. 併行處理大量文件

<?php
// 使用進程池並行處理
$files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($tmplDir));
$cssFiles = new RegexIterator($files, '/\.css$/i');

$pool = new Pool(4); // 4進程
foreach ($cssFiles as $file) {
    $pool->submit(new CssProcessTask($file, $distDir, $imageExts));
}
$pool->shutdown();
?>

六、構建工具整合對比

工具優點缺點適用場景
本 CSSUpdate 類零依賴、PHP 原生、易整合舊項目功能單一、無壓縮、無 SourceMap遺留項目、簡單部署
Gulp/Grunt + gulp-rev生態豐富、支持壓縮、SourceMap、並行需 Node 環境、配置複雜現代前端工程化
Webpack + MiniCssExtractPlugin模塊化、Hash 命名、代碼分割、HMR學習曲線陡峭、構建慢大型 SPA/SSR 項目
Vite極速構建、原生 ESM、插件生態較新、舊瀏覽器需 polyfill新項目首選

七、最佳實踐清單

  1. ✅ 版本號使用內容哈希而非時間戳(精確失效,利用長期緩存)
  2. ✅ CSS 文件本身也應添加哈希命名:style.a1b2c3d4.css
  3. ✅ 配置 Nginx expires 1y + add_header Cache-Control "public, immutable"
  4. ✅ HTML 中引用通過模版變量注入帶哈希的 CSS 文件名
  5. ✅ 遷移至現代構建工具作為長期技術棧規劃

CSSUpdate 類為無法引入 Node.js 構建鏈的 PHP 項目提供了實用的靜態資源版本化方案,是從傳統部署向現代前端工程化過渡的橋梁。

copyright © 萬盛學電腦網 all rights reserved