在浏览器里点开一个链接，两三秒后背景音乐响起，立绘从画面两侧滑入，对话框里的字一个一个往外蹦——这就是HTML5 GalGame 引擎最直观的样子。它做的事情说穿了不复杂：把原本需要打包安装的视觉小说，变成一套纯前端就能跑的内容，玩家不用下载客户端，开发者不用为 Windows、macOS、Android 各维护一份构建。我最早接触这类引擎，是帮一个做独立剧本的朋友把一段十万字的故事搬上网页，当时以为改改 CSS 就完事，结果在剧本解析、立绘排程、存档结构上连着栽了好几个跟头。这套 HTML5 视觉小说引擎解决的正是这些问题：用一套自定义剧本语法描述演出，引擎负责把文字、立绘、背景、音乐、分支、存档串成一条可回放的指令流。适合谁看？如果你会一点 JavaScript、想做个文字冒险 Demo 或完整的视觉小说项目，或者你手头已经有一套引擎但被存档丢失、移动端音频不响、切场景白屏这些问题折磨过，下面这些内容应该能省你不少时间。我会从一个引擎骨架怎么搭讲起，一路拆到剧本解析器、演出层排程、资源加载策略和踩坑速查表，代码和参数都尽量给到能直接抄的程度。

1. 从"能玩"倒推架构：H5 视觉小说引擎的整体设计思路

1.1 为什么是网页，而不是原生客户端

先把这个选择说清楚，因为它决定了后面所有技术细节。视觉小说这类内容的特征是：画面以静态图为主、互动以点击为主、计算量极低、但对资源体积和首次加载速度极其敏感。一套完整的商业级作品，背景加上立绘加上 CG，动辄几百 MB 到几个 GB。原生客户端的好处是资源躺在本地磁盘，读图几乎零延迟；网页的短板恰恰在这里，玩家点开链接的第一秒，什么都还没下载。

那为什么还要选网页？我自己的判断标准有三条。第一是分发成本。分享一个链接和让玩家下载一个安装包，转化率差一个数量级，尤其是短篇作品、试玩版、活动企划这种"看一眼就走"的场景。第二是迭代速度。剧本改一句台词、换一张立绘，重新部署一次静态资源就完事，不用发版、不用过审、不用让玩家重新下载。第三是跨端一致性。同一份代码在桌面浏览器、手机浏览器、平板、甚至嵌入式浏览器里都能跑，虽然要做适配，但比维护三套原生渲染管线便宜太多。

代价也很明确：加载策略必须重新设计，不能像原生那样"要用什么读什么"，得靠预加载队列把玩家即将看到的内容提前拉到内存里；音频在移动端有自动播放限制，必须等一次真实用户交互才能解锁；图片解码在主线程上会卡顿，大图要考虑createImageBitmap或者分帧加载。这些后面都会展开。

1.2 引擎骨架的四个核心模块

我习惯把这类引擎拆成四层，从上到下依次是剧本层、演出层、资源层、持久层。这个分层不是学术意义上的架构图，而是按"改哪里会炸哪里"划分的：改剧本语法只动第一层，调动画曲线只动第二层，换图床或加 CDN 只动第三层，动存档结构则要小心第四层的向后兼容。

剧本层负责把人类可读的剧本文本翻译成引擎能执行的指令序列。它是整个引擎里最像"编译器"的部分：词法分析切 token、语法分析建抽象语法树、再把它编译成一个扁平的指令数组。之所以要编译成扁平数组而不是直接解释 AST，是因为视觉小说有大量"跳回上一句""跳到某个标签""快进到已读位置"的操作，扁平数组加索引寻址比树形遍历好实现太多。

演出层是舞台调度，管的是"这一帧画面上有什么"。背景、立绘、对话框、选项按钮、特效层，各自是独立的渲染单元，由一条时间轴统一驱动。这里最容易被低估的是状态同步：玩家从存档读进来的时候，舞台必须瞬间还原成存档那一刻的样子，包括哪几个角色站在哪个位置、表情是什么、BGM 播到哪儿。

资源层管加载、缓存、释放。核心指标是首屏时间和峰值内存。视觉小说的内存峰值通常出现在连续切换大背景的时候，前一张还没释放、后一张已经解码完，两张 1920×1080 的位图就能吃掉几十 MB。

持久层管存档、已读标记、设置项。它看起来最简单，实际上是最容易埋雷的地方——引擎版本一升级，老存档读不出来，玩家几十小时的进度就没了。

1.3 引擎与内容的边界该划在哪

这个问题我在项目初期纠结了很久：哪些东西写进引擎，哪些留给剧本作者？我的结论是——凡是会改变"演出节奏"的，交给剧本；凡是会改变"渲染方式"的，交给引擎。

举个具体例子。"立绘从左边滑入，用时 400 毫秒，缓动曲线是 ease-out"——这属于演出节奏，应该写在剧本里，作者可以自己调。而"立绘滑入时用 CSS transform 还是 canvas 逐帧重绘"——这属于渲染方式，写死在引擎里，作者不该关心。

边界划不清的典型症状是剧本里出现大量魔法参数，比如@show yuki center normal 400 ease-out 0.8，后面一串数字作者自己都记不住。我的做法是给常用组合起别名，@show yuki center用默认的 300ms 淡入，需要特殊效果才写完整参数。这样剧本读起来像剧本，不像配置文件。

提示：剧本语法的第一原则是"作者写起来顺手"，不是"程序解析起来优雅"。宁可让解析器多写两百行兼容代码，也不要让作者每天查语法手册。

2. 剧本解析器：把一段文本变成可执行的演出指令

2.1 为什么自造脚本语言，而不是直接写 JSON

很多人第一反应是"剧本用 JSON 存不就行了"。我试过，结论是短期内爽、长期痛苦。JSON 的问题在于信噪比太低：一句台词要包成{"type":"say","speaker":"yuki","text":"早上好。"}，十万字剧本写下来，满屏都是花括号和引号，作者改一句话要在三层嵌套里找位置，还得时刻担心少个逗号导致整个文件解析失败。

自造脚本语言的好处是语法可以贴着写作习惯长。上面那句台词，在我的引擎里就是一行：

雪：早上好。

冒号前的部分自动识别为说话人，冒号后的部分是台词。再复杂一点：

@bg classroom_day fade 500 @bgm bgm_daily vol=0.6 @show yuki center normal 雪：早上好。 雪：(今天的她好像有点不一样。) @choice - 回应她 -> greet - 假装没听见 -> ignore :greet 雪：嗯，早。 @set affection_yuki += 3 @jump ch01_after

这套语法里只有三类东西：指令行（以@开头）、台词行（说话人：内容）、标签行（以:开头）以及选项行（以-开头）。剩下的全是普通文本，作者写起来接近写剧本软件。

代价是解析器要自己写，而且要考虑错误提示。我的经验是：解析出错时一定要报行号和原始行内容，否则作者面对一份几千行的剧本根本找不到问题在哪。这一点比语法本身优雅重要十倍。

2.2 一条指令的完整生命周期

从文本到执行，中间要过四道关。我用一个最小可用的实现来说明，逻辑上分四步：预处理、分词、构建指令对象、编译成扁平数组。

第一步预处理，主要是统一换行符、去掉行尾空白、把连续空行折叠、处理注释（我用的注释符号是//，独立成行才算）。这一步不解析语义，只做规整，好处是后面所有步骤都可以假设输入是"一行一条"的干净文本。

第二步分词，按行首字符判断类型：@开头是指令，:开头是标签，-开头且处于选项块内是选项，其余是台词。指令行再按空格切分成命令名和参数，参数里要支持key=value形式。

function tokenizeLine(raw, lineNo) { const line = raw.trim(); if (!line || line.startsWith('//')) return null; if (line.startsWith('@')) { const body = line.slice(1); const firstSpace = body.indexOf(' '); const name = firstSpace === -1 ? body : body.slice(0, firstSpace); const argStr = firstSpace === -1 ? '' : body.slice(firstSpace + 1); return { type: 'cmd', name, args: parseArgs(argStr), lineNo }; } if (line.startsWith(':')) { return { type: 'label', name: line.slice(1).trim(), lineNo }; } if (line.startsWith('-')) { return { type: 'option', raw: line.slice(1).trim(), lineNo }; } const idx = line.indexOf('：') !== -1 ? line.indexOf('：') : line.indexOf(':'); if (idx > 0) { return { type: 'say', speaker: line.slice(0, idx).trim(), text: line.slice(idx + 1).trim(), lineNo }; } return { type: 'say', speaker: null, text: line, lineNo }; }

注意那个中英文冒号的兼容判断。中文剧本作者用全角冒号是常态，解析器必须两种都认，否则会出现"说话人识别不出来、整句被当成旁白"的诡异 bug。这个坑我踩过一次，排查了半小时才发现是输入法的问题。

第三步构建指令对象，把分词结果映射成带执行语义的对象，同时做静态检查：@jump的目标标签是否存在、@show的角色是否在角色表里注册过、选项块是否成对闭合。这一步能在加载阶段就把剧本错误暴露出来，而不是等玩家玩到第三小时才崩。

第四步编译成扁平数组，把标签位置记录成索引映射表：

function compile(tokens) { const program = []; const labels = Object.create(null); let i = 0; while (i < tokens.length) { const t = tokens[i]; if (t.type === 'label') { labels[t.name] = program.length; i++; continue; } if (t.type === 'option') { const options = []; while (i < tokens.length && tokens[i].type === 'option') { const m = tokens[i].raw.match(/^(.*?)\s*->\s*(\S+)$/); if (!m) throw new Error(`第 ${tokens[i].lineNo} 行选项格式错误`); options.push({ text: m[1].trim(), target: m[2] }); i++; } program.push({ op: 'choice', options }); continue; } if (t.type === 'cmd') { program.push(buildCommand(t)); i++; continue; } program.push({ op: 'say', speaker: t.speaker, text: t.text, lineNo: t.lineNo }); i++; } return { program, labels }; }

扁平数组加标签映射表，带来的直接好处是存档只需要存一个整数——当前执行到第几条指令。读档时把指针一设，从那条指令往后重新跑一遍"舞台还原"，就能回到存档瞬间。这个设计我在后面讲存档时会再提。

2.3 变量、条件与好感度：让分支真正有用

纯线性的视觉小说用不上变量，但只要有分支，玩家就会期待"我前面选的话有影响"。最小可用的变量系统包含三样东西：赋值、比较、条件跳转。

赋值的写法我设计成@set 变量名 运算符 值，比如@set affection_yuki += 3。解析时要支持=、+=、-=三种，值可以是数字、布尔或者字符串。别小看这个设计，+=比"先读再写"少写一行，剧本里几十个好感度累加点，省下来的行数很可观。

条件跳转用@if加@endif包住一段指令，或者更简单的@jumpif 条件 -> 标签：

@jumpif affection_yuki >= 10 -> good_route @jumpif has_key == true -> secret_room

条件表达式的解析有两种走法。稳妥的是自己写一个极简表达式求值器，只支持比较运算符和逻辑与或；偷懒且危险的是直接new Function('vars', 'with(vars){return ' + expr + '}')。后者性能好、写法灵活，但剧本文件如果来自不可信来源，这就是一个任意代码执行的口子。我的建议是：内部项目图省事可以用，对外分发的内容一律用受限求值器，白名单只放行变量名、数字、比较符和&&、||。

还有一个细节容易被忽略：变量作用域。全局变量跨章节共享，没问题；但临时变量（比如某个小游戏的结果）如果不隔离，会在后面的章节里意外命中。我的做法是给变量加前缀约定，g_开头是全局、t_开头是当前场景临时，场景切换时清掉t_前缀的全部键。这是个土办法，但比引入真正的作用域链省事得多。

3. 演出层：立绘、文字、转场到底怎么排程

3.1 DOM 还是 Canvas，这个选择要一次做对

这是绕不开的第一个技术选型。两条路的差别很大，而且改起来成本极高，基本等于重写演出层。

DOM 方案的思路是把背景、立绘、对话框都做成<div>或<img>，转场和动画交给 CSS transition / animation。优点是上手快、文字渲染天然清晰、无障碍和选中复制免费、调试时可以直接在开发者工具里改样式看效果。缺点是元素一多，合成层管理会失控，尤其是多个立绘同时做滤镜和位移的时候，移动端掉帧明显。

Canvas 方案的思路是自己管绘制循环，所有东西画到一个<canvas>上。优点是渲染完全可控、可以做复杂的图层混合和粒子特效、元素数量对性能影响小。缺点同样明显：文字排版要自己处理（换行、标点避头尾、字体加载），文本选中和缩放适配都得手写。

我的实战结论是混合方案最省心：背景和立绘用 DOM + CSS transform（translate3d走 GPU 合成），对话框文字也用 DOM，而需要复杂特效的部分（比如雨滴、樱花、胶片颗粒）单独开一个 canvas 覆盖层，只在需要的时候启用。

具体参数上，立绘容器的写法大概是：

.char-layer { position: absolute; inset: 0; pointer-events: none; will-change: transform, opacity; } .char { position: absolute; bottom: 0; height: 92%; transform: translate3d(-50%, 0, 0); transition: transform .3s cubic-bezier(.22,.61,.36,1), opacity .3s ease; backface-visibility: hidden; }

will-change和translate3d是让浏览器提前把这个元素提升为独立合成层，位移和透明度变化就不用重绘整页。但will-change别乱加，常驻几十个元素都开，显存会被吃光，移动端直接闪退。我的做法是只在动画开始前动态加、结束后移除。

3.2 打字机效果：三种实现和它们的坑

台词逐字显示是视觉小说的标志性效果，看起来简单，实现方式却直接影响体验。

第一种是setInterval定时器每 30 毫秒追加一个字。最直观，但问题一大堆：标签页切到后台，定时器被浏览器降频到 1 秒一次，回来时文字卡住；快速点击跳过时定时器没清干净，新旧两个定时器同时往里塞字，文字会乱序。

第二种是requestAnimationFrame加时间累计。每帧算一次"从开始到现在过了多少毫秒，应该显示到第几个字"，然后一次性把字符串切到那个位置。这是我目前主用的方案，理由是它天然对齐屏幕刷新率，后台标签页会被自动暂停，回来继续，不会出现时间错乱。核心逻辑就几行：

let startTime = 0; let shown = 0; const SPEED = 33; // 每字 33ms，约 30 字/秒 function tick(now) { if (!startTime) startTime = now; const target = Math.min(text.length, Math.floor((now - startTime) / SPEED)); if (target !== shown) { shown = target; textEl.textContent = text.slice(0, shown); } if (shown < text.length) rafId = requestAnimationFrame(tick); }

第三种是纯 CSS 方案：把每个字包成<span>，用animation-delay逐个触发 opacity 从 0 到 1。优点是零 JS 开销、动画流畅。缺点是 DOM 节点数量爆炸，一段 200 字的台词就是 200 个 span；而且"点击后立刻显示全部"需要额外写 CSS 覆盖，跳字体验不干脆。我一般在短句或者标题演出上用，长段台词还是走 rAF。

注意：跳过全部文字时，除了把显示位置设到末尾，还要记得清掉在跑的 rAF 句柄并置空。忘了这一步会出现"跳过后又被定时器重写回去"的经典 bug。

3.3 转场的时间轴调度

转场是视觉小说里最能体现质感的部分，也是最容易写成面条代码的部分。我的做法是引入一个极简的时间轴队列：所有演出动作（淡入、位移、闪烁、震动）都包装成「时长 + 进度回调」的对象，统一压进队列，由一个调度器串行执行。

class Timeline { constructor() { this.queue = []; this.running = false; } push(action) { this.queue.push(action); return this; } async run() { if (this.running) return; this.running = true; while (this.queue.length) { const act = this.queue.shift(); await act(); } this.running = false; } }

每个 action 返回一个 Promise，内部用 rAF 推动进度，进度到 1 就 resolve。这样写的好处是时序关系一目了然：先淡出旧背景（400ms），再淡入新背景（400ms），再显示立绘（300ms），三行代码读起来就是演出顺序。

有个细节值得单独说：可打断性。玩家等不及转场就点了下一步，这时候你是让转场跑完，还是立刻跳到终态？我的选择是后者——玩家点击时立刻把所有正在跑的动画设到终点并 resolve，然后继续执行后续指令。实现上就是给每个 action 加一个finish()方法，调度器在收到"跳过"信号时挨个调用。不做这个处理，玩家狂点之后会看到一堆动画叠在一起，画面糊成一团。

3.4 音频通道：BGM、音效、语音不能挤在一条道上

音频管理看着简单，实际上通道划分决定了能不能做出"音乐渐弱、语音打断"这类效果。我的划分是：

• BGM 通道：只有一个，切换时做 300 到 800 毫秒的交叉淡入淡出。视觉小说里音乐经常跨场景延续，所以指令设计上要区分"换 BGM"和"继续当前 BGM"。
• 环境音通道：独立于 BGM，比如雨声、风声、教室的嘈杂。允许和 BGM 同时存在。
• 音效池：短音效（脚步声、开门声、翻页声）用对象池管理，同时最多 8 个实例，超了就复用最早的。别每次new Audio()，节点会越积越多。
• 语音通道：单独一条，新语音进来时立刻打断上一条。这一条是硬需求，玩家快速点击时如果语音排队播放，会听到一堆叠在一起的台词。

音量上要注意的是人耳感知不是线性的。滑块拉到 50%，实际感知响度远不止一半。建议用gain = Math.pow(slider, 2)做一次映射，主观听感才接近线性。这是个小细节，但设置面板做得好不好，玩家一耳朵就能听出来。

4. 资源管理与加载：首屏三秒决定玩家走不走

4.1 预加载队列该按什么顺序排

视觉小说的资源加载不能"要用了才去拉"，否则每次切场景都是一次白屏。但也不能一上来就把几百 MB 全拉下来，手机流量用户会直接关掉页面。

我的做法是三级队列。第一级是阻塞式加载：首屏必需的背景、UI 图、字体、第一段 BGM，没加载完不进场，配一个进度条。第二级是当前场景的剩余资源：进场之后立刻在后台拉当前章节的所有立绘表情和音效。第三级是下一场景的预取：玩家进入到本章中段时，开始预取下一章的首屏资源。

优先级判断上，除了静态的"章节顺序"，还要加一条动态权重：玩家最近两分钟内用过的角色立绘，排到队伍前面。因为视觉小说的剧情往往集中在一两个角色身上，把他们的所有表情都缓存住，命中率能到八九成。

const loader = { queue: [], cache: new Map(), add(url, priority = 0) { if (this.cache.has(url)) return Promise.resolve(this.cache.get(url)); return new Promise((resolve, reject) => { this.queue.push({ url, priority, resolve, reject }); this.queue.sort((a, b) => b.priority - a.priority); this.pump(); }); }, pump() { const CONCURRENCY = 4; while (this.active < CONCURRENCY && this.queue.length) { const job = this.queue.shift(); this.active++; const img = new Image(); img.onload = () => { this.cache.set(job.url, img); job.resolve(img); this.active--; this.pump(); }; img.onerror = () => { job.reject(new Error(job.url)); this.active--; this.pump(); }; img.src = job.url; } } };

并发数设 4 是个经验值。HTTP/1.1 下浏览器同域并发上限是 6，留两个名额给接口和字体；HTTP/2 下理论上可以更多，但图片解码是主线程瓶颈，开太多反而互相拖慢，实测 4 到 6 之间最稳。

4.2 图片格式与体积：几个能立刻生效的参数

资源体积是这类项目最大的成本项。下面这几个参数是我反复调过的，效果直接。

几个实测出来的经验：立绘如果按 4K 出图再缩放，手机上解码会卡顿几百毫秒，直接按最终显示高度的 1.5 倍出图最划算；背景图加一点点噪点或者纹理，WebP 压缩后的体积反而更小，因为大面积纯色渐变是压缩器的噩梦；透明立绘的边缘如果有半透明羽化，WebP 比 PNG 省一半以上体积，而且视觉上看不出差别。

4.3 缓存策略与版本号：资源更新不能炸存档

静态资源部署之后，最头疼的是"玩家浏览器里缓存着旧图"。文件名加内容哈希是最稳的方案，bg_classroom_day.a3f9c1.webp，内容一变哈希就变，天然避开缓存问题。代价是剧本里要引用带哈希的路径，所以我在构建阶段做了一层映射：剧本里写逻辑名bg_classroom_day，构建时替换成真实路径。

另一半问题是存档兼容。玩家存了档，你更新了版本，加了一个新角色、删了一个旧背景，读档时怎么还原？我的做法是存档里只存逻辑名和变量值，不存资源路径；读档时如果某个资源找不到，用一张占位图代替并记一条警告，而不是直接抛异常让整个存档作废。玩家看到一张灰色占位图，总比看到"存档损坏"要好。

再补一条：存档格式要带版本号和迁移函数。我吃过一次亏，中期改了一版存档结构，把chars数组改成对象，结果测试群里十几个人的进度全废了。后来加了migrate(save)函数，按version字段逐级升级，从此再没出过事。

5. 存档、回放与分支：最容易翻车的三块

5.1 快照式存档和指令流存档的取舍

存档有两种思路。快照式是把当前舞台的完整状态序列化下来：背景是什么、立绘有谁站在哪、BGM 是哪首播到第几秒、所有变量当前的值、当前执行到第几条指令。指令流式只存一个起点和一个操作序列，读档时重放。

我最终选的是混合式：主体用快照，但额外存一个指令索引和最近的 20 条台词历史。快照保证读档秒开，指令索引用于"从存档点回看剧情"，历史则用来填充回想界面的文本记录。

存档结构大致长这样：

{ "version": 3, "saveId": "slot_02", "timestamp": 1730000000000, "chapter": "ch01", "pointer": 482, "stage": { "bg": "classroom_day", "bgm": { "name": "bgm_daily", "volume": 0.6 }, "chars": [ { "id": "yuki", "pos": "center", "expr": "normal", "alpha": 1 } ] }, "vars": { "g_affection_yuki": 12, "g_has_key": true }, "history": [ { "speaker": "yuki", "text": "早上好。" } ] }

注意stage.chars里存的是逻辑 id 和表情名，不是图片路径。这一层间接让换美术素材不用动存档。

5.2 已读标记、跳过与自动播放

这三个功能玩家用得最多，做不好被吐槽也最多。

已读标记的核心是给每条台词一个稳定标识。用台词文本的哈希会出问题——改一个错别字，整条记录就失效了，玩家重玩时会发现"这句明明读过却不算已读"。我的做法是章节id + 指令索引组合成键，改文本不影响，改结构才失效，后者本来就不可避免。

存储位置上，localStorage的容量通常只有 5MB 左右，一条记录按 20 字节算，十万条台词就是 2MB，勉强够用但很危险，而且localStorage是同步 API，读写会阻塞主线程。台词量大的项目我建议换 IndexedDB，异步、容量大，代价是首次要写一套 Promise 封装。

跳过功能要区分"跳过已读"和"跳过全部"。前者是大多数玩家的默认需求，后者一般只在选错路线时用。实现上跳过模式就是一个加速倍率，把打字机速度设为 0、转场时长设为 0，然后在每条指令执行完后检查"这条是不是已读"，是就继续跳，不是就停在原地等玩家确认。这里有个坑：跳过时如果遇到选项，必须强制停下，否则会直接跳过分支节点，剧情跑飞。

自动播放的节奏控制是门玄学。固定延迟（比如每句停 2 秒）体验很差，因为短句等太久、长句不够看。我的做法是按字数算基础时长，再加一个固定尾巴：delay = 800 + text.length * 60毫秒，上限 6 秒。语音播放时则以语音时长为准，播完再等 400 毫秒。

5.3 分支与结局管理：别让剧情变成一团毛线

分支一多，剧本维护就会失控。我见过最夸张的一个项目，三十多个标签跳来跳去，最后作者自己都说不清某个选项会通向哪里。

我的做法是加一层章节清单，用一个单独的配置描述章节之间的跳转关系：

export const chapters = { ch01: { next: ['ch02a', 'ch02b'], entry: 'start' }, ch02a: { next: ['ch03'], entry: 'start' }, ch02b: { next: ['ch03'], entry: 'start' }, ch03: { next: [], entry: 'start', endings: ['good', 'normal', 'bad'] } };

这层清单不参与运行时逻辑，只用于三件事：加载时做完整性校验（有没有指向不存在章节的跳转）、做流程可视化（自动生成一张章节关系图，作者能一眼看出结构）、做测试覆盖率统计（哪些分支从来没被跑到过）。第三点特别有用，我一般在开发环境里跑一个自动化脚本，把所有分支随机走几百遍，把没覆盖到的标签列出来，补测试的效率高很多。

6. 常见问题与排查实录

6.1 移动端音频不响：八成是第一下点击没接住

浏览器对自动播放的限制几乎是所有 H5 音频问题的根源。表现是：桌面正常，手机打开没声音，或者第一句台词有声音、切场景之后没了。

根本原因是音频上下文在"没有用户手势"的情况下处于 suspended 状态。解决办法是在首次真实点击（touchend或click，不要用touchstart）时创建或唤醒音频上下文，并播一个静音 buffer 解锁：

let unlocked = false; document.addEventListener('touchend', async function once() { if (unlocked) return; const ctx = new (window.AudioContext || window.webkitAudioContext)(); if (ctx.state === 'suspended') await ctx.resume(); const buf = ctx.createBuffer(1, 1, 22050); const src = ctx.createBufferSource(); src.buffer = buf; src.connect(ctx.destination); src.start(0); unlocked = true; document.removeEventListener('touchend', once); }, { passive: true });

另外，iOS 上把手机调成静音模式时，<audio>标签播放的媒体是静音的，这条无解，只能靠界面提示引导玩家关闭静音。还有一点，切到后台再回来，音频上下文可能又回到 suspended，需要在visibilitychange里重新resume()。

6.2 文字溢出与排版：中文的换行比英文难搞

英文有词边界，中文没有，所以标点避头尾就成了必须处理的问题。默认情况下，句号、逗号可能出现在行首，括号可能被拆成两半，观感很差。

CSS 层面加上这几行能解决大部分问题：

.dialogue-text { line-break: strict; word-break: normal; overflow-wrap: break-word; text-align: justify; text-justify: inter-ideograph; line-height: 1.75; }

line-break: strict让浏览器按严格的避头尾规则断行。字体方面，中文网页字体动辄十几 MB，直接引入会让首屏时间翻倍。实用方案是系统字体栈优先，只在标题等少量文字上用子集化的 WOFF2。做子集的时候别只截常用三千字，剧本里出现的生僻字、人名用字要单独扫一遍加进去，否则会出现某个角色名字显示成方框的尴尬情况。

还有一个隐蔽的坑：line-height设得刚好等于字号会让行间距显得挤，中文尤其明显。我的经验值是字号的 1.7 到 1.8 倍，阅读舒适度最好。

6.3 常见问题速查表

提示：排查这类问题最有效的手段是做一个"调试面板"，把当前指针位置、变量值、舞台状态实时打印出来，按一个键切换显示。比在控制台里一行行console.log快十倍，而且上线前把开关关掉就行。

6.4 几个只有做过才知道的经验

第一条：别在剧本里写绝对时间。@wait 3000这种指令看着方便，玩家开了二倍速之后就会变成"必须干等三秒"的折磨。等待时长应该由引擎的速度倍率统一缩放，剧本里只写"等一个节拍"这种相对量。

第二条：资源加载失败要有兜底。网络抖动、CDN 抽风都是常态，一张背景图挂了不该让整个游戏卡死在加载页。我的做法是图片 onerror 后重试两次，仍失败就用同色系纯色块加文字说明代替，并记录下来，游戏继续。

第三条：测试要在真机上跑。桌面浏览器缩放窗口模拟移动端，和真机完全是两回事，尤其是 iOS Safari 的内存限制——一个页面占用超过几百 MB，Safari 会直接刷新页面，表现就是"玩到一半突然回到开头"。这个问题的排查成本极高，预防手段是控制同时驻留的大图数量，及时释放不可见章节的缓存。

第四条：给作者做一个预览工具。剧本作者不可能每次都构建部署再看效果，我在引擎里加了一个开发模式，支持单章热重载和标签跳转，改一行剧本刷新就能看到，作者的迭代速度提升非常明显。这个投入在项目中期就会回本。

7. 部署与后续扩展的几点实操建议

部署这块没什么花活，静态资源扔到任意对象存储加 CDN 就能跑。几个参数值得调：开启 Brotli 压缩，文本资源能再省 20%；给带哈希的静态资源设一年强缓存，index.html设不缓存；跨域隔离相关的响应头如果不需要 SharedArrayBuffer 就别开，开了反而容易在嵌入场景里出问题。

后续扩展上，我觉得有三个方向性价比最高。一是多语言，把台词抽到外部语言包，引擎层只认 key，切换语言时重新编译剧本。这件事前期做成本很低，后期补就是灾难。二是云存档，本地存档加一个可选的账号同步，玩家换设备能接着玩，实现上就是存档 JSON 传一份到服务端，注意做冲突合并策略。三是数据埋点，统计玩家在哪个选项停得最久、哪条路线走得最多，这些数据对后续创作的参考价值远比想象中大。

我个人在实际项目里最深的一点体会是：这类引擎的复杂度不在技术本身，而在使用它的作者。一个语法设计得再优雅，作者用着别扭就是失败；一个功能实现得再精巧，作者不知道怎么调参数就是白做。所以每次加新特性之前，我都会先问自己一句——这个东西是给玩家看的，还是给作者用的？如果是给作者用的，那文档和默认值的重要性，可能超过代码本身。

最后分享一个小技巧：给剧本解析器加一个"严格模式"开关，开发时打开，遇到未注册的角色、未定义的标签、拼错的指令名直接报错中断；上线时关掉，遇到问题降级成警告继续跑。这个开关帮我拦下过大量低级错误，也让线上版本不至于因为一处笔误就整章崩掉。