前言
均一平台最近進行了一場大概十個月的前端架構瘦身之旅。說真的,面對一個養了超過十年的 codebase,而且牽扯到的不只是前端,連後端跟雲端服務都有份,這趟旅程走起來一點也不輕鬆。
前端架構演進史
均一平台主站的 codebase 已經十幾歲了,這中間前端技術堆積了好幾輪,就像是地層一般;來回顧一下它怎麼長成今天這個樣子的。

Template Engine
最一開始用的是 Jinja template engine,從 2013 年專案誕生就陪著我們。到了 2014 年 7 月,團隊又拉進了 Handlebars。為什麼要再多一套呢?因為 Handlebars 有個好處:Python 跟 JavaScript 都能 render,這樣前後端就可以共用同一套 template 語法,不用各寫各的。
不過當時並沒有把所有 Jinja 都翻成 Handlebars,所以 codebase 裡就這麼兩套 template engine 和平共處了好一陣子。
雖然 Handlebars 讓前後端語法統一了,但在瀏覽器上還是得靠 jQuery 去挖 DOM 來更新畫面,說實在還是有點麻煩。所以團隊在 2016 年 11 月導入了 React,總算可以用宣告式的方式來處理 UI 了。
但老問題又回來了:React 沒辦法給 Python 後端 render 啊。所以那些需要 SSR(Server-Side Rendering)的地方,還是只能回頭用 Jinja 或 Handlebars,React 幫不上忙。
為了徹底解決這件事,團隊終於在 2022 年 6 月導入了 Next.js,並用 Load Balancer 把特定路徑的流量導去 Next.js 伺服器。
到這個時間點,前端 codebase 就很清楚地切成兩邊了:舊架構(Jinja + Handlebars + Client-Side React)跟新架構(Next.js)。
前端 Build Pipeline
在專案剛開始的時候,前端是用 Python 自己兜了一套 build pipeline。怎麼兜的呢?寫一堆 Python script 去呼叫 Terser 編譯跟壓縮 JavaScript,然後再把檔案拼起來;CSS 這邊也差不多,用 Python 去跑 Less、Autoprefixer、cssmin,最後一樣合併檔案。
到了 2016 年 11 月,跟著 React 一起進來的還有 Webpack。流程是輸出 IIFE 格式,再從 Jinja 那邊用 HTML script tag 載入。跟 template engine 的故事一樣,這次也沒有全面搬過去,兩套建置工具繼續共存。
再後來,Next.js 登場了,它自己也帶了一套 build 流程。
到這個階段,系統裡一次養著三套 build pipeline。
| Framework | Template Engine (Server Side) | Template Engine (Client Side) | Build pipeline |
|---|---|---|---|
| Flask | Jinja + Handlebars | Handlebars | 自建 Python build pipeline |
| React | Webpack | ||
| Next.js | React | Next.js | |
痛點
雖然導入了 Next.js,但大部分路徑還是靠舊技術在撐(84 個 vs. 24 個),而且使用量最高的影片頁跟習題頁都在舊的那邊。
好幾套 build pipeline 同時存在,維護起來真的很累。更別說這套自建的 Python build pipeline 沒什麼現代化的功能,像是 npm 套件管理跟 dynamic import,通通沒有。
想在 Next.js 加新路徑?得上線後去改 Load Balancer 規則才行,讓 release 跟 rollback 的步驟又多了一步。
遷移規劃
我們的目標很明確:把 SSR 這塊收斂到只剩 Next.js,也就是跟 Jinja 還有 server-side Handlebars 說再見。這樣一來,前端 build pipeline 自然也會跟著簡化到只剩 Next.js 那一套。
整趟轉換我刻意設計成「隨時都能停下來」的節奏,不會做到一半卡住進退兩難。而且每個階段結束後,開發體驗(DX)都會有明顯的升級感。
第一階段:把 Jinja 裡面用 script tag 內嵌的 Python 通通拉出來,做 Python / JS 的切割。這個階段結束後就不會有 JavaScript 混合 Python 邏輯。
<script type="text/javascript">
$(function () {
ClassProfile.studentLists = {{ templatetags.jsonify(student_lists, false) }};
ClassProfile.initialGraphUrl = '{{ initial_graph_url|escapejs }}';
ClassProfile.cachedExercisesDate = '{{ cached_exercises_date }}';
ClassProfile.init('{{ coach_email }}');
})
</script>
第二階段:跟自建的 Python build pipeline 揮手告別,全面轉到 Webpack。這階段做完之後,改舊頁面的 JS 就會自動重新打包加重整頁面了(之前可是要手動重開 Flask server 再手動刷新,想起來都累)。
第三階段:把 Webpack 上面的 JavaScript 搬到 Next.js。這一步要做的就是 Jinja / Handlebars → JSX 的改寫。
至於 Jinja 轉 Next.js 怎麼做呢?我們走的是 BFF(Backend for Frontend)路線:把 Flask handler 本來產生來 render Jinja 的資料直接輸出,變成該路徑專屬的 RESTful API(每個頁面都有自己的 endpoint)。Next.js 在做 SSR 的時候就去 call 這支 API 拿資料。這樣一來,真正要改寫的範圍就可以鎖定在 Jinja / Handlebars 轉 JSX 這件事上。
Runtime 的部分我們選擇先不動它,Next.js SSR 跑完之後,用 useEffect 搭配 dynamic import 把原本的 jQuery runtime 載進來,讓 scope 盡量限縮在架構面的調整。
障礙
如何上線
轉換前後路徑要保持不變,比如說 /profile 要無縫從 Jinja 變成 Next.js。但麻煩的是,Next.js 的流量是 Load Balancer 在管的。也就是說,/profile 轉成 Next.js 上線之後,還得去更新 Load Balancer 設定,把流量導過去。這中間從上線到 Load Balancer 設定生效,會有一段 downtime。當然也可以不要立刻砍掉舊頁面,等流量確定切過去再砍,但這樣就得反覆跑「做 Next.js 頁面 → 改 Load Balancer → 砍舊頁面」的循環,不只花時間,而且做新頁面跟砍舊頁面的程式碼會散在不同 PR 裡,很難對照。
所以我想了個方法:在 Flask 的 404 handler 偷偷把請求 proxy 去 Next.js。這樣一來就可以無縫轉換了,唯一的代價是在 Load Balancer 更新之前,頁面載入會慢那麼一點點。不過這只是暫時的,等所有路徑都轉完之後,proxy 就可以拿掉了,Load Balancer 也會預設指向 Next.js。
Global CSS
舊頁面是用 global CSS 來做網站的 UI,Next.js 則是用 MUI。Next.js 有個限制:global CSS 只能從 app.tsx 載入,一載進去就全部頁面都會吃到。也就是說,Next.js 的頁面也會被 global CSS 波及。
這題沒有什麼漂亮的解法,最後的折衷方案是:保留舊的 Webpack build pipeline 專門來 build CSS,然後讓 Next.js 去讀 Webpack 產生的 manifest.json,在改寫過的頁面上用 HTML link tag 載入對應的 global CSS。這個做法有個眉角:改寫成 Next.js 的頁面跟原生 Next.js 頁面之間切換時,得做 full-page reload,這樣樣式才能正確載入(原本 Flask 跟 Next.js 之間的切換就已經是這樣)。
網址格式
有些頁面是看網址裡有沒有特定片段(像是 /v/)來判斷的,但前面片段的數量不固定,例如 /foo/bar/buz/v/123 跟 /foo/bar/v/123 都是影片頁。這種規則在 Next.js 根本對不上,非得改格式不可。以前面影片頁的例子來說,後來改成 /videos/123?topic=foo/bar,然後把舊路徑 redirect 到新路徑。
進行方式
開發
照著規劃好的階段一頁一頁遷移,做完一個階段才進到下一個。
Code Review
簡單的頁面就交給 AI 幫忙 code review,複雜的頁面才會請其他工程師來 review。
在均一平台,我們可以使用多種 AI 工具來幫助開發。在遷移過程當中我主要使用 Claude Code 開發,完成後交給 GitHub Copilot 或 GPT 進行 review。
測試
均一平台沒有 QA。簡單的頁面我自己驗,複雜的就請其他工程師夥伴或 PM 幫忙測。
時間線
- 2025 年 8 月:第一階段開跑
- 2025 年 9 月:第二階段開跑
- 2025 年 10 月:第三階段開跑
- 2026 年 5 月:第三階段完工!(84 個路徑全數轉換完畢 🎉)
成果
- 自建的 Python build pipeline 正式退役,Webpack 現在只管 build 舊頁面的 CSS,其他全部搬到 Next.js 了。所有路徑在開發時都有 HMR,dynamic import 跟 npm 套件也都能用了。
- SSR 統一交給 Next.js 處理。
- BFF 架構讓前後端正式分家。
- Load Balancer 預設指向 Next.js,之後新頁面上線再也不用去改設定了。
- 前端檔案結構變清爽了,兩套 ESLint 規則也合併成一套。
- 順手清掉了一些古早味的寫法,像是前端用 Ajax 去撈 HTML 再塞進頁面,或是用 iframe 在不同頁面之間共用區塊。
| Framework | Template Engine (Server Side) | Template Engine (Client Side) | Build pipeline |
|---|---|---|---|
| Next.js | React | React + Handlebars | Webpack (for legacy CSS) + Next.js |
結語
搬到新架構之後,維護跟開發都輕鬆了不少,舊技術的範圍也被縮到各個獨立的頁面裡,之後想一個一個處理就容易多了。現代化工具帶來的不只是更多可能性,也默默幫我們擋掉了很多開發中可能踩到的坑。相信接下來的開發之路,會走得更順暢一些。
感謝
感謝在過程中參與的工程師夥伴,沒有你們的幫助這個困難的任務是無法被完成的。
- 王怡華 Eva Wang
- 鐘揮凱 Frank Chung
- 李宥辰 Isac Lee
- 謝依真 Kim Hsieh
- 郭亭劭 Patrick Gou
- 陳致睿 Ray Chen
- 吳先祐 Shian-Yow Wu
- 江宜陞 Yison Jiang
(依照英文名字排序)
編輯|陳冠宇 Jas Chen






