Spaces:
Sleeping
Sleeping
|
Download guide/12-debugging-guide.md from WorstCardGame/worst-card-game: direct link, hf CLI and curl.
- Browser
- Download file 9.12 kB
-
https://huggingface.co/spaces/WorstCardGame/worst-card-game/resolve/main/guide/12-debugging-guide.md
- Command line
-
hf download hf://spaces/WorstCardGame/worst-card-game/guide/12-debugging-guide.md
-
curl -L -o 12-debugging-guide.md https://huggingface.co/spaces/WorstCardGame/worst-card-game/resolve/main/guide/12-debugging-guide.md
9.12 kB
12 — 全端除錯指南(Frontend → Backend)
一套可照做的除錯流程。核心觀念:先分層定位,再深入——不要一看到畫面怪就改前端。 本專案的結構讓除錯很有優勢:
battle-core是決定性純函式,大多數規則 bug 可以不開瀏覽器、用單元測試重現。
0. 四層架構(先記住 bug 可能落在哪一層)
[web 前端] 顯示 / 互動 / WS 收發 packages/web/src (App.tsx, PvpScreen.tsx, pvpClient.ts)
│
[server 後端] 連線協調 / 房間 / 計時 / 反作弊 packages/server/src (server.ts, pvpHub.ts, pvpMatch.ts, ghostService.ts)
│
[battle-core] 純規則 / 決定性 / 三模式共用 packages/battle-core/src (engine, player, effects, pvpResolve...)
│
[build/部署] dist 編譯 / cards.json / HF Spaces
第一鐵則:UI 顯示錯 ≠ 規則錯。 先判斷在哪一層,80% 的時間省在這一步。
1. 分層定位表(症狀 → 嫌疑層 → 先查哪裡)
| 症狀 | 最可能的層 | 先查 |
|---|---|---|
| 卡牌效果數值不對(ATK/DEF/抽牌/硬幣) | battle-core | effects.ts(runOps)、data/cards.ts、player.ts |
| 只有 PvP 錯、單人正常 | server 協調層 | pvpResolve.ts、pvpMatch.ts、pvpHub.ts |
| 只有鬼影(第12關)錯 | opponent/ghost | opponent.ts(ghost 重建)、engine.ts turnLog |
| 畫面數字與實際狀態不符 | web 顯示 | App.tsx/PvpScreen.tsx 的 render |
| 點了沒反應 / 狀態沒更新 | web 事件或 reducer | pvpClient.ts reduce、dispatch、WS 有沒有送出 |
| 計時 / 倒數怪 | server 計時 + web | pvpHub deadline、pvpClient PHASE_START、useCountdown |
| 連線斷 / 配對失敗 | server WS | server.ts /ws/pvp、pvpHub 房間 |
| 改了程式線上沒變 | build/部署 | dist 是否重建、HF Spaces build log |
最強定位法 —「哪些模式出現?」(三模式共用同一份 battle-core):
- 三模式都錯 → 幾乎一定在 battle-core。
- 單人對、PvP 錯 → 在 PvP 協調層(
pvpResolve/pvpMatch/pvpHub),不是規則。 - 單人對、鬼影錯 → 在 ghost 重建 / turnLog。
2. battle-core 層(規則)— 最該優先、最好查
為什麼先查這層:純函式、決定性、零相依 → 可以用最小重現測試抓,不必開瀏覽器、不必連後端。
重現步驟:
- 寫一個最小 golden test(
packages/battle-core/test/):固定 seedcreateGame({classType:"WARRIOR", seed: N})→ 套一串step(s, action)→expect狀態。 npm run test:watch -w @wcg/battle-core(存檔即跑)。- 用
replay(seed, actions)(engine.ts)驗決定性:同輸入必同輸出;不同則代表有非決定性來源(多半是誤用Math.random())。
這層的高頻 bug:
- 出牌順序(必須先移出手牌再結算;
09 G3/G6)。 - 旗標結算時機 / 沒清除(出傷時
onDealDamage、回合末onTurnEndResolve、重置resetForNextTurn)。 - 亂數消費順序(
effects.ts的 DRAW/RANDOM_*、洗牌;見08 §6)。 handCount/handEmpty是否含本張。
檢查清單:
- 能用 golden test 穩定重現嗎?(不能穩定 = 非決定性,先抓亂數)
- 同 seed 跑兩次結果一致嗎?(
replay) - 數值是否與
02/08設計一致?
3. server 層(連線 / 協調 / 計時)
單元測試(首選,完全可控):pvpHub/pvpMatch 的相依都可注入——
genSeed/now/scheduler注入假值(見test/pvpHub.test.ts的 harness:假send收訊息、假scheduler不真的計時)。- 用
types(msgs.A)看伺服器送了哪些訊息、順序對不對(PHASE_START / RESOLVE_RESULT / DRAFT_CHOICE…)。
e2e:test/pvpWs.e2e.test.ts 開真 WebSocket,驗端到端收發。
反作弊 / 對局重算:用 replay(seed, actions) 重跑,對比 server 記的 actionLog。
這層的高頻 bug:
- 計時:
deadlineTs(改用durationMs由 client 自算,避免時鐘偏差)。 - 四相狀態機相位轉換(PLAN→LOCK→RESOLVE→ADVANCE)。
- draft 流程(DRAFT_CHOICE/PICK/WAIT、雙方完成才開戰)。
- 斷線 / 投降 / 房間清理。
檢查清單:
- 用假 scheduler/seed 能單測重現嗎?
- 伺服器送出的訊息序列符合預期嗎?(印
msgs) - seed 有沒有不小心外洩給 client?(
JSON.stringify(msg)不該含 "seed")
4. web 層(前端)
先分清三種前端 bug:
- 顯示 bug:狀態對、畫面畫錯 → 看 render(
App.tsx/PvpScreen.tsx)。 - reducer bug:收到訊息但 state 沒更新對 → 看
pvpClient.tsreduce(漏 case?)。 - 事件沒送:點了沒反應 → dispatch /
send沒被呼叫,或 WS 沒連上。
工具:
- React DevTools 看
game(單人 GameState)、usePvp的state。 console.log印GameState/PvpView;單人甚至可在瀏覽器 console 直接 import 跑battle-core(因前端就 import 它)。- 瀏覽器 DevTools → Network → WS:看
/ws/pvp的 frames(收發的DRAFT_CHOICE/PHASE_START/RESOLVE_RESULT…),確認「是後端沒送」還是「前端沒處理」。
這層的高頻 bug:
reduce漏處理某訊息類型(狀態不動)。- 倒數時鐘(
useCountdown用deadlineTs - Date.now();時鐘偏差)。 - React key 重複 / stale closure。
- 顯示用衍生值算錯(例:
displayNextReq、pileView)。
檢查清單:
- 問題是「沒收到訊息」(看 WS frames)還是「收到沒更新」(看 reduce)還是「更新了沒畫對」(看 render)?
- state 在 React DevTools 裡是對的嗎?
5. build / 部署層
「明明改了卻沒效果」最常見的兇手。web/server 吃的是**編譯後的
dist**。
- dist 過期:改了
battle-core/src一定要npm run build(或至少 build battle-core)。驗證法:grep你的新程式碼/註解是否進了packages/battle-core/dist/*.js;或比對src與dist的 mtime。 - cards.json 沒重產:改
data/cards.ts後要npm run gen:cards -w @wcg/battle-core。 - HF Spaces:看 Space 的 build log(Docker);
app_port 7860;部署細節見../DEPLOY.md。 - 健康檢查:
GET /api/health應回{ ok: true, ghosts: N }。
檢查清單:
-
npm run build跑過了嗎?dist 有你的改動嗎? - 線上版本 = 最新 commit 嗎?(GitHub/HF 都 push 了?Spaces 重建完成了?)
6. 工具箱(常用指令)
# 在 repo 根目錄 worst-card-game/
npm run typecheck # 全套件型別檢查(先跑,最快抓錯)
npm test # 全部測試(battle-core + server)
npm run test:watch -w @wcg/battle-core # 規則層 watch 模式(改卡/改效果時)
npm run build # 重建 dist(web/server 吃 dist)
npm run gen:cards -w @wcg/battle-core # data/cards.ts → cards.json
git diff/git log --oneline:對照「上次能動」與「現在」之間改了什麼。- 全文搜尋症狀關鍵字(訊息型別、旗標名、卡 id)快速定位。
7. 標準除錯流程(SOP)
flowchart TD
S([遇到 bug]) --> M{哪些模式會發生?}
M -- 三模式都錯 --> C[battle-core:寫最小 golden test 重現]
M -- 只有 PvP --> P[server 協調層:pvpResolve/hub 單測 + WS frames]
M -- 只有鬼影 --> G[opponent/ghost 重建 + turnLog]
M -- 只有畫面 --> W[web:WS frames? reduce? render? 三選一]
C --> R{能穩定重現?}
R -- 否 --> ND[抓非決定性:Math.random? 用 replay 比對]
R -- 是 --> FIX[定位根因 → 修]
P --> FIX
G --> FIX
W --> FIX
ND --> FIX
FIX --> T[加/更新 golden test 釘行為 → typecheck+test 全綠]
T --> B[npm run build 重建 dist → 三模式手測]
B --> D[commit/push → 線上驗證]
D --> E([關閉])
8. 實戰案例(本專案真實 bug,當教材)
案例一:「好的開始沒抽」
- 症狀:單人打出後手牌數不增。→ 分層:三模式皆有 ⇒ battle-core。
- 重現:golden test「手牌滿 5 時打出抽牌卡」→ 抽 0。
- 根因:效果在「牌仍在手牌」時結算,
hand.length>=5卡住 DRAW。 - 修:出牌先移出手牌再結算(對齊原版)。
- 驗:測試 + 三模式;順手發現 5 個測試把舊 bug 當規格(改成正確值)。
案例二:「PvP 時間有錯誤」
- 症狀:PvP 倒數不準。→ 分層:只有 PvP + 顯示 ⇒ web/server 計時。
- 根因:server 送絕對
deadlineTs(server 時鐘),client 用自己時鐘倒數 → 偏差。 - 修:server 改送剩餘時長
durationMs,clientDate.now()+durationMs自算。
案例三:「改了卻沒變」
- 先驗
dist是否最新(grep新註解進 dist?mtime?)→ 排除 build/部署層,再深入。
9. 回報 bug 的最小資訊(給未來的你/隊友)
附上這些,任何人都能快速重現:
- 模式(單人 / 鬼影 / PvP)、seed(若有)。
- 操作序列(出了哪些牌、按了什麼)。
- 預期 vs 實際。
- console / WS frames log(PvP 尤其要 WS frames)。
- 線上版本 commit / 本機
git log -1。