Flarum 2.0 的正式釋出，象徵著這套以輕量、快速著稱的論壇系統邁入了一個全新的高效能時代。對於許多長期維護 Flarum 1.x 版本的站長來說，面對這次底層架構的重大變更與 API 翻新，難免會對跨版本升級感到些許擔憂。然而，今天站長成功將萌芽論壇從 Flarum v1.8.20 跨版本躍升至 v2.0.2，整個過程其實比想像中更加順暢。只要掌握大方向與正確的步驟，不被繁雜的依賴報錯打亂陣腳，升級 Flarum 2.0 絕對是一件令人充滿成就感且值得投資的事。這篇文章將梳理這次成功升級的核心心法，希望能帶給準備升級的站長們滿滿的信心。
升級的第一步，也是最重要的一步，就是進行系統的「斷捨離」。在 Flarum 1.x 時代，我們可能安裝了各式各樣的第三方擴充套件，但隨著 2.0 核心架構的升級，部分久未維護的套件將成為升級過程中的絆腳石。在下達升級指令前，我們必須先透過 Composer 狠下心來移除那些已知不相容或已被官方棄用的套件。例如舊版的個人主頁封面、夜間模式、Markdown 表格擴充、舊世代的 Email 白名單，以及升級顧問工具等。這個清理動作能大幅降低後續核心升級時發生依賴衝突的機率，為新系統騰出乾淨的運作空間。
完成環境清理後，接著迎來升級的核心關鍵：巧妙運用 Composer 的「寬鬆約束」策略。由於 Flarum 生態系中許多第三方套件正處於 2.0 的過渡期，可能會以 Beta 或 RC 版本釋出，因此我們首先需要將 Composer 的最低穩定度（minimum-stability）調整為 beta，並設定優先採用穩定版。隨後，在要求安裝 Flarum 2.0 核心時，千萬不要逐一指定各個延伸套件的精確版號，而是將所有欲保留的套件版本要求全部改為星號（*），並務必加上不立即更新的參數（--no-update）。這個技巧能讓 Composer 預先在設定檔中排好所有寬鬆條件，避免在解析過程中因為單一套件的卡關而導致整個升級程序中斷。
當所有寬鬆條件都設定妥當後，就能放心執行包含所有相依套件的全面更新指令。看著終端機畫面飛速跳動，系統自動抓取符合 Flarum 2.0 規範的最新資源並重新建立依賴樹，是整個升級過程中最療癒的時刻。下載完成後，按照標準程序執行資料庫結構遷移（migrate），並確實清除快取（cache:clear）與重新發布靜態資源（assets:publish）。當這些指令皆無報錯地順利跑完，就代表新版論壇的底層架構已經成功就緒。
核心升級成功後，接下來是尋找替代方案與適應新機制的階段。許多在 1.x 時代好用的功能，在 2.0 中可能需要由更現代化的套件來接手。以註冊信箱限制為例，過去我們可能依賴支援正規表示式的白名單套件，但在 2.0 環境下，就要切換到專為新架構開發的信箱網域管理套件（如 MailGuard），直接透過設定網域（如 gmail.com）來達到相同的防護效果，設定上反而更加直覺與輕量。
此外，Flarum 作為一個單頁應用程式（SPA），其前端路由的運作方式在升級後依然是我們需要特別留意的重點。如果您有在論壇中嵌入第三方的廣告代碼（如 Google AdSense）或自訂的統計追蹤腳本（如 Matomo），必須意識到使用者在點擊文章或切換頁面時，瀏覽器並不會真正重新載入網頁。因此，直接將程式碼貼在頁尾往往會導致腳本失效。我們需要利用原生的 MutationObserver 來監聽廣告容器的變化，或是攔截 history.pushState 等路由事件來觸發追蹤。確保這些動態監聽機制運作正常，才能讓論壇在保持極速體驗的同時，也不漏失任何重要的數據與收益。
最後，對於有自行開發客製化外掛（例如自動阻擋垃圾訊息）的進階站長來說，Flarum 2.0 帶來了最大的架構考驗。2.0 版本徹底重構了後端 API 層，全面捨棄了舊版的序列化系統（Serializer），改用全新的 API Resources 與 Schema 架構。這意味著舊版外掛只要一載入就會觸發致命錯誤。然而，解決之道其實非常優雅：我們可以利用 PHP 的 class_exists() 函式作為「版本守衛」。在程式碼中動態判斷，若偵測到舊版類別存在，就走 1.x 的邏輯；若偵測到新版 API Resource 類別，則切換到 2.0 的註冊方式。透過這種向後相容的寫法，就能讓同一份客製化程式碼在雙版本環境下暢行無阻。加上有 AI Agent 協助開發修正，這部分相信有經驗的人都可以克服。
回顧整趟 Flarum 2.0 的升級之旅，雖然面對了套件汰換、架構翻新與程式碼重構等重重挑戰，但只要思路清晰，善用 Composer 的依賴管理特性，並理解新版 API 的變更邏輯，一切問題都能迎刃而解。現在，萌芽論壇已經在 Flarum 2.0.2 的環境下展現出前所未有的流暢度與穩定性。如果您也還在觀望，不妨趁現在規劃一次系統升級，告別舊框架的包袱，為您的社群打造一個更現代、更高效率的交流空間吧！
《上一篇》PHP：再揭未修補安全漏洞 CVE-2026-115560，特殊 Session 設定引發遠端程式碼執行隱憂 
留言區 / Comments
萌芽論壇