Skip to main content

swup.js SPA 網站開發教學

本文介紹 AJAX 換頁的網站實作上的所有問題,具體來說是在純靜態的 MPA 網站中使用 DOM replace 替換做到 SPA-like 的效果的網站。本文的程式碼以 swup.js 作為範例,概念是通用的,hotwire/turbo 或是 barba.js 也同樣適用,如果你不確定要選哪個套件,可以參考前一篇文章的整理。

所有內容都源自於 AJAX 換頁的原理:「瀏覽器不載入下一頁,換頁是利用 JS 攔截連結點擊並替換節點。」

Head 標籤​

AJAX 換頁後 head 標籤內容不會自己更新,如果你是多語言網站就需要更新 lang 屬性、meta 標籤、conditional 載入的 CSS 也需要額外修改,這時應該使用 swup head-plugin。

如果有畫面閃爍問題,可以使用 persistTags 把相關標籤保留不要移除,這是因為換頁時先移除標籤,樣式消失後才換頁,保留相關標籤可以避免此問題1。

CSS​

Head 標籤內的 CSS 由 head-plugin 處理,而 body 內部的 CSS 又分成兩種情況:

  1. 屬於 swup 換頁的更新區域
  2. 不屬於 swup 換頁的更新區域

第一種情況 CSS 會自動套用,再次換頁也不會污染下一頁的 CSS;而第二種完全不會套用,因為從頭到尾就不在 DOM 裡面。

JS​

JS 需改為手動初始化和清理,因為 AJAX 因此不再有進入頁面自動執行,換頁 JS 重置的機制也不會觸發,要改成手動清理。

具體做法就和 common issues Scripts on the next page are not executed 裡面說的一樣。

基礎範例​

核心就是初次進入頁面的瀏覽器原生操作和後續 swup 接管換頁兩種邏輯都要顧到,然後 init, destroy 都要自己寫。

舉例來說,如果要綁定事件監聽器,並且在頁面之間同步 UI,應該要這樣做

// 離開頁面清理
swup.hooks.before('content:replace', () => {
foo.destroy();
});

// 進入頁面初始化
swup.hooks.on('content:replace', () => {
foo.init();
});

// 初次進入頁面,swup 尚未介入時的進入頁面初始化
foo.init();

Inline Script​

最好的方式是都不要用 inline script,依靠主 JS 檢查頁面元素,所有 JS 都靠主 bundle 檢查和觸發載入,需要用 inline script 的只有影響首屏畫面的 JS,如 canvas。

換頁初始化則一樣用 await import JS 檔案就好了。

記憶體洩漏 Memory Leak​

因為使用 AJAX 換頁,如果沒有正確清理 JS 就會不斷疊加,造成記憶體洩漏問題,比如說 A 頁面有很重的圖表 JS,現在換頁到 B 頁面沒有這些 JS 了,但是那些圖表 JS 沒有被正確清理就會造成記憶體持續佔用。

解決方式是在 hook 也要裡面也要調用 JS 附帶的清理程序,比如 echarts.dispose()。

另外要注意的還有 observer/timeout 這些類型的變數,他們會持續存活因此總是應該要手動清理。

垃圾回收 Garbage Collection​

總結來說就是「瀏覽器比你想的更聰明」。

前一個記憶體洩漏的段落明顯遺漏掉最常見的 EventListener 問題,要不要手動 remove listener 呢?實際上不必要。

如果不是迴圈一次綁定幾千個,懶惰一點不清理也沒問題,這了不起也就幾 KB 的佔用,更重要的是在 AJAX 更換之後,這些 listener 監聽的 DOM 節點不存在了,因此 JS 的垃圾回收 (garbage collection) 之後會自動清理掉這些監聽器,要確保的只有不要讓這些東西 reachable,比如閉包、外部奇怪的東西還拿著這個 listener 的參照造成 gc 認為這個 listener 還有用,從而造成記憶體洩漏。另一種情況是一次綁定幾千個監聽器,這時手動清理確實更乾淨,不過綁幾千個的情況本來就不該發生,應該用事件委派而不是綁一堆監聽器。

正確實作範例:

function setup() {
const el = document.querySelector('.foo');
el.addEventListener('click', () => {...});
}
setup();

// setup() 執行完就結束了,el 這個區域變數消失
// 之後 AJAX 把 .foo 從 DOM 移除,listener 在之後的自動 gc 也會被清除

錯誤做法如下:

const el = document.querySelector('.foo');
el.addEventListener('click', () => {...});

// 之後 AJAX 把 .foo 從 DOM 移除
// el 這個變數還活著、還握著強參照。
// 節點雖然從 DOM 樹上被拔掉了,但 el 這條參照鏈沒斷。
// 結果:這個節點物件(連同掛在它身上的 listener)繼續佔用記憶體,永遠不會被 GC,直到 el 也被設成 null、離開作用域,或整個頁面關閉。

相關參考文章可看

  • 4 Types of Memory Leaks in JavaScript and How to Get Rid Of Them 2016 的老文章就已經明確指出 Nowadays, modern browsers (including Internet Explorer and Microsoft Edge) use modern garbage collection algorithms that can detect these cycles and deal with them correctly. In other words, it is not strictly necessary to call removeEventListener before making a node unreachable.

  • Event listeners and garbage collection 前端大神,FireFox 開發者,這篇文章的意思就是瀏覽器很聰明,並且舉例 The event listener added to signal, and everything that listener can access, needs to stay in memory as long as the 'abort' event can fire.

  • How to Avoid Memory Leaks in JavaScript Event Listeners 10 年 SWE 在 2025 年還在傳遞錯誤資訊,別人老早在 2016 就已經說不清除 EventListener 不會有問題了。WeakRef 也用錯,設定了一個弱引用目的是讓 GC 可自動回收,但是 WeakRef 完全沒有發揮他想做的效果

  • WeakRef 和 FinalizationRegistry 的範例(英文原文版)和 10 年 SWE 的範例非常相似,但是這才是正確的用法:

    SWE 錯誤範例 — element 這個 DOM 元素被誰參照?

    • 外部有一個變數 element(強參照)。
    • elementRef 裡面又包了一份弱參照。
    • 這個元素同時被「一個強參照 + 一個弱參照」指著。
    • 只要那個外部的 element 變數還活著(還在作用域內、沒被設成 null),這個元素就不可能被回收,跟 elementRef 這個 WeakRef 完全無關,WeakRef 在這裡是多餘的裝飾品。

    正確範例 — DOM 元素被誰參照?

    • .window__body 這個元素,唯一的參照就是 windowElementRef 裡的弱參照。
    • 沒有任何其他變數強抓著它。
    • 所以只要它從 DOM 移除,它就真的沒人抓著了,可以被回收。
  • 絕大多數情況下無需使用 WeakRef

  • 如果想要清理,AbortController + signal 方式可以統一清理

觸發鉤子​

Swup 提供非常多的鉤子讓你可控制任務的執行時機,重點是 content, page, visit,其他 hook 適用的時機比較屬於高級動畫客製化的部分。

文檔:

404 頁面處理​

不知道為什麼整個 Github repo 乃至 FAQ 沒有任何一個人討論到 404 頁面,如果沒有處理的話 swup.js 進入 404 頁面會顯示錯誤。

404 頁面的樣式消失

Swup 只把 HTTP 500 當成錯誤,404 回應會被當成正常頁面處理,理論上不應該有任何問題,但是實際瀏覽時碰到 404 頁面會發生 CSS/JS 消失的問題。

解法就是 404 時改成一般載入,檢查 status 的時機只有 fetch:request 一處,丟出錯誤後 swup 內建的錯誤處理會自己整頁跳轉。

swup.hooks.replace('fetch:request', async (visit, args, defaultHandler) => {
const response = await defaultHandler(visit, args);
if (response.status === 404) throw new Error(`404: ${args.url}`);
return response;
});

按上一頁後連結點不動

上面解決 swup 沒有載入 CSS/JS 造成 404 頁面顯示錯誤的問題,但是還有另一個問題,從 404 按上一頁之後連結會沒反應。

原因是 swup 放棄 ajax 之前把自己標記成「導覽中」,接著整頁跳到 404,這時再按瀏覽器的上一頁按鈕,bfcache 會把原頁面連同 JS 記憶體原樣還原:swup 以為導覽還沒結束,所以現在點連結沒反應。

解法就是還原時重設狀態:

// swup 4.9.2
window.addEventListener('pageshow', (event) => {
if (!event.persisted) return;
swup.navigating = false;
swup.options.skipPopStateHandling = swup.defaults.skipPopStateHandling;
swup.location = new swup.location.constructor(window.location.href);
swup.currentHistoryIndex = window.history.state?.index ?? 1;
});

// swup 4.10.0
window.addEventListener('pageshow', (event) => {
if (!event.persisted) return;
window.addEventListener('popstate', swup.handlePopState);
swup.location = new swup.location.constructor(window.location.href);
swup.currentHistoryIndex = window.history.state?.index ?? 1;
});

這不是公開 API,升級後要重新檢查。

無障礙網站​

做了也沒人知道,但是用的到的人會感謝你的內容,設身處地著想,如果哪天我們也有某種障礙,是要加上幾行設定、幾行 aria 標記幫助閱讀,還是就讓網站難以被存取。

swup 對此也帶有 a11y 插件,筆者非常強烈建議一定要使用,不使用會有很多問題。

更通用的 a11y 討論請見本站的無障礙簡介和 A11y 設計。

進階:系統化管理​

當專案變大,基礎範例把 init 和 destroy 掛在換頁 hook 的方法會有幾個問題,第一是如果元件在換頁以外的情況也會增減的話,這種方案無法自動偵測;第二是維護問題,每次增減 JS 功能都要到主 JS 檔案寫他自己的 init 和 destroy,需要靠人工記憶且違反 SRP。

系統化管理方案的概念和執行流程是:

  1. 每次 DOM 內容改動時 MutationObserver 觸發工作
  2. forEachModuleElement 找到 DOM 上的 data-module="xxx"
  3. 對目標元素執行 mountModule 將元素綁定 JS
  4. 換頁對每個節點做 unmountModule,執行 abort 和 cleanup
  5. 需要 inline script 的則把 data-module 也加上 data-module-src,這樣換頁也會自動處理。
const registry = new Map();
const mounted = new WeakMap();
const SELECTOR = '[data-module]';

export function defineModule(name, fn) {
if (registry.has(name)) throw new Error(`module "${name}" is already defined`);
registry.set(name, fn);
}

async function mountModule(el) {
if (mounted.has(el)) return;
const ctrl = new AbortController();
const cleanups = [];
mounted.set(el, { ctrl, cleanups });

for (const name of el.dataset.module.split(/\s+/).filter(Boolean)) {
try {
let fn = registry.get(name);
if (!fn && el.dataset.moduleSrc) fn = (await import(el.dataset.moduleSrc)).default;
if (typeof fn !== 'function') {
console.warn(`yore: module "${name}" is not defined`);
continue;
}
// The element left the document while the module was loading
if (ctrl.signal.aborted) return;
const cleanup = await fn(el, { signal: ctrl.signal });
if (typeof cleanup !== 'function') continue;
if (ctrl.signal.aborted) cleanup();
else cleanups.push(cleanup);
} catch (e) {
console.error(`yore: module "${name}" failed`, e);
}
}
}

function unmountModule(el) {
const record = mounted.get(el);
if (!record) return;
mounted.delete(el);
record.ctrl.abort();
record.cleanups.forEach((fn) => {
try {
fn();
} catch (e) {
console.error(e);
}
});
}

function forEachModuleElement(node, fn) {
if (node.nodeType !== 1) return;
if (node.matches(SELECTOR)) fn(node);
node.querySelectorAll(SELECTOR).forEach(fn);
}

export function startModules() {
forEachModuleElement(document.documentElement, mountModule);
new MutationObserver((records) => {
for (const record of records) {
// Callbacks see the final DOM, so a node that was moved is connected again and keeps its module
record.removedNodes.forEach((node) =>
forEachModuleElement(node, (el) => el.isConnected || unmountModule(el)),
);
record.addedNodes.forEach((node) => forEachModuleElement(node, mountModule));
}
}).observe(document, { childList: true, subtree: true });
}

在 JS 功能上註冊:

function initCarousel(root) {
const instance = createCarousel(root);
return instance ? () => instance.destroy() : undefined;
}

defineModule('carousel', initCarousel);

再在主入口 JS 執行 startModules()。

這樣每次新增功能只需要記得 HTML 寫好 data-module,每次 DOM 改動就會觸發檢查、執行和清理。

至於複雜度則完全不必擔心,對比一般 MPA 頁面基本相同,因為這個做法和一般 MPA 頁面都是找到元素然後執行 JS,只是從每個 JS 自己找變成 observer 偵測後統一一起找,多的只有 swup 本身、observer 和清理,都是必要的開銷。

進階:JS 架構設計​

在 client-side routing 的網站中,JS 會分成三類

  1. 只須初始化一次:初始化一次就不用再管的,包含不會被移除的元素,以及可以使用事件委派完成只初始化一次就完成的
  2. 每個頁面不同,且沒有辦法綁元素:綁元素指的是把 JS 綁在 DOM 元素上。沒有辦法綁元素的例子如圖片燈箱,需要對每張圖片處理,但是不好綁元素(圖片會有很多不同來源),這種就每次換頁都執行一次初始化
  3. 每個頁面不同,有辦法綁元素:比如幫按鈕綁上 JS,或是幫 mermaid 元素綁 JS 初始化

第一類很簡單,一般 JS 直接寫就好了,無須清理也無須重複初始化。

第二類本質上就是最基礎的換頁時 init destroy,應該盡量少用,不然又變成原始的 init destroy 問題。

第三類就使用前面講到的系統化管理方案,以 defineModule 管理。

這樣分類就很清楚每次寫 JS 都知道應該怎麼做,依序判斷先符合就使用不會混淆。

第二類也可以使用 JS 自動化管理,這樣主 JS 就完全不需要知道每個 JS feature 該怎麼做了,寫法如下:

const hooks = new Set();
let cleanups = [];

export function registerRouteHook(fn, { signal } = {}) {
if (signal?.aborted) return;
hooks.add(fn);
signal?.addEventListener('abort', () => hooks.delete(fn), { once: true });
}

export function runRouteCleanups() {
const fns = cleanups;
cleanups = [];
fns.forEach((fn) => {
try {
fn();
} catch (e) {
console.error(e);
}
});
}

export function runRouteHooks() {
for (const fn of hooks) {
try {
const cleanup = fn();
if (typeof cleanup === 'function') cleanups.push(cleanup);
} catch (e) {
console.error(e);
}
}
}

在 JS 功能上註冊

registerRouteHook(() => {
init();
return destroy; // destroy function
});

在主入口呼叫

swup.hooks.on('content:replace', runRouteHooks);
runRouteHooks();

這樣三個層級就涵蓋所有 JS 使用範圍了,至於需要特別設定處理順序的仍然需要自己寫,畢竟特別就代表不多。

總結​

前一篇文章是全中文圈第一篇深入分析比較 SPA-like 套件的文章,本文則可能是世界上把 AJAX 換頁做 SPA-like 網站開發介紹的最詳細的文章,內容涵蓋 CSS、JS、404、a11y、垃圾回收全部包辦,讓你一勞永逸的解決 AJAX 網站的所有問題。

簡單網站不需要 JS 架構,直接寫 swup.hooks.before 和 on 就好了;複雜的網站就使用本文的架構,視網站實際內容調整要用幾層。只會有這兩種 JS 方案,不會再有更好的了,因為純靜態無後端的 MPA 網站要做到 SPA-like AJAX 換頁就一定要解析 DOM,做法就被限制了,Turbo Streams 或 HTMX 那種不算,那些需要後端伺服器協同。

附帶一提,Claude 最初盤點我的網站有超過 10 種不同 JS 載入方式,被他分為五種不同類型,需要四種載入機制...

進階:附錄:參考的專案的架構​

前面的架構設計是跟 Claude 討論後,參考好幾個不同專案才總結出來的架構,包含:

  1. Docusaurus
  2. vitepress
  3. Fumadocs
  4. go-gitea
  5. jellyfin-web
  6. once-campfire

其中也有 React 和 Vue 框架的專案,畢竟大家本質上都是 JS client-routing,沒有不一樣的地方,Docusaurus, Fumadocs 是 React 專案,vitepress 是 Vue 專案。

這裡附上 Claude 總結前面提到參考的六個專案的做法提供讀者參考,以下是 Claude 撰寫的內容。

Docusaurus​

兩套機制:

  1. 元素行為全部是 React 元件。 生命週期由 mount 與 unmount 決定,沒有任何「換頁時掃描 DOM」的做法。
  2. 全站橫切事務用 client module。 這是一個匯出 onRouteUpdate 與 onRouteDidUpdate 的物件,建置時自動收集,ClientLifecyclesDispatcher 在每次換頁時對每個 client module 都呼叫一次。hook 回傳函式就是 cleanup。我讀過的例子是 nprogress.ts 和 gtag,都是進度條、頁面統計這類跟元素無關的事。

每個 client module 要自己判斷這次換頁需不需要做事(例如比對 location.pathname),框架不替你過濾。

Fumadocs​

只有一套:React 元件。需要對換頁反應時,在元件裡用 usePathname() 加 useOnChange(pathname, ...),例如換頁時關閉側邊欄。沒有委派層,也沒有路由 hook 層,所有東西都是元件的 state 與 effect。

VitePress​

三種機制並存,依需求選。

  1. Markdown 產生的靜態 HTML 用全站事件委派。 copyCode.ts 與 codeGroups.ts 在 window 註冊一次 click,用 selector 判斷目標。這類功能沒有 init 與 destroy。
  2. 有狀態的功能用 Vue 元件的生命週期。 preFetch.ts 的 IntersectionObserver 在內容更新後先 disconnect() 再重建,並在 onUnmounted 清掉。copyCode.ts 用 WeakMap 記每個按鈕的 timer。
  3. 內容更新後要重算的東西用 onContentUpdated(fn),另有 onBeforeRouteChange、onAfterRouteChange 等路由 hook。

Gitea​

它不是整頁換頁,是多頁網站加局部替換,而且新舊兩套做法同時存在。

  1. 舊做法:index.ts 裡約 90 個 init 函式的陣列,每個自己 querySelector,在頁面載入時執行一次。這就是你原本遇到的問題。
  2. 新做法:data-global-init="initXxx" 加 registerGlobalInitFunc,全站一個 MutationObserver,新節點進入時初始化,用元素旗標防重複。沒有 destroy。官方註解直接說舊的 selector 式比較難維護。
  3. 局部替換:data-fetch-sync 宣告要替換的位置,用 replaceWith 或 morph,替換後靠 observer 自動初始化。

Jellyfin Web​

只有一套:view 生命週期事件。

  • view 是一個 DOM 元素,HTML 用 data-controller 指定模組。
  • 模組是 export default function (view, params),每個 view 只呼叫一次。
  • 生命週期用 view 元素上的事件表達:viewinit、viewbeforeshow、viewshow、viewbeforehide、viewhide、viewdestroy。
  • viewContainer 會快取 view,所以 view 可以被隱藏後再顯示,這就是為什麼有 show 與 hide 事件。
  • 沒有 MutationObserver、沒有事件委派層。監聽器綁在 view 上,view 銷毀就一起消失,只有改了 view 以外的東西才在 viewhide 還原。

Once Campfire​

只有一套:Stimulus controller。

  • data-controller="名稱" 宣告,依檔名自動註冊,一個元素可掛多個。
  • 生命週期是 connect 與 disconnect,由 Stimulus 自己的 MutationObserver 驅動。
  • Turbo 負責換頁,Stimulus 負責元素,兩者互不認識。
  • 全站行為掛在 <body data-controller="...">。
  • 36 個 controller 只有 8 個寫了 disconnect()。

整理​

專案機制數主要機制
Docusaurus2元件生命週期加全站路由 hook
Fumadocs1元件生命週期
VitePress3事件委派、元件生命週期、內容更新 hook
Gitea2 到 3(新舊並存)屬性宣告加 MutationObserver
Jellyfin Web1view 元素上的生命週期事件
Campfire1Stimulus 的 connect 與 disconnect

Footnotes​

  1. 沒看到能設定 plugin 順序的方法。 ↩