用React+TypeScript和Zustand构建数据驱动的互动剧情引擎

如果让我把《异环关于我在异世界捡到青梅竹马这件事》做成一个可玩的互动剧情第一件事不是画女主立绘也不是写一万字文案而是先想清楚剧情在代码里到底存成什么。很多人做文字冒险游戏习惯把剧情直接写在组件里点一下按钮更新一下 text再点一下再更新。这种写法在三个节点的时候很好用等剧情超过三十个节点、开始出现分支和好感度变量时组件会膨胀到无法维护。更合理的做法是把剧情当成数据把界面当成渲染器把状态管理当成推进器。这样剧本可以单独维护后续加配音、加立绘、加多结局都只是换数据源和增加渲染能力不需要重写业务逻辑。这篇文章以《异环》作为项目代号以“在异世界捡到青梅竹马”作为示例剧情一步步搭建一个基于 React TypeScript Zustand 的互动剧情引擎。你可以把它理解为文字冒险游戏的“最小可运行骨架”也可以直接作为后续做 Galgame、视觉小说或叙事向小游戏的起点。文章会从剧情的数据结构讲起然后搭建工程、编写状态管理和界面渲染最后补上存档、条件分支、常见排错和生产化建议。每一段代码都可以直接复制到项目里运行但更重要的是理解每个节点字段存在的理由。1. 互动剧情的技术拆解把“捡到青梅竹马”变成可计算的结构1.1 剧情不是一段长文本而是一张有向图传统的线性小说阅读体验是从第一行读到最后一行读者没有选择权。互动剧情不一样玩家在关键节点做出的选择会改变后续对话、角色好感度和最终结局。从技术角度看这就不是线性文本而是一张有向图每个可停留的剧情片段是一个节点。一个对话说完后跳到哪个节点由next指向。一个选项节点包含多个分支出口每个出口也是一条边。某些边的显示需要满足变量条件比如好感度大于某个值。某些边的触发会修改变量比如选择“叫出她的名字”后好感度 10。只要这张图能稳定表达写剧情的人只关心节点内容写程序的人只关心节点如何被访问。两者通过一套约定好的数据结构解耦。《异环》这个标题里“异世界”是舞台“捡到青梅竹马”是核心事件。用技术语言翻译一下玩家从“街道醒来”这个节点出发进入“遇到熟悉身影”的对话遇到一个两难选择。选择“叫出她的名字”会进入好感度上涨的相认结局选择“表示不认识”会进入错过结局。这就是一个最小的有向图。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 或配置中心版本号和存档绑定剧情更新时兼容旧存档。如果剧情文件很大不要一次性把整棵树加载到内存。可以按章节拆分加载一章后再加载下一章。示例中的storyMap是全量数据适合小体量互动故事超过几百个节点的项目需要引入分片加载。7.2 存档设计要带版本号和结构校验生产环境存档不能只存currentNodeId和vars。建议增加saveVersion用于做迁移。updatedAt用于自动存档排序。storyVersion标记当前剧情版本剧情更新后决定是否允许读档。playTime用于统计玩家进度。示例中的load已经做了节点存在性检查但生产环境还需要对vars做默认值合并。否则新版本增加了变量affection旧存档没有这个键后续做条件判断时会出现 undefined 比较。7.3 可复用的生产检查清单在发布互动剧情项目前至少确认以下事项已经完成节点 id 全局唯一且跳转目标全部存在。所有条件分支都能被至少一个前置状态满足避免出现无法触发的分支。变量在进入游戏时初始化条件判断对 undefined 值有兜底。存档包含版本号读取失败时有降级策略。所有异常路径在 UI 上有提示而不是只在控制台打印。音频和立绘资源用懒加载避免开局加载整个剧情包。对save、load、clearSave做防抖避免连续点击导致存档覆盖错乱。在测试环境制定一份“全分支通关测试表”每个选项点一遍每条结局跑一遍。如果要把这个引擎推到更复杂的方向可以继续扩展分支嵌套、音量控制、自动存档、多语言文本、文本变量插值比如在对话中显示{affection}当前值。核心仍然不变剧情是数据界面是渲染器状态管理负责所有派生计算。理解了这层关系《异环》这个项目无论加多少内容技术骨架都不会散。