模組一｜現況盤點與立案（Day 1–5）

先給你三個數字，全部是我自己跑指令量出來的：

• 342 個 Vue 元件，總共 103,870 行。全庫測試檔數量：1。
• 父元件直接伸手進子元件呼叫方法：330 次，分布在 132 個檔案。
• 掛在全域的工具有 11 個，其中 8 個六年來從沒被用過，但沒人敢刪。

這是一個 Vue 2 後台在六年之後的樣子。它每天都在服務真實使用者，而且還在賺錢。

這 30 天，講的是我們怎麼把它升級到 Vue 3。

先講清楚我是誰

這不是「我如何重構了一個大型專案」的英雄故事，因為那不是事實。這是一個團隊做的事。

整件事的方向主要由團隊裡一位資深同事定調，而我是實際動手的成員之一：搬了模組、寫了頁面、修了 bug，也在共存期兩邊系統都維護過。

所以這 30 天有兩種身分交錯：動手的人，以及一直在追問「為什麼要這樣做」的人。

後者才是這個系列真正的來源。因為很多決策當下我只是照著做，是後來回頭整理紀錄，才看懂它們為什麼是對的，有些甚至到現在我還不確定對不對，那些我也會寫出來。

這是一份觀察筆記，不是教學

我不打算憑印象寫。這個系列裡出現的每一個數字，我都會實際跑指令量一次：多少行、多少檔案、哪個檔案被改過幾次。git 記了六年，它比任何人的記憶都可靠。

每篇的結構固定：

1. 現象      我觀察到什麼（用實測數字或 git 紀錄開場）
2. 我們怎麼做  團隊實際的處理方式，以及我後來才理解的原因
3. 代價      這個做法的反面：沒解決什麼、犧牲了什麼
4. 帶走什麼   給你可以直接用的判斷準則

第 3 段每篇都會有。沒有代價的決策不值得寫，那通常代表我沒看懂。

回頭看開場那三個數字

「342 個元件，1 個測試檔」 這件事我在任何會議裡都不需要解釋，所有人都懂它的意思：任何人改任何東西，都只能靠肉眼和運氣。 這個數字後來決定了整個遷移策略：為什麼不敢一次大改、為什麼要一塊一塊搬。

「330 次伸手進別人家裡」 講的是元件之間怎麼互相影響。父元件不只是「使用」子元件，它還「知道」子元件內部有哪些方法。這代表你改一個子元件的方法名，可能有五個地方在半夜壞掉，而且沒有任何工具會告訴你。Day 2 會展開。

「11 個全域工具，8 個沒人用」 最有意思。沒人刪的原因不是懶，是你沒辦法證明它沒人用，全域的東西沒有 import 關係可以追。Day 4 會專門講。

還有一個沒放進開場、但同樣重要的：這其實是兩套系統。 當年為了趕時間，有人把第一套整包複製一份改成第二套。六年後我去比對，有 20 個檔案一字不差，另外 33 個差不到十行，而那些「差幾行」的，代表有人改了一邊、另一邊沒跟上。Day 3 會給你兩個很具體的例子。

那，為什麼要重構？

既然講到這裡，動機也要說清楚。我把它拆成三層，由外而內：

1. 維護性。 同一個需求要在兩個 repo 各做一次，改完驗兩次。而且如同現象二，兩邊已經開始長歪。

2. 技術棧壽命。 主框架停在六年前的版本，生態裡的新東西一個都用不了，安全性更新拿不到。而且很現實的一點：招人的時候，沒有人想接手維護 Vue 2。

3. 開發體驗。 一次建置要吃 6GB 記憶體、開發伺服器慢到大家不敢重跑、沒有型別所以 IDE 幫不上忙。這些單看都是小麻煩，但它們每天都在課稅。

「想用新技術」算不算好理由？算，但它必須能翻譯成上面三層的其中一層，否則在會議室裡撐不過三個追問。

花了多久？兩個相差三倍的答案

如果我說這件事做了兩年，你大概會直接關掉這篇。所以要先拆開講。

核心重構期：每套系統各約六個月。 其中一套在第四個月就打出了第一個正式版本標記，六個月完成主體，第七個月的開發量直接掉到前一個月的三成。另一套系統規模大一倍，第六個月才打出第一版。

而且兩件事是接力進行的：第一套開始收斂的那個月，正好是第二套起步的那個月。

完整落地：時間長了三倍以上。 剩下的都是驗收修正、新舊共存、舊系統下線，以及永遠不會結束的持續重構。

所以「重構要多久」這個問題，正確的回應是反問對方在問哪一段。談預算講六個月，談風險講兩年。

最貴的那一段：新舊兩套同時上線

這是我覺得最少人談、成本卻最高的一件事：新系統上線後，舊系統沒有立刻關掉。

兩套後台同時對外提供服務，使用者被分批請到新系統，前後共存了一年以上。原因很實際：他們是外部單位，你不能挑一個週二早上通知所有人「明天換介面」。

而共存不等於「舊的凍結」。攤開開發量會看到一個刺眼的畫面：共存期間有一段時間，舊系統的開發量比新系統還多。那段時間維護的是兩套活著的產品，任何新功能都要做兩次，否則沒有人有動機切換。

所以整場重構真正的終點，是舊系統最後一次改動的那天，不是「新系統做完」那天。

技術棧位移總覽

表格裡有幾個名詞現在看不懂沒關係，後面每天都會拆開講。先給三個最影響理解的白話版：

• Options API / Composition API：Vue 元件的兩種寫法。前者把 data、methods 分類放好，後者讓你自由組合。差別不只是語法，Day 7 會講。
• 響應式底層：Vue 怎麼知道「資料變了、畫面要更新」的內部機制。Vue 2 和 Vue 3 用了兩種完全不同的做法，各有各的坑，Day 8 會講。
• monorepo：把好幾個專案放在同一個 repo 裡一起管理。好處是共用的東西只需要維護一份，正好對應我們最大的痛點。

30 天地圖

三個誠實邊界

一、這是團隊的成果，不是我的。 我會照實寫「哪些是團隊的決定」和「哪些是我自己的判斷」，也會區分「我當時就懂」和「我後來才理解」（後者佔多數）。

二、很多事情我是事後才想通的。 當下我只覺得「這個改起來很怕」、「這個看起來怪怪的」，說不出所以然。文章裡的分析是整理筆記時才成形的，不是當時的洞見，所以我不會把後見之明寫成先見之明。

三、程式碼是公司資產，所以全系列去識別化。 不會出現公司名、產品名、業務領域專有名詞，程式碼片段都改寫成中性範例，開發歷程只用相對時間（第幾個月）而不給日期。

但專案規模的數字都是真的：多少個元件、多少行、某個寫法出現幾次，這些我一個都沒改，因為那是說服力的來源，而且任何一個活了六年的後台大概都長這樣。

明天 Day 2，從第一個現象開始：我怎麼把「這 code 很爛」翻譯成一份會議室裡拿得出手的清單。會給六個維度、六段可以直接複製的指令，以及一個讓我改變優先順序的交叉比對：最長的六個檔案，正好就是被改最多次的六個檔案，一個都沒漏。