WordPress 圖片燈箱效果：內建「點擊放大」與不用外掛的 GLightbox 寫法

「燈箱」（Lightbox）效果是指：點一下文章裡的圖片，畫面變暗，圖片放大顯示在正中間，看完再關掉回到文章。產品照、作品集、教學截圖都很需要這個功能。

以前要做燈箱，一定得裝外掛，或自己引入 fancybox 之類的套件。現在 WordPress 的圖片區塊已經內建這個功能，大部分情況不用寫程式。

方法一：用 WordPress 內建的點擊放大（推薦）

WordPress 6.4 起，圖片區塊內建燈箱功能：

1. 在區塊編輯器點選圖片。
2. 按圖片工具列上的「連結」按鈕。
3. 選擇點擊後放大圖片的選項（英文介面是 Enlarge on click 或 Expand on click）。
4. 更新文章，到前台點圖片測試。

要注意：

• 圖片如果已經設定了其他連結，就不能同時使用放大功能，兩者只能選一個。
• 圖庫（相簿）區塊裡的每一張圖片也是圖片區塊，一樣可以設定。

全站預設開啟

不想每張圖片都設定一次，可以在子主題的 theme.json 加入：

{
  "version": 2,
  "settings": {
    "blocks": {
      "core/image": {
        "lightbox": {
          "enabled": true
        }
      }
    }
  }
}

這樣圖片區塊預設就會開啟點擊放大（有設定其他連結的圖片除外）。如果子主題已經有 theme.json，把 lightbox 那一段加進原本的 settings 裡就好，不要整個檔案覆蓋掉。

限制：這個功能只對「圖片區塊」有效。用傳統編輯器（Classic Editor）寫的舊文章，或放在「傳統」區塊裡的圖片，不會有效果，這時候用方法二。

方法二：舊文章、傳統編輯器：用 GLightbox 自己加

GLightbox 是一個免費（MIT 授權）、不需要 jQuery 的燈箱套件，支援手機滑動切換。舊版文章用的 fancybox 舊版本已經停止維護，新版 Fancybox 用在商業網站則需要購買授權，所以這裡改用 GLightbox。

步驟一：放入檔案

到 GLightbox 的官方 GitHub 下載最新版，取出 dist/css/glightbox.min.css 與 dist/js/glightbox.min.js 這兩個檔案，在子主題的資料夾裡建立一個 glightbox 資料夾，把檔案放進去。

檔案放在自己的主機上，不依賴外部網站，比較穩定，也不用擔心對方網站變動。

步驟二：建立啟動程式

在同一個 glightbox 資料夾裡，新增一個 lightbox-init.js：

document.addEventListener('DOMContentLoaded', function () {
  var imagePattern = /\.(jpe?g|png|gif|webp|avif)(\?.*)?$/i;
  var links = document.querySelectorAll('.entry-content a, .wp-block-post-content a');

  links.forEach(function (link) {
    var href = link.getAttribute('href') || '';
    // 只處理「連到圖片檔案、而且裡面有圖片」的連結
    if (imagePattern.test(href) && link.querySelector('img')) {
      link.classList.add('glightbox');
      link.setAttribute('data-gallery', 'post-images');
    }
  });

  if (typeof GLightbox === 'function') {
    GLightbox({ selector: '.glightbox' });
  }
});

這段會找出文章內容裡「連到圖片檔案」的圖片連結，替它們加上燈箱；data-gallery 讓同一篇文章裡的圖片可以左右切換。

.entry-content、.wp-block-post-content 是常見主題包住文章內容的區塊名稱。如果你的主題不一樣，用瀏覽器的開發者工具（F12）看一下文章內容外層的 class，替換進去即可。

步驟三：載入檔案

在子主題的 functions.php 加入：

add_action( 'wp_enqueue_scripts', function () {
    // 只在單篇文章與頁面載入
    if ( ! is_singular() ) {
        return;
    }

    $uri  = get_stylesheet_directory_uri() . '/glightbox';
    $path = get_stylesheet_directory() . '/glightbox';

    // 用檔案修改時間當版本號,檔案更新時瀏覽器會重新下載
    $ver = function ( $file ) use ( $path ) {
        return file_exists( $path . '/' . $file ) ? (string) filemtime( $path . '/' . $file ) : null;
    };

    wp_enqueue_style( 'glightbox', $uri . '/glightbox.min.css', array(), $ver( 'glightbox.min.css' ) );
    wp_enqueue_script( 'glightbox', $uri . '/glightbox.min.js', array(), $ver( 'glightbox.min.js' ), true );
    wp_enqueue_script( 'glightbox-init', $uri . '/lightbox-init.js', array( 'glightbox' ), $ver( 'lightbox-init.js' ), true );
} );

只在單篇文章與頁面載入，首頁、分類頁不會多載入這些檔案。

步驟四：圖片要連結到圖片檔案

燈箱是替「連到圖片檔案的連結」加上效果，所以插入圖片時，連結要選連到媒體檔案。想讓之後插入的圖片預設就連到檔案，可以參考WordPress 插入圖片的預設選項，把 image_default_link_type 設成 file。

方法一和方法二可以同時使用：新文章用內建的點擊放大，舊文章靠 GLightbox。內建放大的圖片本身沒有連結，不會被方法二重複處理。

舊版寫法為什麼不能用了

• 下載連結已經失效，fancybox 舊版本也已停止維護。
• $(document).ready 會出錯：WordPress 載入的 jQuery 是相容模式，不能直接使用 $；而且很多新主題的前台根本沒有載入 jQuery。
• 直接修改主題的 footer.php：主題一更新，加的程式碼就不見了；bloginfo('template_url') 指向的也是父主題的資料夾，用子主題時會找不到檔案。
• 每一頁都載入燈箱檔案，包括用不到的首頁與分類頁。
• 用正規表示式改寫文章的 HTML：遇到比較複雜的連結寫法容易出錯，改在瀏覽器端處理比較安全。

常見問題

點圖片沒有反應？

• 確認圖片的連結是連到媒體檔案，而不是「無」或附件頁面。
• 按 F12 切到「Console（主控台）」，看有沒有紅色的錯誤訊息，常見是檔案放錯位置、路徑不對。
• 主題包住文章內容的 class 跟程式碼裡寫的不一樣。

點一下跳出兩層燈箱？

主題或其他外掛可能也內建燈箱功能，保留一個就好。

用外掛比較簡單嗎？

不想碰程式碼的話，到「外掛 → 安裝外掛」搜尋 lightbox，選更新日期近、安裝數多的外掛也可以。只是不要跟內建的點擊放大用在同一張圖片上。

延伸閱讀

• WordPress 插入圖片的預設對齊、連結與尺寸：用程式碼設定一次就好
• WordPress 限制上傳檔案類型：upload_mimes 寫法與 JPG、PNG、WebP、SVG 格式選擇
• WordPress 網站加速完整攻略：測速、主機、快取、圖片、外掛與資料庫清理

作品、產品照片展示得好不好看，會直接影響訪客的印象。正威網路行銷是 25 年經驗的基隆網頁設計工作室，提供客製化網頁設計，也有攝影剪輯服務，歡迎來聊聊。