Drupal Views 分頁器 Pager ID 衝突：區塊視圖嵌入頁面導致搜尋結果分頁錯誤的根因與修復

現象

搜尋結果頁面的總筆數、總頁數永遠顯示為一個固定的錯誤數字。禁用自定義模組、切換核心主題 Bartik 後問題依舊，僅切換到其他主題（如 Zen）時復現，極具迷惑性。

排查歷程

1. 禁用所有自定義模組、切換核心主題 → 問題依然存在
2. 逐個啟用模組 → 定位到主題層
3. 主題僅覆寫搜尋結果模板，邏輯極簡 → 排除模板代碼問題
4. 切換 Zen 主題 → 同樣復現 → 問題非主題專屬，而是「頁面上有多個分頁器」的通用觸發條件
5. 追蹤變數變化：$pager_total_items 在某區塊渲染後被竄改
6. 該區塊為 Views 生成的「帶分頁視圖區塊」
7. 恍然大悟：Views Pager ID 預設為 0，與搜尋結果分頁器衝突！

核心機制：Drupal 分頁器全域變數

Drupal 所有分頁器基於 4 個全域陣列變數，以 Pager ID 為索引區分多個分頁器：

• $pager_page_array — 當前頁碼
• $pager_total — 總頁數
• $pager_total_items — 總記錄數
• $pager_limits — 每頁筆數

Entity/Node 列表模組會自動遞增 Pager ID，但 Views 分頁器預設 ID = 0。當頁面同時存在：

1. 主內容分頁器（搜尋結果，ID = 0）
2. 區塊視圖分頁器（側邊欄「熱門文章」，ID = 0）

後渲染的區塊視圖會覆蓋全域 $pager_total_items[0]，導致主內容讀取到錯誤的總筆數。

修復：為區塊視圖指定唯一 Pager ID

1. 編輯 Views：進階 → 其它 → Pager ID
2. 設定為較大唯一整數，如 100、999、12345
3. 儲存、清除快取

最佳實踐：統一 Pager ID 分配規範

代碼層面驗證（模組開發者參考）

<?php
// 手動建立分頁器時指定 ID
$pager_id = 123;
$per_page = 10;
$current_page = pager_find_page($pager_id); // 自動從 $_GET['page'] 讀取

$total_items = $query->count()->execute();
pager_default_initialize($total_items, $per_page, $pager_id);

$results = $query->range($current_page * $per_page, $per_page)->execute();

// 主題輸出
$output = theme('pager', ['tags' => [], 'element' => $pager_id, 'parameters' => []]);

常見誤區

• ❌ 以為只有「同一頁面多個 Views」才衝突 → 搜尋結果 + 區塊視圖 同樣衝突
• ❌ 以為更換主題能解決 → 主題不影響 Views Pager ID 邏輯
• ❌ 設定 Pager ID 為 1、2 等小數字 → 易與核心/其他模組衝突，用大數字
• ❌ 忘記清快取 → Views 設定變更需重建快取才生效

總結

Drupal 分頁器衝突是「隱形殺手」：症狀極具誤導性（總筆數錯誤），實則源於 全域陣列索引碰撞。鐵律：頁面上每個分頁器必須擁有唯一 Pager ID。Views 區塊視圖嵌入頁面時，務必手動設定 Pager ID ≥ 100。這個 30 秒的配置，能省下數小時的排查人生。