做视觉小说这行久了，经常有人问我一个问题：一段剧情做出来，怎么让玩家在手机浏览器里点开链接就能玩，不用下载安装包？HTML5 Galgame 引擎就是干这个的。它把传统视觉小说里那套“立绘切换、背景过渡、文字逐字显示、分支选项、存档读档”的能力，用网页技术重新实现了一遍，最终产物是一堆静态文件，扔到任意静态托管上就能跑。这类引擎解决的核心痛点是分发成本和迭代速度——美术改一张图、脚本改一句台词，重新上传即可生效，不需要重新打包发版、不需要过审、不需要玩家更新。它适合三类人：想快速验证剧情的小型独立团队、从文案或美术转过来的个人制作者、以及想给学生做互动叙事课程作业的开发者。我自己前后折腾过几个版本的 HTML5 Galgame 引擎，从最早的 DOM 硬拼，到后来的 Canvas 分层渲染，踩过的坑基本能写成一本小册子，下面把能直接抄的部分都摊开讲。
1. 浏览器里跑视觉小说的架构选型与思路拆解
1.1 为什么“能跑”和“好玩”是两件完全不同的事
先说一个容易被忽略的事实：视觉小说在技术上是极其“轻”的品类。它没有物理引擎、没有实时碰撞、没有每帧几十次的状态更新，绝大多数时间画面是静止的，只有文字在动、偶尔一张立绘做个呼吸动画。这意味着如果你单纯以“能不能跑”为标准，一个下午写出的两百行代码就能实现基本演示。但真正决定体验的，是那些不起眼的细节：点击屏幕后文字是瞬间全部显示还是继续等待、快速连点会不会吞掉下一句台词、切后台回来音频是否还在正确位置、存档读档后立绘表情是不是还原到了当时那一帧。
我在早期版本里犯过最典型的错误，是把剧本解释器和渲染层写在同一坨代码里。结果就是“改一个文字显示速度”需要动到逻辑分支的判断，“加一个转场特效”又得回头改解析器。后来重构成四层：剧本层负责把纯文本脚本解析成指令数组；调度层负责按顺序消费指令、维护一个可暂停可回退的执行游标；渲染层只认“当前应该显示什么”这个结果，不关心剧情逻辑；状态层统一管理变量表、已读记录、存档快照。分完之后，加新的大类功能基本只需要动其中一层，调试也方便——哪一层出问题，看日志前缀就知道。
这套分层带来的另一个好处是可测试性。剧本解析器是纯函数，输入脚本字符串、输出指令数组，写断言非常容易；调度层的游标推进也可以脱离浏览器环境跑单元测试。对一个可能只有一个人维护的项目来说，这种“能被验证”的部分越多，后期改动的心理负担越小。
注意：不要一开始就设计“万能指令系统”。我见过有人把指令设计成可以嵌套任意参数对象的通用结构，结果脚本写起来像在写 JSON，美术和文案根本不愿意碰。可读性优先于表达力，这一点在脚本格式上体现得特别明显。
1.2 渲染方案对比：DOM、Canvas 与混合路线
这是绕不开的第一个技术决策，也是争议最多的。我做过完整对比，直接上表：
| 方案 | 文字表现 | 图像与特效 | 内存占用 | 适配与调试 | 适用场景 |
|---|---|---|---|---|---|
| 纯 DOM + CSS | 极好，可直接选中、可无障碍朗读 | 中等，滤镜和复杂合成受限 | 较低 | 最简单，浏览器开发者工具直接改 | 文字量大、交互简单的作品 |
| 纯 Canvas 2D | 需自己实现排版、换行、逐字动画 | 很好，图层自由、可做粒子与滤镜 | 中等 | 较难，出问题看不到节点树 | 演出效果重、有大量动画的作品 |
| DOM 文字 + Canvas 特效层 | 兼顾 | 好 | 中高 | 需要处理两层的坐标对齐 | 中大型项目，我的默认选择 |
| WebGL 全渲染 | 最强 | 最强，可接着色器 | 高 | 门槛最高，着色器调试痛苦 | 有专门图形同学参与的团队 |
我自己的项目最终走的是第三种：文字和 UI 走 DOM，背景、立绘、转场特效走 Canvas。理由很实在——文字用 DOM，字号、行高、字间距、中英文混排、标点避头尾这些排版细节浏览器已经帮你做好了，自己要做的只是控制opacity和逐字span的插入；而需要做溶解、波纹、径向模糊这类转场时，DOM 的 CSS 滤镜在移动端性能很不稳定，Canvas 反而更可控。
坐标对齐是这条路线的唯一麻烦点。我的做法是让 Canvas 和文字容器都放在同一个固定尺寸的“舞台”容器内，舞台用transform: scale()等比缩放，两者内部一律使用设计基准坐标，永不在运行时读window.innerWidth去算位置。这样缩放后的坐标系是统一的，Canvas 的绘制尺寸和 DOM 的绝对定位天然对齐。
1.3 技术栈的减法原则
引擎类项目最容易失控的地方是依赖膨胀。现代前端随便拉一个脚手架就是几百兆的node_modules，对一个静态导出的小引擎来说完全是负担。我的判断标准很简单：这个依赖能不能在打包后体积小于 10KB 且无法用两百行实现。按这条线砍下去，最终留下的大概只有构建工具和一点点工具函数，运行时的核心逻辑全部手写。
这不是为了炫技，是出于实际考虑。引擎往往要嵌入到各种奇怪的宿主环境里——有人把成品塞进桌面端外壳程序里，有人塞进小程序 webview，有人直接本地双击index.html打开。依赖越少，出问题的面越小。我曾经因为一个第三方动画库在某个旧版浏览器里用了不支持的 API，导致整个开场白屏，排查了两个晚上，从那之后核心路径上的依赖就一律自己写。
构建工具方面，我建议保留，但只让它做三件事：代码分割、压缩、静态资源指纹。别用它做花哨的按需加载策略，视觉小说的资源是按场景组织的，你比任何自动策略都清楚该在什么时候预加载什么。
2. 核心模块拆解：脚本解析、演出调度与状态管理
2.1 剧本格式设计：让文案愿意写的才是好格式
脚本格式是整个引擎的“接口”，它决定了文案和程序之间的沟通成本。我试过三种：纯 JSON、YAML、以及自定义的类指令文本。结论是自定义纯文本最受欢迎，因为文案改起来几乎零学习成本，而且 diff 极其清晰。
我的格式长这样：
#scene 01_走廊 @bg bg_corridor_day @bgm bgm_daily @char 主角 left normal @char 学姐 center smile 主角：今天的走廊好像有点不一样。 学姐：你也是这么觉得的吗？ @choice - 追问下去 -> jump 02_追问 - 装作没听见 -> jump 02_回避解析规则非常朴素：#scene开新场景，@开头是引擎指令，-开头是选项，含全角冒号的行是台词（左边角色名，右边文本），空行忽略。这套规则我控制在十条以内，文案看一遍就会写。
这里有个关键的设计取舍：台词行不强加引号。很多引擎要求主角："台词内容"，用起来很别扭，而且中文引号在排版时会和正文的引号混淆。直接以“角色名 + 全角冒号”作为分隔符，解析时按第一个全角冒号切分即可，简单且几乎不会误判——因为对白正文里很少出现“一个纯中文词后紧跟全角冒号”的情况。真遇到了，用转义前缀\处理。
解析器的实现核心就是逐行状态机，这里给一段可以直接用的骨架：
const CMD_RE = /^@(\w+)\s*(.*)$/; const CHOICE_RE = /^-\s*(.+?)\s*->\s*jump\s+(\S+)$/; const LINE_RE = /^([^：\s][^：]{0,15})：(.+)$/; function parseScript(text) { const lines = text.split(/\r?\n/); const scenes = new Map(); let cur = null; let node = null; for (let raw of lines) { const line = raw.trim(); if (!line || line.startsWith('//')) continue; if (line.startsWith('#')) { const tag = line.slice(1).trim().split(/\s+/); if (tag[0] === 'scene') { cur = tag[1]; node = { id: cur, steps: [] }; scenes.set(cur, node); } continue; } if (!node) throw new Error('剧本必须以 #scene 开头'); let m; if ((m = CMD_RE.exec(line))) { node.steps.push({ type: 'cmd', name: m[1], args: m[2].trim().split(/\s+/) }); } else if ((m = CHOICE_RE.exec(line))) { const last = node.steps[node.steps.length - 1]; const opt = { text: m[1], target: m[2] }; if (last && last.type === 'choice') last.options.push(opt); else node.steps.push({ type: 'choice', options: [opt] }); } else if ((m = LINE_RE.exec(line))) { node.steps.push({ type: 'say', who: m[1], text: m[2] }); } else { node.steps.push({ type: 'say', who: '', text: line }); } } return scenes; }注意LINE_RE里角色名限定了最长 15 个字符且不能以空白开头，这是为了防止正文里包含冒号的长句被误判成台词。这个限制在实际项目里几乎不会触犯，但如果你的角色名特别长，记得调这个阈值。
提示：解析阶段一定要做严格报错，把行号带出来。文案写错格式时，报错信息里只说“解析失败”是没用的，必须告诉他“第 47 行：选项缺少 jump 目标”。我在解析器里加行号之后，文案自己就能定位问题，不用每次都来找我。
2.2 执行游标：可暂停、可回退、可序列化的调度核心
调度层是整个引擎的心脏，它的职责是“当前该执行到哪一步”。听上去简单，但一旦引入分支跳转、等待点击、等待动画结束、可回退历史，事情就变得微妙了。
我的实现里，执行状态是一个很朴素的对象：
const runtime = { sceneId: '01_走廊', pc: 0, // 当前场景内的指令下标 vars: {}, // 剧情变量，如好感度 flags: {}, // 已读标记、解锁标记 callStack: [], // 用 jump 之外的 call/return 时用 };每帧（或者说每次“推进”信号）只做一件事：取出steps[pc]，根据类型分派，执行完pc += 1。等待型指令（等待点击、等待转场）不会阻塞循环，而是设置一个waiting标记，主循环看到标记就不再自动推进，直到外部再发一次推进信号。
这个设计的好处是状态完全可序列化。存档就是把这个对象深拷贝一份，加上时间戳和一张缩略图，塞进存储即可。读档就是反序列化回来，然后让渲染层根据当前指令“重建画面”——注意这里是重建而不是重放，重放会慢而且可能触发副作用（比如重新播放一次音效），重建则需要对每个指令都实现一个“应用到当前状态”的幂等操作。
具体做法是给每条指令配一个apply(state)和一个enter(state)。apply用于读档时的静默重建，enter用于正常播放时带演出效果的执行。以背景指令为例：
const handlers = { bg: { apply(state, args) { state.bg = args[0]; }, // 静默设置 enter(state, args, stage) { // 带过渡 return stage.setBackground(args[0], { fade: 300 }); } }, say: { apply(state, args, step) { state.currentLine = { who: step.who, text: step.text }; }, enter(state, args, stage, step) { return stage.typeText(step.who, step.text); } } };读档时按顺序对所有已执行过的指令调用一次apply，最终状态自然收敛到当前画面；正常播放时调用enter，享受完整的演出。这套双通道写法一开始会觉得啰嗦，但它是解决“读档画面不对”这类顽疾最干净的办法。
2.3 演出层：立绘站位、转场与文字打字机
演出效果是最能体现引擎质感的部分，也是最容易做过头的地方。我的经验是：克制比炫技重要。玩家在视觉小说里追求的是沉浸感，过度花哨的转场反而会打断阅读节奏。
立绘站位我用的是“归一化坐标 + 锚点”方案。每个角色位置定义为{ x: 0~1, y: 0~1, anchor: 'bottom' }，渲染时把舞台宽度乘上x得到像素位置。这样做的原因很实际：美术给的立绘尺寸五花八门，有的带透明边、有的画到膝盖、有的画到腰，如果直接按像素定位，换一套立绘就全乱。归一化之后，只要约定“底边对齐舞台底边”，换图基本不需要调参。
主流的三站位（左、中、右）我建议直接在引擎里预设常量，不要每次都让脚本写坐标：
const POS = { left: { x: 0.22, y: 1.0, scale: 0.9 }, center: { x: 0.5, y: 1.0, scale: 1.0 }, right: { x: 0.78, y: 1.0, scale: 0.9 } };左右两侧scale: 0.9是我反复调出来的手感：中间的角色略大一点，视觉重心自然落在正在说话的人身上，两边缩小的同时可以再加一点点透明度和灰度，形成“未聚焦”的感觉。这些细节单看没感觉，但整套叠起来，画面会明显“专业”很多。
文字打字机是另一个细节集中营。三个必须处理的问题：一是富文本标记（比如某几个字加粗变红）要在打字过程中正确处理，不能把标签拆碎；二是快速连点时应该“先补全当前句，再进入下一句”，而不是直接跳两句；三是标点符号后的停顿，句号、省略号、感叹号后面加 80~200ms 的额外延迟，读起来会自然非常多。
第三条是我从纸书排版里学来的。纯匀速逐字显示看起来像机器在念，加上标点停顿后立刻有了语气。实现上就是在逐字循环里判断当前字符是否属于标点集合，是的话额外await sleep(pause)。
2.4 存档系统：别只存一个位置上
新手最常犯的错是只存了“当前场景 + 指令下标”，结果玩家读档回来，好感度变量、已解锁 CG、当前 BGM 位置、立绘表情全部丢失。存档必须存的是完整可还原的画面状态，而不是“读到哪里”这个位置信息。
我的存档结构大致是：
{ version: 3, // 存档格式版本，用于迁移 slot: 1, time: 1712345678901, thumb: 'data:image/jpeg;base64,...', // 128x72 缩略图 snapshot: { sceneId, pc, vars, flags, bg, bgm, chars: [{ id, pos, expr, visible }], currentLine: { who, text, typed: true } } }version字段非常关键。引擎在迭代过程中必然会新增变量、调整结构，老存档读进新版本就是一堆undefined。我的做法是维护一张迁移表，v1 → v2补默认值，v2 → v3重命名字段，读档时按版本号链式升级。这套机制在后期改需求时救了我无数次。
存储介质的选择上，我的分配是：设置项（音量、文字速度、全屏状态）用 localStorage，因为读写频繁且体积小；存档槽位和已读记录用 IndexedDB，因为存档里带的缩略图 base64 可能有几十 KB，localStorage 的 5MB 上限在多槽位下很容易撑爆。IndexedDB 的 API 稍繁琐，但封装一层 Promise 之后就很好用了，键值设计成save_${slot}直接取。
注意：缩略图一定要在存档时现场截取，不要用原始背景图缩放。现场截取能真实反映当前画面（包括立绘和文字框），玩家在存档列表里一眼就能认出这是哪一段。截取方法是用 Canvas 的
drawImage把背景层和立绘层画到离屏画布上再toDataURL，注意文字框不要画进去，否则缩略图全是字看不清。
3. 从零搭一个能跑起来的完整 Demo
3.1 目录结构与资源命名规范
先定结构，结构乱了后面全是麻烦。我用的目录长这样：
project/ ├─ index.html ├─ engine/ │ ├─ parser.js 剧本解析 │ ├─ runtime.js 执行调度 │ ├─ stage.js 渲染与演出 │ ├─ audio.js 音频管理 │ ├─ storage.js 存档与设置 │ └─ main.js 入口装配 ├─ script/ │ ├─ 01_prologue.txt │ └─ 02_meeting.txt ├─ assets/ │ ├─ bg/ bg_corridor_day.jpg │ ├─ char/ ch_senpai_smile.png │ ├─ cg/ cg_01.jpg │ ├─ bgm/ bgm_daily.mp3 │ └─ se/ se_door.mp3 └─ ui/ ├─ textbox.png └─ buttons.png命名规范我强制要求前缀_主体_状态三段式：bg_地点_时段、ch_角色_表情、bgm_场景_变体。原因很实际——后期素材多起来之后，senpai_smile.png、senpai_smile2.png、senpai-smile.png这种混着来的文件名，脚本里引用一定会错。统一规范之后，甚至可以写脚本自动校验“脚本里引用的资源是否都存在”。
这个校验是我强烈建议加的。写一个构建期的小任务，扫描所有脚本里的@bg、@char资源名，去assets目录比对，缺失的直接在构建日志里标红。美术改文件名忘了通知程序，这种事故在多人协作里发生率高得惊人，有了这层校验，至少在发布前能被拦下来。
3.2 舞台缩放：一次算清等比适配
分辨率适配这件事，思路想清楚了其实很简单：定一个设计基准尺寸，之后所有内部逻辑都用这个尺寸内的坐标，只在最外层做一次整体缩放。
我定的基准是1280 × 720。理由是这个比例覆盖了绝大多数横屏设备，而且尺寸适中，美术出图成本可控。缩放公式：
const BASE_W = 1280, BASE_H = 720; function fitStage(stageEl) { const vw = window.innerWidth; const vh = window.innerHeight; const scale = Math.min(vw / BASE_W, vh / BASE_H); stageEl.style.transform = `translate(-50%, -50%) scale(${scale})`; }Math.min保证的是“完整显示不裁切”，代价是可能出现黑边——超宽屏上左右会有黑边，竖屏手机上上下会有大片黑边。我认为这是正确的取舍：视觉小说的画面是精心构图的，裁切掉边缘很可能裁掉关键信息。黑边可以用一层暗色渐变或者装饰边框填掉，观感上完全能接受。
如果想在移动端竖屏也提供好体验，正确做法不是拉伸，而是准备一套竖屏的布局变体：把立绘缩小、文字框上移、背景用cover方式加模糊填充。我的做法是用媒体查询在aspect-ratio < 1时切到竖屏模式，文字框高度从 26% 提到 34%，字号从 28px 提到 30px，立绘整体下移 5%。改动不大，但竖屏下的可读性提升非常明显。
这里顺便说一个坑：移动浏览器的100vh会因为地址栏收缩而变化，导致页面跳动。我的处理是用100%配合html, body { height: 100%; overflow: hidden; }，然后监听resize重新执行一次fitStage。resize事件加 100ms 防抖，避免地址栏动画过程中疯狂重排。
3.3 主循环装配：把四个模块串起来
入口文件的职责就是把解析器、调度器、舞台、音频装起来，跑通“加载 → 解析 → 预载 → 播放”。核心流程：
async function boot() { const stage = createStage(document.getElementById('stage')); const audio = createAudio(); const storage = createStorage(); const raw = await fetch('script/01_prologue.txt').then(r => r.text()); const scenes = parseScript(raw); const rt = createRuntime({ scenes, stage, audio, storage }); await preloadAssets(collectAssets(scenes), (p) => stage.setLoading(p)); stage.hideLoading(); await rt.start('01_走廊'); bindInput(stage, rt); // 点击、回车、空格推进 bindUI(rt, storage); // 存读档、设置面板 } function bindInput(stage, rt) { let lock = false; const advance = async () => { if (lock) return; lock = true; await rt.next(); // next 内部会处理“补完当前句” lock = false; }; stage.el.addEventListener('click', advance); document.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); advance(); } }); }那个lock非常重要。玩家手速快的时候一秒能点五六下，如果没有锁，next()会被并发调用，导致指令游标跳跃、台词错乱。用一个布尔锁串行化是最简单可靠的办法。注意await rt.next()里如果包含长时间动画，锁会让后续点击全部忽略——这通常在转场时是想要的效果，但在打字机阶段玩家希望“点一下补完”，所以next()内部要在动画结束前就返回，把“补完”和“下一句”分成两步。
我用的策略是：点击时先检查是否处于打字中，是则立即补完并返回；否则才推进游标。这样体验最符合直觉。
3.4 预加载策略与进度反馈
视觉小说的加载体验直接影响留存。我的原则是：进入游戏的等待必须有一次，但只此一次。所有场景的背景、常用立绘、BGM 在启动时全量预加载，进度条走完再进标题界面。后续切场景时只对新增资源做增量加载，且必须做在转场动画的掩护下。
预加载的实现用Promise包一层：
function preloadImage(src) { return new Promise((resolve, reject) => { const img = new Image(); img.onload = () => resolve({ src, img }); img.onerror = () => reject(new Error(`图片加载失败: ${src}`)); img.src = src; }); } async function preloadAssets(list, onProgress) { let done = 0; const total = list.length; const results = await Promise.all(list.map(async item => { const r = await (item.type === 'image' ? preloadImage(item.src) : preloadAudio(item.src)); done += 1; onProgress(done / total); return r; })); return results; }进度条不要做成“文件数百分比”这种跳变式的，它会一卡一顿。我的做法是加一层平滑：目标进度用文件数算，显示进度用显示值 += (目标值 - 显示值) * 0.15每帧逼近。视觉上进度条是匀速爬升的，体验好很多。
音频预加载要注意格式兼容。我一般同时准备 mp3 和 m4a 两份，用canPlayType探测后选择。虽然现代浏览器对 mp3 支持已经很好了，但如果目标环境包含一些定制内核的 webview，多一份兜底能省掉很多投诉。
提示：预加载失败的资源不要直接抛错中断整个流程。改成收集失败列表，用占位资源顶上，同时在控制台输出清单。线上环境里网络抖动导致某张图失败太正常了，把整个游戏卡死在一个非关键资源上不值得。
4. 常见问题排查与性能优化实录
4.1 移动端卡顿与内存问题
移动端最常见的抱怨是“玩久了变卡”。我遇到过的原因按出现频率排：图片没释放导致内存持续增长、每帧都在创建新对象触发 GC、以及 Canvas 尺寸过大导致 GPU 上传压力。
第一条的排查方法是打开浏览器性能面板看内存曲线，如果呈现阶梯式上升且从不回落，基本就是图片泄漏。视觉小说的图片生命周期应该跟着场景走：切场景时，不在下一场景资源清单里的图片，应该主动把引用置空并关闭对应的ImageBitmap（如果用了createImageBitmap）。这里特别提醒，用URL.createObjectURL生成的临时地址，用完必须URL.revokeObjectURL，否则那块内存永远不会回收，这是最隐蔽的一种泄漏。
Canvas 尺寸是最容易被忽视的一条。有些人为了“高清”把画布设成3840 × 2160，然后在手机上跑——GPU 纹理上传一次就几十兆，帧率直接腰斩。正确做法是按照实际显示尺寸乘devicePixelRatio来定，并且加一个上限：
function sizeCanvas(canvas, cssW, cssH) { const dpr = Math.min(window.devicePixelRatio || 1, 2); // 上限 2 就够 canvas.width = Math.round(cssW * dpr); canvas.height = Math.round(cssH * dpr); canvas.style.width = cssW + 'px'; canvas.style.height = cssH + 'px'; const ctx = canvas.getContext('2d'); ctx.setTransform(dpr, 0, 0, dpr, 0, 0); // 后续按 CSS 像素作图 return ctx; }dpr上限设 2 是实测结论：超过 2 之后肉眼几乎看不出差别，但填充率翻倍。特别是那些三倍屏手机，老老实实按 3 倍画，中低端机型立刻掉帧。
4.2 音频自动播放限制与播放中断
这条几乎每个做网页游戏的都踩过。浏览器策略规定，没有用户交互的情况下不允许播放音频。视觉小说的标题界面如果自动放 BGM，大概率是静音的。解决方案有两条：要么在标题界面放一个“点击开始”的按钮，把音频上下文在点击回调里初始化；要么在静音状态下先加载，等第一次点击时再resume()。
我倾向于第一条，因为顺手还能当加载门禁。点击开始时同时做三件事：初始化音频上下文、全屏、开始预加载。逻辑清晰，玩家也理解。
另一个高频问题是切后台回来音频错乱。某些浏览器在页面隐藏时会暂停音频，恢复时不自动续播，或者从奇怪的位置续上。处理办法是监听visibilitychange，隐藏时记录当前所有在播音频的时间戳并暂停，可见时按记录的位置currentTime恢复。这个逻辑写起来不长，但不做的话体验会非常割裂。
还有一个细节：BGM 切换时如果直接pause()再换源，会有明显的断音。我的做法是双 buffer，新音频先加载好，用 300ms 的gain淡出淡入交叉过去，听感平滑很多。
4.3 问题速查表
把这两年踩过的问题整理成表，遇到现象直接对号入座：
| 现象 | 可能原因 | 排查与处理 |
|---|---|---|
| 打开一片空白 | 脚本解析抛错，主循环没启动 | 看控制台有无解析异常；解析器加行号输出 |
| 文字显示但立绘不出现 | 资源路径大小写不一致 | 部署环境区分大小写，本地不区分，容易漏 |
| 快点点多了台词跳句 | 推进未串行化 | 加点击锁，或把 next 改为队列消费 |
| 存档读档后立绘表情不对 | 只存了指令位置，未存完整画面状态 | 补实现指令的apply幂等重建 |
| 移动端字号发虚 | 画布未按 dpr 缩放 | 按dpr设置 canvas 尺寸与变换 |
| 转场时画面撕裂 | 动画和渲染帧不同步 | 转场统一走 requestAnimationFrame 时间轴 |
| 后台切回音画不同步 | 音频被系统暂停 | 监听 visibilitychange 记录并恢复 |
| 中文标点显示为方块 | 字体文件未包含对应字形 | 字体子集化时把全角标点纳入范围 |
| 首屏加载超过 10 秒 | 资源总量过大且未压缩 | 图片转 WebP，BGM 降到 96kbps 单声道 |
| 存档列表缩略图全黑 | 截取时离屏画布未绘制完成 | 截取前 await 一次绘制帧 |
字体那条值得单独说一句。中文视觉小说如果用自定义字体，一个字库动辄几兆，全量加载不现实。我是用子集化工具按剧本里出现过的字符生成子集，通常能压到几十 KB。但一定要注意把全角标点、数字、英文字母、以及可能的生僻字都纳入范围，否则会出现一部分字渲染成方块的情况。稳妥点是把常用汉字 3500 字整体打包，压缩后也就一百多 KB，v 划算。
4.4 实测下来最有价值的三条经验
第一条：先做工具，再做内容。在正式写剧本之前，先把“脚本语法检查”“资源引用校验”“一键截图预览”这三个小工具写出来。它们加起来可能只要半天，但能省掉后面几十个小时的排查时间。
第二条：永远在真机上测。桌面浏览器的开发者工具模拟移动端，在音频、触摸事件、字体渲染上都和真机有明显差异。我遇到过只在某个型号手机上出现的文字重影，桌面怎么调都复现不了，最后发现是那个机型对text-shadow的合成实现有问题，去掉就好了。
第三条：把“跳过已读”做对。玩家二周目时最烦的就是重复读已经看过的内容。实现上要在每条台词执行时打一个已读标记（按“场景 + 指令下标”作为键存到 IndexedDB），跳过模式只对已读指令加速，未读的自动停下。这个小功能对体验的提升幅度，远超那些花哨的转场特效。
5. 内容生产工作流与后续扩展方向
5.1 分工协作的接口约定
引擎写完之后，真正的瓶颈会转移到内容生产上。我参与过的几个项目里，最容易出问题的地方不是技术，而是“约定不清晰”。所以我会在项目启动时先把三份约定写下来。
第一份是脚本规范：指令清单、参数含义、命名规则、注释写法。控制在两页纸以内，文案看完能直接上手。
第二份是资源清单表：每一张背景、每一个立绘表情、每一首 BGM，标明文件名、尺寸、时长、用途、所属场景。这份表是美术和程序的共同语言，用表格工具维护，谁改了谁更新。
第三份是验收标准：文字框不超过几行、单句不超过多少字、每个场景的图片总量上限是多少。这些数字看着教条，但能有效防止“文案一段写三百字把文字框撑爆”这类问题。
约定之外，还要有一个“中间产物”的概念。我一般要求文案交脚本时同时交一份纯文本通读稿，方便没有技术背景的成员 review 剧情；美术交图时同时交一张带透明通道的 png 和一份尺寸说明。这些看着是额外工作量，但能大幅降低返工。
5.2 分支剧情的组织方式
分支是视觉小说的灵魂，也是最容易把工程搞乱的地方。我的原则是：场景文件按“最小可复用单元”切分，跳转只跳场景，不在场景内部做复杂跳转。
具体来说，每个.txt文件就是一个场景，内部只有顺序执行和选项；选项的jump目标一定是另一个场景的 id，绝不跳回本场景中间某一行。这条约束看起来限制了很多可能性，实际上它让整个剧情结构变成一张有向图，非常好维护——想知道某个场景被谁引用，全局搜一下 id 就行；想画剧情流程图，把场景和跳转提取出来直接能画。
对于好感度这类变量驱动的分支，我建议把判断逻辑收敛到一个“路由场景”里：
#scene 03_route @if favor >= 5 -> jump 03_good @if favor >= 2 -> jump 03_normal @jump 03_bad所有条件判断集中在这种很短的路由场景里，主剧情场景保持线性。这样改数值平衡的时候，只需要看几个路由文件，不用在几千行剧情里翻找。
变量本身也要有约定。我一般限制在十个以内，命名用英文短词，每个变量在文档里写清楚取值范围和影响的分支。超过十个说明设计可能过度复杂了，需要回头想想是不是能用标志位（flag）代替。
5.3 多语言与跨端发布
多语言的实现方式，我推荐脚本分文件而非运行时替换。也就是script/zh/01.txt、script/ja/01.txt这样按语言分目录，启动时根据设置加载对应目录。这么做的好处是每种语言的断句、语气、甚至分镜节奏都可以独立调整，而不是被原文的结构绑死。运行时替换的方案（用一个 key 去查翻译表）在短句上没问题，但视觉小说的长段落一旦遇到语序差异，翻译出来的句子会非常别扭。
跨端发布这块，静态托管是最省心的。整个项目打包出来就是一堆 html/css/js/图片，扔到任意静态文件服务上即可。如果要做成桌面端应用，用轻量的外壳程序包一层，注意把文件读取路径改成相对路径，别用绝对路径。如果要嵌到移动应用里，注意 webview 的音频策略和本地文件访问权限，通常需要宿主应用配合做一些配置。
我个人建议先把 Web 版打磨到极致，再考虑其他端。因为 Web 版的迭代成本最低，改一个错别字重新上传就行，而打包成客户端之后，每次更新都要走一遍分发流程，调试成本陡增。
5.4 我在实际项目里踩过的几个坑
最后说几个具体到有点“土”的经验，都是文档里不会写、但实际会遇到的。
一是不要在剧本里写绝对路径。有人在@bg里写了assets/bg/xxx.jpg，后来资源目录调整，全量替换脚本，改漏一处就白屏。统一规定脚本里只写资源 id（不带路径和扩展名），路径映射放在引擎的配置表里，改结构只改一处。
二是文字框的行数要用代码限制而不是靠自觉。文案写着写着就超行，超出部分被裁掉，玩家看不到。我在渲染层加了自动检测：如果文字高度超过容器，就在控制台警告并标出是哪一句场景哪一行。有了这个提示，文案自己就会去精简。
三是及时清理测试存档。存档格式升级后，测试机上残留的旧存档会让排查变得极其混乱——你以为是新代码有 bug，其实是旧数据不兼容。我的做法是在开发模式下给存档加一个构建号，构建号不匹配就自动清空并提示。
四是给每个场景加一个“直达”入口。开发期在 URL 上带参数直接跳到某个场景，省去每次从头点的几十秒。这个小功能我每个项目都会加，累计节省的时间非常可观。
这套东西做下来，一个能支撑十万字级别剧本、带分支和存档、在主流手机浏览器上流畅运行的 HTML5 Galgame 引擎就成型了。它没有什么高深技术，难的是把几十个细节都照顾到、并且保持代码结构不随着需求增长而腐烂。我的体会是，这类项目的成败往往不在“能不能实现”，而在“三个月后还敢不敢改”——分层清晰、约定明确、工具到位，才有持续迭代的底气。
