在一個 Drupal 專案中,我們遭遇了一個極具迷惑性的問題:搜尋結果頁面的總記錄數與總頁數永遠固定在一個錯誤數值。經過數天的多方向排查,最終定位到 Views 區塊視圖的 Pager ID 衝突。本文完整記錄排查過程、核心原理分析與解決方案,為開發者提供避坑指南。
症狀:搜尋結果頁面顯示的總筆數、總頁數錯誤且固定不變,無論搜尋關鍵字如何變化。
排查路徑:
Drupal 所有分頁器基於四個全域陣列變量構建:
$pager_page_array // 當前頁碼
$pager_total // 總頁數
$pager_total_items // 總記錄數
$pager_limits // 每頁記錄數
這些陣列以 Pager ID 作為下標 區分多個分頁器。Entity 等核心模組會自動遞增 Pager ID,確保同頁多個分頁器互不干擾。
Views 模組生成分頁器時,Pager ID 預設固定為 0。當頁面存在多個分頁器時(典型場景:主內容區搜尋結果分頁 + 側邊欄 Views 區塊分頁),後渲染的 Views 區塊會覆蓋先前的 Pager ID 0 數據,導致主分頁器讀取到錯誤的統計信息。
在 Views 視圖編輯介面的「分頁器」設置中,展開「進階」選項,修改 Pager ID 為唯一值(建議使用較大數字,如 100、200 等,避免與核心模組衝突)。

| 場景 | 建議 Pager ID | 說明 |
|---|---|---|
| 主內容區分頁(搜尋/列表) | 0(預設) | 核心模組通常佔用 0,保持不變 |
| 側邊欄 Views 區塊分頁 | 100+ | 避開核心範圍,預留擴展空間 |
| 頁面多個 Views 區塊 | 101, 102... | 每個區塊分配唯一遞增 ID |
| 嵌入式 Views (Views Embed) | 200+ | 區分頁面級與嵌入級分頁器 |
在主題的 template_preprocess_views_view() 或 hook_views_pre_render() 中調試:
function MYTHEME_views_pre_render(&$view) {
if ($view->name === 'sidebar_block') {
\Drupal::logger('pager_debug')->notice('Pager ID: @id, Total: @total', [
'@id' => $view->pager->getPagerId(),
'@total' => $view->pager->getTotalItems(),
]);
}
}
Pager ID 衝突是 Drupal 多區塊分頁場景的經典陷阱。關鍵認知:
理解底層全域陣列機制,能從根源上避免此類難以復現的幽靈 Bug。