如果讓我把《異環關于我在異世界撿到青梅竹馬這件事》做成一個可玩的互動劇情第一件事不是畫女主立繪也不是寫一萬字文案而是先想清楚劇情在代碼里到底存成什么。很多人做文字冒險游戲習慣把劇情直接寫在組件里點一下按鈕更新一下 text再點一下再更新。這種寫法在三個節點的時候很好用等劇情超過三十個節點、開始出現分支和好感度變量時組件會膨脹到無法維護。更合理的做法是把劇情當成數據把界面當成渲染器把狀態管理當成推進器。這樣劇本可以單獨維護后續加配音、加立繪、加多結局都只是換數據源和增加渲染能力不需要重寫業務邏輯。這篇文章以《異環》作為項目代號以“在異世界撿到青梅竹馬”作為示例劇情一步步搭建一個基于 React TypeScript Zustand 的互動劇情引擎。你可以把它理解為文字冒險游戲的“最小可運行骨架”也可以直接作為后續做 Galgame、視覺小說或敘事向小游戲的起點。文章會從劇情的數據結構講起然后搭建工程、編寫狀態管理和界面渲染最后補上存檔、條件分支、常見排錯和生產化建議。每一段代碼都可以直接復制到項目里運行但更重要的是理解每個節點字段存在的理由。1. 互動劇情的技術拆解把“撿到青梅竹馬”變成可計算的結構1.1 劇情不是一段長文本而是一張有向圖傳統的線性小說閱讀體驗是從第一行讀到最后一行讀者沒有選擇權?；觿∏椴灰粯油婕以陉P鍵節點做出的選擇會改變后續對話、角色好感度和最終結局。從技術角度看這就不是線性文本而是一張有向圖每個可停留的劇情片段是一個節點。一個對話說完后跳到哪個節點由next指向。一個選項節點包含多個分支出口每個出口也是一條邊。某些邊的顯示需要滿足變量條件比如好感度大于某個值。某些邊的觸發會修改變量比如選擇“叫出她的名字”后好感度 10。只要這張圖能穩定表達寫劇情的人只關心節點內容寫程序的人只關心節點如何被訪問。兩者通過一套約定好的數據結構解耦?！懂惌h》這個標題里“異世界”是舞臺“撿到青梅竹馬”是核心事件。用技術語言翻譯一下玩家從“街道醒來”這個節點出發進入“遇到熟悉身影”的對話遇到一個兩難選擇。選擇“叫出她的名字”會進入好感度上漲的相認結局選擇“表示不認識”會進入錯過結局。這就是一個最小的有向圖。1.2 最小數據模型節點、選項、動作和條件為了讓圖能夠被代碼執行我建議把節點設計成可辨識的類型。一個劇情系統通常只需要三種基礎節點export type StoryNode | DialogNode | ChoiceNode | EndingNode; export interface DialogNode { id: string; type: dialog; speaker: string; text: string; next?: string; onEnter?: StoryAction[]; } export interface ChoiceNode { id: string; type: choice; text: string; choices: StoryChoice[]; onEnter?: StoryAction[]; } export interface EndingNode { id: string; type: ending; text: string; } export interface StoryChoice { label: string; next: string; condition?: StoryCondition; effect?: StoryAction[]; } export interface StoryCondition { key: string; op: | ! | | | | ; value: number | string | boolean; } export type StoryAction | { op: set; key: string; value: number | string | boolean } | { op: add; key: string; value: number };這里有幾個容易理解錯的地方onEnter是進入這個節點時立刻執行的動作適合做“剛走進某個場景就觸發存檔點”或“一見到青梅竹馬就增加緊張值”這類邏輯。next只對對話節點有意義。如果對話節點沒有next就相當于這個節點是當前分支的終點。選擇節點自己不持有next它通過choices里的每個選項分別指向后續節點。condition不是“這個選項會觸發什么條件”而是“滿足什么條件時才顯示這個選項”。不滿足時當前選擇節點里仍然可以顯示其他選項。effect是選擇這個選項之后、跳轉之前立刻生效的動作。把動作從節點里拆出來是因為劇情文案經常要調整“什么時候加好感度”。寫成聲明式動作以后改好感度不需要改組件代碼只需要改數據。2. 從空目錄到可運行工程Vite React TypeScript 環境準備2.1 環境要求與依賴選擇在實際項目中我不會為了一個 Demo 手寫 webpack 配置。互動劇情項目本身邏輯并不復雜主要工作量在數據結構、狀態流轉和渲染交互上因此推薦用 Vite 快速搭建 React TypeScript 工程。推薦環境如下依賴版本建議說明Node.js18 或 20 LTSVite 5 需要 Node 18React18.x使用函數組件和 HooksTypeScript5.x提供節點類型約束Vite5.x開發服務器與構建工具Zustand4.x輕量狀態管理適合保存游戲狀態nanoid5.x生成歷史記錄 ID可選也可用 Date.nowZustand 不是唯一選擇。你也可以用 useReducer Context不過當項目出現存檔、歷史記錄、變量表和節點跳轉多處狀態聯動時Zustand 的寫法和調試成本更低并且只在狀態真正變化時觸發組件重渲染。2.2 初始化項目和目錄結構打開終端執行下面命令創建項目npm create vitelatest yihuan-story -- --template react-ts cd yihuan-story npm install npm install zustand安裝完成后把src下的文件整理成下面結構src/ ├── engine/ │ ├── types.ts # 劇情節點類型定義 │ ├── store.ts # Zustand 狀態管理 │ └── actions.ts # 動作執行、條件判斷工具 ├── data/ │ └── story.ts # 示例劇情數據 ├── components/ │ ├── DialogPanel.tsx # 對話渲染 │ ├── ChoicePanel.tsx # 選項渲染 │ └── HistoryPanel.tsx # 歷史記錄 ├── App.tsx ├── main.tsx └── index.css這樣分層的原因是data只放劇本engine只放邏輯components只放渲染。以后換劇本只需要改data/story.ts引擎和界面可以完全復用。2.3 跑通一個空頁面先修改App.tsx為一個最簡單的渲染容器確保依賴安裝正確import ./App.css; function App() { return ( div classNamegame-container h1異環互動劇情引擎/h1 p骨架已跑通。/p /div ); } export default App;運行npm run dev瀏覽器打開終端提示的地址如果能看到頁面文字說明工程環境正常。這一步檢查點很明確沒有紅色報錯終端沒有編譯異常瀏覽器控制臺沒有 404。3. 用數據驅動劇情定義《異環》示例故事和引擎核心3.1 先寫一段能跑通的示例劇本為了讓后面每一步都有實際效果我們先把開頭這一段劇情寫入src/data/story.tsimport type { StoryNode } from ../engine/types; export const storyMap: Recordstring, StoryNode { start: { id: start, type: dialog, speaker: 系統, text: 你在異世界的街道上醒來眼前是一塊寫著“歡迎來到異環”的路牌。, next: meet, }, meet: { id: meet, type: dialog, speaker: , text: “喂你怎么在這里我找了你半天。”, next: choice1, }, choice1: { id: choice1, type: choice, text: 你抬起頭看見一個熟悉的身影。, choices: [ { label: 叫出她的名字, next: recognize, effect: [{ op: set, key: affection, value: 10 }], }, { label: 表示不認識, next: stranger, effect: [{ op: set, key: affection, value: -5 }], }, ], }, recognize: { id: recognize, type: dialog, speaker: 青梅竹馬, text: “果然是你笨蛋你怎么會跑到異世界來”, next: ending_good, }, stranger: { id: stranger, type: dialog, speaker: 青梅竹馬, text: “啊……抱歉我認錯人了?！彼拖骂^語氣明顯失落。, next: ending_normal, }, ending_good: { id: ending_good, type: ending, text: 異世界的第一天你重新遇到了最重要的人。結局相認。, }, ending_normal: { id: ending_normal, type: ending, text: 你們擦肩而過。有些重逢只存在于異世界的偶然。結局錯過。, }, };這段劇情雖然不是完整故事但覆蓋了對話節點、選擇節點、選項效果和結尾節點。后續加入條件分支時往choices里加condition字段即可。3.2 Zustand 狀態管理讓節點跳轉變成可追蹤的“狀態遷移”游戲狀態可以拆成四部分currentNodeId當前處在哪個節點。vars全局變量表比如好感度、已收集物品、是否觸發過某個事件。history玩家經過的節點記錄用于回溯和顯示歷史對話。isCompleted是否已經到達結局。在src/engine/store.ts中實現核心 storeimport { create } from zustand; import type { StoryNode, StoryChoice, StoryAction } from ./types; import { storyMap } from ../data/story; import { applyActions, checkCondition } from ./actions; interface PersistedState { currentNodeId: string; vars: Recordstring, number | string | boolean; history: Array{ nodeId: string; choiceLabel?: string; time: number; }; } interface GameState extends PersistedState { isCompleted: boolean; goTo: (nodeId: string) void; selectChoice: (choice: StoryChoice) void; applyEnterActions: (node: StoryNode) void; reset: () void; save: () void; load: () boolean; clearSave: () void; } const SAVE_KEY yihuan-story-save-v1; const initialState: PersistedState { currentNodeId: start, vars: { affection: 0 }, history: [], }; export const useGameStore createGameState((set, get) ({ ...initialState, isCompleted: false, applyEnterActions: (node) { const actions node.onEnter ?? []; if (actions.length 0) return; set({ vars: applyActions(get().vars, actions) }); }, goTo: (nodeId) { const node storyMap[nodeId]; if (!node) { console.error([story-engine] 找不到節點: ${nodeId}); return; } const history [ ...get().history, { nodeId, time: Date.now(), }, ]; set({ currentNodeId: nodeId, history, isCompleted: node.type ending, }); get().applyEnterActions(node); }, selectChoice: (choice) { const nextVars applyActions(get().vars, choice.effect ?? []); set({ vars: nextVars, history: [ ...get().history, { nodeId: get().currentNodeId, choiceLabel: choice.label, time: Date.now(), }, ], }); get().goTo(choice.next); }, reset: () { set({ ...initialState, isCompleted: false, }); }, save: () { const state get(); const data: PersistedState { currentNodeId: state.currentNodeId, vars: state.vars, history: state.history, }; localStorage.setItem(SAVE_KEY, JSON.stringify(data)); }, load: () { const raw localStorage.getItem(SAVE_KEY); if (!raw) return false; try { const data JSON.parse(raw) as PersistedState; if (!data.currentNodeId || !storyMap[data.currentNodeId]) { console.warn([story-engine] 存檔節點不存在忽略存檔); return false; } set({ currentNodeId: data.currentNodeId, vars: { ...data.vars }, history: Array.isArray(data.history) ? data.history : [], isCompleted: storyMap[data.currentNodeId]?.type ending, }); return true; } catch (err) { console.error([story-engine] 存檔解析失敗, err); return false; } }, clearSave: () { localStorage.removeItem(SAVE_KEY); }, }));這里有幾個關鍵設計決定applyEnterActions和goTo分離是為了在跳轉后立刻執行節點的onEnter動作。如果你把動作放進goTo的同一個 set 里要注意動作需要基于最新狀態計算避免出現連續跳轉時變量覆蓋。每次選擇都先記錄選擇標簽再跳轉是為了后面歷史回看時能知道玩家當時點了哪個選項。load里做節點存在性檢查非常重要。一旦劇情改版舊存檔可能指向不存在的節點。此時直接恢復會導致白屏比較好的方式是返回false由界面提示玩家開始新游戲。3.3 動作執行和條件判斷不需要 eval 的安全寫法我見過不少劇情引擎用eval執行腳本字符串來修改變量雖然寫起來靈活但項目一旦引入玩家輸入或者外部數據eval就是安全隱患。這里使用結構化的動作和條件描述代碼寫起來稍長但足夠安全。在src/engine/actions.ts中實現import type { StoryAction, StoryCondition } from ./types; type Vars Recordstring, number | string | boolean; export function applyActions(vars: Vars, actions: StoryAction[]): Vars { let next: Vars { ...vars }; for (const action of actions) { switch (action.op) { case set: next { ...next, [action.key]: action.value }; break; case add: { const current next[action.key]; const base typeof current number ? current : 0; next { ...next, [action.key]: base action.value }; break; } default: console.warn([story-engine] 未知動作, action); } } return next; } export function checkCondition( condition: StoryCondition | undefined, vars: Vars, ): boolean { if (!condition) return true; const left vars[condition.key]; switch (condition.op) { case : return left condition.value; case !: return left ! condition.value; case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); default: return true; } }使用結構化條件后劇情數據變成這樣{ label: 告訴她你失憶了, next: sad_ending, condition: { key: affection, op: , value: 5 }, }條件字段不是必填項。沒有條件時選項永遠顯示。4. 渲染層把節點數據變成可點擊的交互界面4.1 對話面板和選項面板在App.tsx中根據當前節點類型渲染不同組件。先用最簡單的方式import { useEffect } from react; import { useGameStore } from ./engine/store; import { storyMap } from ./data/story; function App() { const currentNodeId useGameStore((s) s.currentNodeId); const isCompleted useGameStore((s) s.isCompleted); const goTo useGameStore((s) s.goTo); const selectChoice useGameStore((s) s.selectChoice); const reset useGameStore((s) s.reset); const save useGameStore((s) s.save); const load useGameStore((s) s.load); const clearSave useGameStore((s) s.clearSave); const node storyMap[currentNodeId]; useEffect(() { if (node?.type dialog node.next) { // 這里不自動跳轉等待用戶點擊“繼續” } }, [currentNodeId, node]); if (!node) { return ( div classNamegame-container p當前節點不存在可能存檔已失效。/p button onClick{() { clearSave(); reset(); }} 重新開始 /button /div ); } return ( div classNamegame-container div classNametoolbar button onClick{save}保存/button button onClick{() { if (load()) { // 存檔讀取成功后會自動更新 currentNodeId } }} 讀檔 /button button onClick{reset}重置/button /div {node.type dialog ( div classNamedialog-box div classNamespeaker{node.speaker}/div div classNametext{node.text}/div {node.next ( button onClick{() goTo(node.next!)} 繼續 /button )} /div )} {node.type choice ( div classNamechoice-box p classNamechoice-description{node.text}/p div classNamechoices {node.choices.map((choice) ( button key{choice.label} onClick{() selectChoice(choice)} {choice.label} /button ))} /div /div )} {node.type ending ( div classNameending-box p{node.text}/p button onClick{reset}重新開始/button /div )} {isCompleted p classNamecompleted-tip已到達結局/p} /div ); } export default App;注意上面的onClick{() goTo(node.next!)}中用了非空斷言因為node.next在 if 內已經判斷存在。更穩妥的寫法是抽出子函數避免 TypeScript 類型收窄問題。4.2 條件選項的隱藏邏輯上面的界面沒有處理condition。如果一個選項不滿足條件仍然顯示玩家點擊后會進入你不希望進入的劇情。正確做法是在渲染選項時過濾const availableChoices node.choices.filter((choice) checkCondition(choice.condition, useGameStore.getState().vars), );但在組件里直接讀取getState()不會觸發重渲染。更規范的方式是在組件里訂閱varsconst vars useGameStore((s) s.vars); const availableChoices node.choices.filter((choice) checkCondition(choice.condition, vars), );這樣當變量變化時選項列表會自動重新計算。4.3 歷史記錄讓玩家看到自己走過哪條路歷史記錄不一定是界面必需品但它是排查“玩家到底點了哪里”最好的工具。在 store 中我們已經保存了history現在可以渲染到側邊欄const history useGameStore((s) s.history); div classNamehistory-panel h2經歷/h2 {history.map((item, index) ( div key{${item.time}-${index}} [{item.nodeId}] {item.choiceLabel ? - ${item.choiceLabel} : } /div ))} /div這個簡單列表在開發階段很有價值。當劇情跳轉不符合預期時你只需要看歷史記錄就能確認玩家是不是在某個選擇節點進入了錯誤分支。5. 運行驗證從第一句話到結局把整個鏈路跑通5.1 正常流程驗證啟動項目后按以下路徑驗證頁面顯示“你在異世界的街道上醒來”。點擊“繼續”進入“”對話。點擊“繼續”進入選擇節點看到兩個選項。點擊“叫出她的名字”控制臺打印affection變為 10進入“果然是你笨蛋”。點擊“繼續”進入“結局相認”頁面出現“已到達結局”。打開 DevTools 的 Application 面板查看 Local Storage確認yihuan-story-save-v1在點擊保存后出現。點擊“重置”確認頁面回到開頭且存檔仍存在直到點擊“存檔”覆蓋或“清除”刪除。5.2 添加條件分支讓同一個節點在不同好感度下顯示不同選項為了驗證條件引擎在choice1的choices中增加一個只有好感度足夠高時才出現的選項{ label: 一把抱住她好感度 5, next: hug_ending, condition: { key: affection, op: , value: 5 }, effect: [{ op: add, key: affection, value: 5 }], }在初始狀態下affection為 0這個選項不會顯示。當玩家先走一遍“叫出名字”流程保存后重置并讀檔affection變成 10此時再進入選擇節點這個選項就會出現。這就是條件分支的基本效果。5.3 異常場景節點不存在、存檔損壞、變量類型錯誤把storyMap中某個節點的next改成不存在的 id比如next: not_exist點擊“繼續”后控制臺會出現[story-engine] 找不到節點: not_exist頁面不會跳轉因為 store 在goTo中做了存在性檢查。這是有意為之寧可停在原地報錯也不要跳到 undefined 導致白屏。存檔損壞時手動在 Local Storage 里把值改成{bad json點擊“讀檔”后 load 函數捕獲異常并返回 false。界面可以提示“存檔讀取失敗”而不是直接崩潰。變量類型錯誤最容易出現在add操作上。比如affection被設成字符串10再做add時typeof current number判斷為 false會把 base 當成 0于是結果變成0 10。表面看起來只是數值異常實際上會掩蓋劇本數據寫錯的問題。建議在開發環境給vars加類型校驗或者在控制臺打印警告。6. 常見問題排查從現象倒推原因問題現象常見原因檢查方式處理建議點擊選項后沒有反應選項的next指向了不存在的節點打開控制臺看[story-engine] 找不到節點日志檢查 storyMap 中的 id修正next指向或補全缺失節點存檔讀取后白屏存檔里的節點 id 在舊版本中存在新版本已被刪除在load中打印data.currentNodeId判斷節點是否存在增加節點存在性校驗不存在時返回 false 并重新開始條件選項不顯示condition表達式寫錯或者變量值從未初始化在面板組件中打印vars和checkCondition結果確保變量在initialState或onEnter中初始化繼續按鈕點擊后跳過多個節點goTo中額外調用了applyEnterActions而onEnter里又調用goTo檢查動作鏈是否形成遞歸跳轉不要把跳轉寫在onEnter動作里動作只修改變量繼續按鈕點擊后所有選項一起出現沒有在渲染前過濾condition只是把 choices 全部 map 出去檢查availableChoices是否基于vars過濾使用filter配合checkCondition并訂閱vars歷史記錄順序混亂history在selectChoice和goTo中重復追加檢查每條歷史記錄的時間戳和內容統一只在一處追加歷史跳轉節點和選擇節點分別記錄排查時建議按下面的優先級進行先確認當前節點 id 是不是預期值。在組件頂部打印currentNodeId。再確認storyMap里是否存在該節點節點的type是否正確。再檢查變量表。在控制臺執行useGameStore.getState().vars查看實時變量。再檢查條件判斷。手動調用checkCondition({ key: affection, op: , value: 5 }, { affection: 10 })看返回結果。最后檢查界面渲染。確認availableChoices和node是從同一個 store 中讀取。7. 從 Demo 到完整項目架構、存檔和內容生產建議7.1 把劇情數據從 TS 文件挪到 JSON 或遠程配置示例中劇情寫在story.ts里好處是類型檢查方便壞處是策劃改劇本需要改代碼。在正經項目里劇本通常由策劃或敘事設計師維護他們不應該接觸 TypeScript。推薦兩種方式開發期使用本地 JSON通過 Vite 的import直接讀取。上線后把劇情放在遠程 CDN 或配置中心版本號和存檔綁定劇情更新時兼容舊存檔。如果劇情文件很大不要一次性把整棵樹加載到內存?？梢园凑鹿澆鸱旨虞d一章后再加載下一章。示例中的storyMap是全量數據適合小體量互動故事超過幾百個節點的項目需要引入分片加載。7.2 存檔設計要帶版本號和結構校驗生產環境存檔不能只存currentNodeId和vars。建議增加saveVersion用于做遷移。updatedAt用于自動存檔排序。storyVersion標記當前劇情版本劇情更新后決定是否允許讀檔。playTime用于統計玩家進度。示例中的load已經做了節點存在性檢查但生產環境還需要對vars做默認值合并。否則新版本增加了變量affection舊存檔沒有這個鍵后續做條件判斷時會出現 undefined 比較。7.3 可復用的生產檢查清單在發布互動劇情項目前至少確認以下事項已經完成節點 id 全局唯一且跳轉目標全部存在。所有條件分支都能被至少一個前置狀態滿足避免出現無法觸發的分支。變量在進入游戲時初始化條件判斷對 undefined 值有兜底。存檔包含版本號讀取失敗時有降級策略。所有異常路徑在 UI 上有提示而不是只在控制臺打印。音頻和立繪資源用懶加載避免開局加載整個劇情包。對save、load、clearSave做防抖避免連續點擊導致存檔覆蓋錯亂。在測試環境制定一份“全分支通關測試表”每個選項點一遍每條結局跑一遍。如果要把這個引擎推到更復雜的方向可以繼續擴展分支嵌套、音量控制、自動存檔、多語言文本、文本變量插值比如在對話中顯示{affection}當前值。核心仍然不變劇情是數據界面是渲染器狀態管理負責所有派生計算。理解了這層關系《異環》這個項目無論加多少內容技術骨架都不會散。