Claude Code 處理 dependency 升級：major version bump 點安全行、breaking change 點處理

情境

你係一間香港 agency 嘅 freelance dev。新客戶交咗一個 5 年舊嘅 Next.js codebase 畀你接手 —— 原本團隊散咗，老闆要你 6 個禮拜內推出兩個新功能。

你 git clone + npm install，第一輪 warning：

• React 17（current 19）
• Next.js 12（current 15）
• Node 16（你 local 跑緊 22，舊版 deprecated 兩年）
• 47 個 transitive dependency 有已知 CVE

老闆問：「使唔使升級 framework？」你心裡知答案係要，但每次 major bump 都恐怖：

• Changelog 50 頁，唔知邊條 breaking change 影響到你個 codebase
• 升完跑 next dev 死喺一啲莫名其妙嘅 error，stack trace 指向 node_modules 深處
• 試改一個 file → 連帶 5 個 file 都要改 → 改完再壞 3 個
• 半日就過咗，連第一個 page 都未行得返

呢個規律嘅根本問題：major version bump 唔係「一個 command 嘅事」，係一個要 有系統咁逐步重構嘅工程 —— 但 changelog 寫得似查閱用嘅技術文件、唔係一份升級攻略。

Claude Code 啱呢類嘢：佢可以消化 changelog、掃描你個 codebase、具體指出你邊度會 break、逐個處理。呢篇示範一套受控升級流程，React 18 → 19 / Next.js 14 → 15 / Node 18 → 20 都通用。

跟住做

1. 升級前評估（15 分鐘）

升之前要知道你會撼到咩。唔好直接跑 npm install react@19。

開一條獨立 branch：

git checkout -b upgrade/react-19

落第一個 prompt：

我想升級 React 18 → 19。麻煩你：
1. 抓 React 19 release notes + migration guide
2. 掃描我個 codebase（特別係 src/）
3. 列出我具體 codebase 入面會 break 嘅地方，唔好籠統講
4. 估個工作量範圍（細 patch / 中度重構 / 大手術）

Claude 會：

• 讀官方 changelog（如有 WebFetch 工具）
• grep 你個 codebase 揾出受影響嘅 API：useRef 寫法、forwardRef、useTransition 新 signature、<Context> provider 寫法等
• 出一份 markdown 報告：邊個 file、邊一行、對應邊一條 breaking change 規則

呢一步係防止「升咗先諗」嘅最大保險。如果報告出嚟係 80 處都要改，你可以同老闆攤牌：呢個唔係 1 日工作，係 3 日。

⚠️ Claude 整理嘅 changelog 唔係 100% 齊全。將佢當作 初步分流，唔係最終定案。

2. 獨立 branch + 安裝（10 分鐘）

確認個計劃之後先至裝。

# 鎖死 Node 版本先（用 .nvmrc / volta / asdf）
echo "20" > .nvmrc
nvm use 20

# Install 新版
pnpm add react@19 react-dom@19
# 或 npm install react@19 react-dom@19

⚠️ 唔好順手 npm update —— 你只係想升 React，唔想連 50 個 transitive dependency 都一齊飛。Major bump 一次處理一個 framework，先至 isolate 到問題根源。

跑第一輪 sanity check：

pnpm typecheck
pnpm build

預期會死。死法越具體越好（type error > runtime crash > 靜悄悄嘅 regression）。

3. 同 Claude 逐條分流 breaking change（25 分鐘）

將 error log 整段交畀 Claude：

typecheck 跑完出咗呢一堆 error（貼 stack trace）。
參照 step 1 個 migration plan，逐個 file 處理：
- 先解釋點解會 break
- 再出最精簡嘅 diff
- 唔好一次過改 10 個 file，1 個 1 個嚟畀我睇

關鍵：逐個 file 批准。Claude 會傾向「一氣呵成」全部改晒，但 dependency upgrade 出錯嘅代價高 —— 你需要每個 diff 都睇過。

Claude Code 嘅 Edit 工具會逐個 file 問權限，照常按 Yes / No 即可。每改完一個 file，重新跑 typecheck，確認 error 數量下降、無新 error 加入。

常見陷阱：

• 自動修正「過頭」：Claude 試將一條規則套去 5 個 file，但其中 2 個 file 嘅情況唔同 → 反而 break。睇到「我幫你順手連埋呢度都改」時要警惕。
• Lockfile 各有各亂：唔同 collaborator 用唔同 package manager 會出唔同 lockfile。揀一個（pnpm-lock.yaml 為主），刪其他。
• Peer dependency 黑洞：React 19 升完，@testing-library/react / next-themes 等都要跟住升。Claude 識辨呢條鏈，但唔好盲信 —— 每個 peer 都係一輪小升級。

4. Regression smoke test（10 分鐘）

Typecheck + build 過 ≠ 行得起。

pnpm dev
# 開瀏覽器，跑一次最關鍵嘅 user flow

最少跑：

• Homepage 載入
• 一個 form 提交
• 一次 client-side navigation
• 一個 data-fetching page（SSR / RSC）

如果有 E2E test：

pnpm test:e2e

冇 E2E？同 Claude 講：

我冇 e2e test。麻煩寫 3 個 Playwright smoke test，覆蓋：
1. Homepage 載入無 console error
2. 主要 navigation link 全部 click 得通
3. 一個有代表性嘅 form 可以提交成功

跑過、綠燈、再 merge。

git checkout main
git merge upgrade/react-19

🎉 Major bump 一次完成、無 regression、留低一條清楚嘅紀錄（branch history）。

變化

變化 1：Node major version bump（runtime 改變）

升 Node 18 → 20 / 22 同 framework bump 唔同 —— 影響嘅唔止 application code，連 build tool、CI image、Docker base 都要跟。

Claude 嘅角色：

我要升 Node 18 → 20。
1. 列出 Node 20 對比 18 嘅 breaking change（特別係 fetch、test runner、ESM）
2. 掃描我個 codebase + package.json + Dockerfile + .github/workflows
3. 出 checklist：邊個 file 要改、邊個 CI step 要換 base image

關鍵額外步驟：

• 改 .nvmrc / volta 設定
• 改 Dockerfile FROM node:18-alpine → node:20-alpine
• 改 GitHub Actions node-version: '18' → '20'
• 確認 package.json 入面個 engines field 跟住升

Runtime bump 嘅麻煩位係環境唔同步：local 升咗、CI 未升 → 喺 local 綠燈、喺 CI 紅燈。Claude 幫你一次過掃晒所有 config file。

變化 2：Framework major bump（Next.js / Vue / Nuxt 等）

Framework bump 影響面最大 —— routing、data fetching、build pipeline 都可能換。

以 Next.js 14 → 15 為例，重要嘅 break：

• Async request API（cookies() / headers() / params 變 async）
• Caching 預設由 cache-by-default 轉 fetch-fresh-by-default
• Turbopack 轉穩定版

呢類 bump 用 Claude Code 嘅 codemod 做法：

Next.js 15 將 cookies() 改做 async。
1. 揾我所有用到 cookies() / headers() / params 嘅地方
2. 一個一個 file 改：加 await + 將上游 function 轉 async
3. 順住 type error 一路向上推

Claude 識追 type error 點樣一層層傳上去 —— 你改一個 server component → 用佢嘅 page route 要變 async → page 嘅 metadata generator 要變 async → 一路向上。逐個 file 改、逐個 file 批准，30 分鐘搞掂一條本來要 debug 半日嘅鏈。

變化 3：Database driver bump（資料完整性額外重要）

Driver bump（pg、mysql2、Prisma、Drizzle 等）係風險最高嘅 dependency upgrade —— 一條 query 行為微微唔同 = production 資料損壞。

額外步驟：

我要升 Prisma 5 → 6。麻煩：
1. 列出 breaking change，特別點出任何會影響 query 結果嘅
2. 掃描我所有 .prisma migration + 所有 prisma.*.create/update/findMany
3. 列出邊啲 query 嘅行為可能微妙變化（date handling / null handling / transaction isolation）

Driver bump 一定要做嘅步驟：

• 喺 staging environment 跑完 1 個禮拜，先上 prod
• 跑 schema diff（prisma migrate diff）對比 prod schema
• 跑一輪唯讀 smoke test（揀有代表性嘅 query，比較新舊 driver 嘅 output）
• 備好 rollback plan：lockfile + 釘死舊 driver 版本，10 分鐘可以還原

⚠️ Claude 識讀 changelog + 掃 code，但 production data 嘅 edge case 佢唔識。Driver bump 必須人手檢視 staging dataset。

拆解：點解 work，同邊度會爆

跟到上面就已經用得。下面呢段係畀**想由「升完跑得起」做到「升完三個月都唔會半夜爆 prod」**嘅人——初學者可以跳過，唔影響你跟住做。

Dependency upgrade 最危險嘅地方係：最大鑊嘅問題，唔會喺你個 terminal 紅燈出現。Typecheck 綠、build 綠、page 開得到，你以為穩陣，但有幾類嘢會靜悄悄等你 merge 完先發作。呢幾個位你要預咗：

1. Claude 講嘅 breaking change，可能係「佢以為」嘅版本 Claude 嘅知識有 cutoff，而 framework 升得快。你問佢「React 19 點升」，佢答嘅可能係某個時間點嘅理解——RC 同正式版之間 API 改過、minor patch 又改過。

• 會出事：佢叫你跟一條根本已經唔存在嘅 migration step，或者漏咗一條最新先加嘅 breaking change，你照跟、升完先發現對唔上。
• 點救：逼佢用 WebFetch 抓官方嗰一個 minor 版本嘅 release notes，唔好淨係靠記憶；每條 claim 同你裝咗嘅實際版本號（睇 lockfile）對返。step 1 嗰份報告當分流，唔當聖旨。

2. grep 掃唔到嘅用法，先至係漏網之魚 step 1 靠掃 code 揾受影響嘅 API，但 grep 類掃描只睇到「字面寫成咁」嘅用法。

• 會出事：你經 re-export 包過一層嘅 API、用字串砌出嚟嘅 dynamic import、codegen 出嚟嘅 file、或者 node_modules 入面某個冇升嘅 library 內部仲用緊舊 API——全部掃唔到，升完喺 runtime 先爆。
• 點救：唔好當「報告冇列到 = 安全」。叫 Claude 連 re-export 同 barrel file（index.ts 嗰類）一齊追；最後實際行一次成個 app 嘅關鍵 path，唔好淨係信靜態掃描。

3. Typecheck 綠燈 ≠ 行為冇變 最陰公嘅 breaking change 唔會改 type signature，只改行為——上面提過 Next.js 15 個 caching 預設由 cache-by-default 轉去 fetch-fresh，type 完全唔變。

• 會出事：build 全綠、demo 睇落正常，但上 prod 之後 cache 行為變咗，要麼資料舊、要麼 origin 被打爆，幾日後先有人 report。
• 點救：升之前列一張「行為類 breaking change」清單（caching、null / date handling、預設值改變），逐條落 staging 用真實流量觀察；單靠 typecheck 同 demo 揾唔到呢類問題。

4. Codebase 太大，Claude 中途會「斷片」 5 年舊 codebase 塞唔晒入一個 context window。分幾次 session 改，Claude 唔會記得上一 session 點改。

• 會出事：同一條 migration 規則，頭 20 個 file 用 A 寫法、後 30 個 file 用 B 寫法，兩種都 compile 到，但風格分裂、日後接手嘅人一頭霧水；更弊係佢「以為」改晒，其實漏咗冇入 context 嗰批。
• 點救：將 migration plan 寫低做一份 checklist file commit 入 repo（呢篇尾段都建議咁做），每次開新 session 都餵返佢做 anchor；改完用 grep 數一數舊 API 嘅剩餘數量，跌到零先算完，唔好靠感覺。

呢幾個位，就係「升完跑得起」同「升完三個月都信得過」之間嘅距離。

一個心態

Dependency upgrade 嘅深層體會：bump 唔係「一個動作」，係「一段過程」。

未有 Claude Code 之前，香港中小企 / freelance dev 嘅慣性係 唔升：

• 升要 1 日，1 日嘅 invoice 客戶唔肯畀
• 升完 break，客戶投訴「你搞壞咗我嘢」
• 唔升又有 security CVE，但「未爆就唔關事」

呢個拖延嘅累積成本巨大 —— 5 年後變成冇人維護得到嘅 codebase，客戶要重寫，重寫報價 30 萬。

Claude Code 改變咗條數：1 小時受控升級（升前評估 + 獨立安裝 + 分流 + smoke test）取代咗 1 日驚青升級。1 小時報得出價、做得起、有紀錄可查。

換個角度睇：dependency upgrade 由「高風險大手術」變成「日常保養」。每兩個月做一次、每次升一兩個 framework，你個 codebase 永遠喺最新版減一，CVE 永遠喺修緊，交接永遠順手。

最後提醒：

• ✅ 一次升一個 framework。Lockfile diff 細、容易 isolate 到問題根源。
• ⚠️ 唔好相信「Claude 話 OK」就 merge。Runtime smoke test 同 staging 觀察期慳唔到。
• 🎯 將 migration plan commit 入 repo（docs/upgrades/react-19.md）。下個 dev 接手見到有紀錄，唔使由頭再摸索一次。

下個鐘揀你個 stack 入面最舊嗰個 dependency，開條 branch 試一輪受控升級。3 個月後你個 codebase 健康程度會係另一個級數。