在開發 WordPress 主題或自訂頁面時,常會遇到需要導入 Owl Carousel 來製作輪播圖的需求。如果直接在 header.php 或 footer.php 手寫 HTML 標籤來引入 CSS 和 JS,很容易導致 jQuery 重複載入或載入順序錯誤,最終造成 Slider 無法正常運作或 JavaScript 報錯。這是因為 WordPress 有一套專門的資源管理機制,必須遵循這套規範才能確保外掛與主題間的相容性。
內容導覽
為什麼要使用 wp_enqueue_scripts?
WordPress 的 wp_enqueue_scripts 鉤子(Hook)是用來管理前端資源的核心機制。透過這個方式載入套件有三大優點:第一,它可以處理「相依性」,例如確保 Owl Carousel 的 JS 一定在 jQuery 之後才執行;第二,它可以避免重複載入相同的函式庫;第三,它能讓其他外掛有機會對這些資源進行優化(如合併或壓縮)。
實作程式碼
/**
* 將 Owl Carousel 的 CSS / JS 佇列到前端
* 前綴統一使用 rs_
*/
function rs_enqueue_owl_carousel() {
/* ===== CSS ===== */
wp_enqueue_style(
'rs-owl-carousel',
'https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/assets/owl.carousel.min.css',
array(),
'2.3.4'
);
wp_enqueue_style(
'rs-owl-carousel-theme',
'https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/assets/owl.theme.default.min.css',
array('rs-owl-carousel'),
'2.3.4'
);
/* ===== JS ===== */
// WordPress 內建 jQuery,這裡確保它被加入
wp_enqueue_script('jquery');
wp_enqueue_script(
'rs-owl-carousel',
'https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/owl.carousel.min.js',
array('jquery'),
'2.3.4',
true // 放在 footer,減少 render-blocking
);
}
add_action('wp_enqueue_scripts', 'rs_enqueue_owl_carousel');步驟拆解與說明
- 定義唯一識別碼(Handle):在
wp_enqueue_style中,第一個參數(如 ‘rs-owl-carousel’)是該資源的 ID,建議加上專案前綴以防與其他外掛衝突。 - 處理 CSS 相依性:載入 Theme CSS 時,我們在
array('rs-owl-carousel')中填入核心 CSS 的 ID,這樣 WordPress 就會確保核心樣式一定排在主題樣式前面。 - 呼叫內建 jQuery:不需要另外從 CDN 引入 jQuery,直接使用
wp_enqueue_script('jquery')即可呼叫 WordPress 核心內建的版本。 - 放置於頁面底部:在 JS 函式的最後一個參數設為
true,這會將<script>標籤放在</body>之前,有助於提升頁面的載入速度分數(LCP/FCP)。
實務踩坑提醒
- noConflict 模式:WordPress 內建的 jQuery 預設開啟 noConflict 模式。這意味著在寫初始化 JS 時,不能直接使用
$('.owl-carousel'),必須使用jQuery('.owl-carousel'),或是將代碼包在(function($){ ... })(jQuery);的匿名函式中。 - 版本號更新:在開發環境修改 CSS 後,如果發現前端沒變化,記得更新
wp_enqueue中的版本號參數(如從 ‘2.3.4’ 改成日期),這能強迫瀏覽器抓取新檔案,避開快取問題。 - HTTPS 協議:從 CDN 引入資源時,務必檢查連結是否包含
https:。如果網站有安裝 SSL 但資源連結是http:,瀏覽器會因為安全性考量封鎖該資源,導致輪播圖破圖。
看不懂沒關係,照做就能用
以上的原理看不懂沒關係,只要照著下面的步驟操作就能直接套用:
操作步驟
- 安裝並啟用 FluentSnippets 外掛
- 在後台選單進入 FluentSnippets,點擊「Create New」新增 PHP 片段
- 將文章中的 PHP 程式碼完整複製並貼入編輯區域
- 點擊儲存並將狀態切換為啟用 (Status: On)
- 清除網站快取並前往前台確認輪播圖功能
如果啟用後網站出現異常,回到 Snippets 將該片段停用即可立刻復原,不會影響其他設定。


