网页文字单机模组整合：分层加载、汉化注入与存档隔离

写给同样在这个坑里折腾过的朋友：单机文字类作品玩到一定深度，几乎都会走上一条路——装模组。可一旦模组数量上去，改过的资源、汉化文本、自定义界面、平衡性调整就会互相踩踏，最后游戏打开是一片白屏，或者干脆卡在加载页。这篇要聊的，就是围绕《Degrees of Lewdity》这类以文字叙事为核心、基于网页引擎构建的开源单机作品，怎么用一套“模组整合”的思路把定制化体验稳稳落地：什么是整合器、它解决了哪些具体问题、适合什么基础的人照着做。我自己从最早手动解压覆盖文件，到后来写脚本做清单管理、做本地化注入、做版本对齐，中间踩的坑不算少，这里把设计取舍和实操细节都摊开讲清楚，能直接抄的部分我会给到可运行的结构。

1. 先弄清“整合”到底在解决什么问题

很多人对“模组整合”的理解停留在“把一堆文件塞进同一个文件夹”。这在小体量下勉强能跑，但文字类单机作品有个特点：它的逻辑几乎全部承载在脚本和文本资源里，一个模组的改动往往横跨界面结构、事件分支、数值定义和语言文本四个层面。你手动覆盖，本质上是把前一个模组的改动直接抹掉，且没有任何记录。整合器真正的价值不是“打包”，而是把“谁改了哪一层、按什么顺序生效、出问题怎么退回去”这件事变成可控的、可追溯的工程行为。

1.1 手动覆盖文件的三种翻车现场

第一种是静默覆盖。两个模组都改了同一个界面模板文件，你后装的赢，前一个的功能悄悄消失，游戏不报错，你只会觉得“这个模组好像没生效”。这类问题最难查，因为没有异常，只有“感觉不对”。

第二种是半覆盖导致的结构残缺。某些模组的资源是一个完整的目录树，你只替换了其中一部分文件，剩下的还是旧版本，于是出现“按钮点得动但弹窗是空的”这种诡异状态。文字引擎渲染界面通常依赖模板和脚本的字段一一对应，缺一个字段就是一片空白。

第三种是存档污染。这是最疼的。模组改动如果在运行期往存档里写了自定义字段，你卸载模组后再读档，引擎读到未知字段，轻则丢数据，重则整个存档无法解析。而且文字类作品的存档往往是纯文本序列化，一旦结构错乱，手工修复的成本极高。

注意：只要你的操作会改动运行期数据结构，就必须先备份存档目录，且备份要带时间戳。这不是谨慎，是底线。

我做整合器的第一个决定就是：永远不直接改原始游戏目录。所有模组改动都落在一个独立的层里，原始资源只读。这样无论怎么折腾，删掉整合层就能回到干净状态，这是后面所有回滚能力的基础。

1.2 中文玩家绕不开的三件事

第一是文本长度差异。中文的字符宽度和英文不一样，同一段话，英文 80 个字符换行刚好，中文 40 个字可能就撑破容器。很多界面在英文下完美，汉化之后按钮文字溢出、选项框高度错位。整合器如果只做“文本替换”不做“排版补偿”，用户第一眼看到的还是坏的。

第二是编码一致性。网页引擎默认按 UTF-8 解析，但模组来源五花八门，有的文件是 GBK、有的是带 BOM 的 UTF-8。混合之后典型的症状是“部分界面显示成方块或者问号”，而错误信息根本不指向具体文件。

第三是版本追赶。这类作品更新频繁，每次上游改动都可能让一批模组失效。中文玩家还多一层：汉化文本基于旧版本翻译，新版本新增的段落没有对应译文，于是出现中英混排。整合器需要能标记“哪些键没有译文”，而不是粗暴地整段回退成英文。

这三件事决定了整合器不能只是一个文件复制工具，它至少要有优先级模型、编码归一化、文本键映射表三样东西。

2. 整合器的架构：分层加载与优先级模型

整体思路我参考了常见的资源覆盖模型：底层是原始资源，中间是若干模组层，顶层是用户个性化配置。加载时按优先级从低到高叠加，高优先级覆盖低优先级，但覆盖的粒度是“文件”而不是“整个目录”。这样 A 模组改界面、B 模组改数值，两者互不干扰。

2.1 目录分层与覆盖顺序怎么定

我最终用的结构是这样的：

game_root/ core/ # 原始资源，只读，永不修改 mods/ 10-base-framework/ # 数字前缀即优先级，越小越先加载 20-ui-tweaks/ 30-localization-zh/ 90-user-overrides/ # 用户自己的临时改动，永远最高 loader/ manifest.json runtime.js

数字前缀这个设计看着土，但极其实用。原因有三个：一是排序直观，新人一眼能看懂谁覆盖谁；二是插入新模组不用改配置文件，改个文件夹名就行；三是出问题时按数字顺序二分排查，效率极高。我试过用配置文件显式声明顺序，结果用户一旦手动删了某个模组，配置里的顺序引用就悬空，加载器直接崩。文件名排序虽然不够优雅，但没有状态，这点在分发场景下价值巨大。

具体的覆盖规则我定为：同路径文件，高优先级整体替换；不同路径，各自保留。不做行级合并。为什么不做行级合并？因为网页资源里 JS 和模板文件做行级合并几乎必然产生语法错误，合并的收益远小于风险。真要细粒度改动，让模组作者自己提供补丁脚本，而不是让加载器去猜。

提示：90-user-overrides这一层不要省。用户想临时改一个数值或者换一张图，直接扔进去就行，不用动任何模组文件，也不影响下次更新。

2.2 模组清单该写哪些字段

每个模组目录下放一个mod.json，字段不多，但每个都有明确用途：

gameVersion这个字段我认为是最重要但最容易被忽略的。它的写法建议用区间表达式，比如>=0.4.0 <0.5.0。加载器在启动时读一次上游版本号，落在区间外就弹提示而不是直接崩。很多“装完打不开”的问题，本质就是版本错配，有了这个字段，用户至少知道原因。

textKeys是我后来加的。它让整合器能算出“当前安装的模组里，有多少文本键已经有中文译文”，直接在设置页显示一个覆盖率百分比。这个数字看着不起眼，但它能有效减少“为什么这里还是英文”的重复提问。

2.3 汉化注入走文本替换还是运行时钩子

这是架构上最需要想清楚的一个岔路口。

文本替换路线：构建阶段把原文键值对里的值替换成中文，产出一个完整的、已汉化的资源包。优点是运行时零开销，出的问题都在构建期暴露；缺点是每次上游更新都要重新走一遍构建，且无法在运行时切换语言。

运行时钩子路线：保留原始文本，在引擎取词的时候拦截，查一张映射表返回中文。优点是可以做多语言热切换、可以只加载部分译文；缺点是要精准找到引擎的取词入口，且一旦引擎内部实现变了，钩子就失效。

我的选择是两者结合：构建阶段做静态替换产出主包，同时对少量动态拼接的文本保留运行时查表兜底。理由是，网页文字引擎里大部分叙事文本是静态的，静态替换最稳；但界面提示、数值格式化这类动态文本必须走运行时。纯静态会漏，纯运行时风险高，混合方案的实际维护成本最低。

具体怎么找到取词入口？我的做法不是去逆向，而是在资源里全局搜索原文的完整句子，定位到它被定义的位置，看它是以什么形式存在的——是直接写在模板里，还是存进某个字典对象。前者用构建期替换，后者在字典对象加载完成后追加一次合并。这样不需要理解引擎全貌，只需要处理“文本存在哪里”这一个问题。

3. 核心环节实现：从清单解析到运行时注入

这一节给的是可以直接跑起来的骨架。语言我选 JavaScript，因为最终产物要在浏览器环境里加载，用同一种语言能省掉一层胶水。

3.1 依赖解析与加载顺序的拓扑排序

先扫描mods/下所有mod.json，建图，再做拓扑排序。这里有个细节：优先级和依赖是两套顺序，冲突时以依赖为准。也就是说，如果 A 依赖 B，但 A 的目录前缀比 B 小，仍然要让 B 先加载。否则依赖方拿不到被依赖方的资源。

function resolveLoadOrder(mods) { const byId = new Map(mods.map(m => [m.id, m])); const visited = new Map(); // id -> 0 未访问 / 1 访问中 / 2 已完成 const order = []; function visit(id, stack) { const state = visited.get(id) ?? 0; if (state === 2) return; if (state === 1) { throw new Error(`依赖成环: ${[...stack, id].join(' -> ')}`); } visited.set(id, 1); const mod = byId.get(id); if (!mod) throw new Error(`缺少依赖: ${id}`); for (const dep of mod.depends ?? []) { visit(dep, [...stack, id]); } visited.set(id, 2); order.push(mod); } const sorted = [...mods].sort((a, b) => (a.priority ?? 999) - (b.priority ?? 999)); for (const m of sorted) visit(m.id, []); return order; }

这段代码不长，但解决了一个很实际的问题：依赖成环时给出完整路径。我见过太多加载器在成环时只报一句“循环依赖”，用户完全不知道该删哪个。把栈打出来，问题基本一眼定位。

3.2 文本替换引擎的匹配策略

匹配策略上我吃过一次亏。最初用简单的字符串全局替换，结果一个短词被误伤——原文里“打开”这个词在某处是动词、在另一处是名词短语的一部分，全局替换后语义全乱。后来改成只在文本节点粒度上替换，也就是先按结构把资源拆成“键 → 值”的映射，替换发生在值这一层，绝不跨结构替换。

具体实现分三步：

1. 抽取：把资源里的文本按句子切分，生成原文 → 出现位置列表的索引。
2. 翻译表：中文译文以原文为键、译文为值，独立成文件，方便多人协作和增量更新。
3. 回填：按索引逐个位置替换，替换时校验目标位置当前内容是否仍等于原文，不等于就跳过并记录警告。

第三步的校验是防止版本漂移的关键。上游一更新，某些原文改了，你的翻译表里还是旧的键，直接替换会破坏新内容。有了校验，不匹配的自动跳过，日志里能看到“有 N 条译文因原文变更失效”，维护者据此更新即可。

function applyTranslation(resource, dict, report) { for (const node of resource.textNodes) { const zh = dict[node.raw]; if (zh === undefined) { report.missing.push(node.raw); continue; } if (node.raw !== node.current) { report.drifted.push({ key: node.raw, at: node.locator }); continue; } node.current = zh; } return resource; }

drifted这个报告项是我加的第二个东西。它比missing更有价值——missing只是漏翻，drifted意味着你的译文可能已经和游戏内容对不上了，属于潜在的错误信息。我一般会把它单独列出来优先处理。

3.3 配置与存档的隔离

文字类作品的配置和存档通常落在浏览器的本地存储里。整合器如果不做隔离，用户换一套模组组合就得重新配置一遍，体验非常糟。

我的做法是给本地存储的键加一层命名空间前缀，前缀由当前启用的模组组合指纹生成：把已启用模组的id@version排序后取哈希，取前 8 位。这样：

• 同一套组合多次启动，指纹一致，配置和存档连续；
• 换一套组合，指纹变化，走的是另一份配置，互不污染；
• 想回到旧组合，指纹还原，配置自然回来。

async function comboFingerprint(mods) { const sig = mods .filter(m => m.enabled) .map(m => `${m.id}@${m.version}`) .sort() .join('|'); const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(sig)); return [...new Uint8Array(buf)].slice(0, 4) .map(b => b.toString(16).padStart(2, '0')).join(''); }

这个方案有个副作用要提前说清楚：同一份存档不能跨组合直接迁移。用户如果想把进度带到新组合，需要走一个导出导入流程，导出时把存档内容序列化，导入时做字段校验和补全。我在实现里加了一个“宽松导入”开关，允许缺字段时用默认值补齐，代价是可能丢少量自定义数据，但比直接打不开强。

注意：命名空间前缀一旦确定就不要再改算法。改一次，所有用户的旧配置全部失联，这是最容易被骂的改动。

3.4 一个可以直接抄的目录骨架

把上面几块拼起来，实际可用的骨架长这样：

game_root/ core/ # 原始资源，设只读 mods/ 10-base/ mod.json assets/ patches/ 30-localization-zh/ mod.json dict/zh-CN.json layout-fix.css 90-user-overrides/ loader/ manifest.json # 构建产物，记录每层文件哈希 runtime.js # 加载器本体 saves-backup/ # 每次启动前自动快照

layout-fix.css这一项值得单独提。中文排版补偿我全部收敛到一个 CSS 文件里，通过加载器在页面渲染前注入。里面主要做三件事：把常用容器的line-height调大一档、给按钮加white-space: normal允许换行、给长文本容器加word-break: break-word。这三条能解决八成以上的中文溢出问题，成本极低，收益极高。

4. 打包分发与更新：让整合包活得久一点

整合包做出来只是开始，真正的考验是第二周——上游一更新，用户全跑来问“还能用吗”。这一块的设计目标很明确：让用户永远知道自己装的是什么版本、兼容不兼容、出了问题怎么退。

4.1 构建脚本与完整性校验

构建阶段我做了一件事：遍历最终产物，对每个文件算哈希，写进loader/manifest.json。启动时加载器先校验清单，发现某个文件哈希对不上，直接提示“文件被修改或不完整”，而不是带着损坏状态往下跑。

#!/usr/bin/env bash set -euo pipefail OUT=dist/pack rm -rf "$OUT" && mkdir -p "$OUT" cp -r core "$OUT/" for d in mods/*/; do cp -r "$d" "$OUT/mods/$(basename "$d")" done node loader/build-manifest.js "$OUT" > "$OUT/loader/manifest.json" echo "构建完成，共 $(find "$OUT" -type f | wc -l) 个文件"

这个校验带来的最大好处是排错时可以排除一整类原因。用户报“打不开”，第一句话我就问：清单校验过了吗？过了，问题在加载逻辑；没过，问题在文件完整性。二分一次，排查范围砍一半。

4.2 版本号对齐与增量更新

版本号我用三段式：上游主版本.整合包序号.修正号。举例，0.4.2.7.1表示适配上游 0.4.2 的第 7 版整合、第 1 次修正。这个命名看着啰嗦，但它解决了一个核心问题：用户能自己判断能不能升。

增量更新我只做一件事：把模组按目录拆成独立压缩单元，构建时记录每个单元的内容哈希。更新时只下发哈希变化的单元，用户端合并。这样一次常规更新往往只有几 MB，而不是每次重下几百 MB 的整包。代价是合并逻辑要处理“删除的文件”——上游删了一个文件，增量包必须显式带删除指令，否则旧文件残留在层里继续生效，产生极难排查的“幽灵 bug”。我在清单里专门加了removed数组来处理这个。

第三行那种情况，我的处理是不自动更新，只提示。让用户自己决定什么时候大版本迁移，比自动推送安全得多。

4.3 分发形态的取舍

分发形态我试过三种：整包压缩、安装器程序、纯网页加载本地目录。最终保留的是整包压缩 + 可选网页加载。

整包压缩的好处是简单，用户解压即用，不依赖任何系统权限，出问题也好定位。安装器的体验更好，但引入了一层系统交互，杀软误报、权限申请、卸载残留，每个都是麻烦。纯网页加载（用户手动选目录）最灵活，适合开发调试，但对普通用户门槛太高。

最后我的做法是：默认整包，调试模式提供一个“加载本地目录”的入口。两边的好处都能吃到，代价是加载器要同时支持两种资源来源，多写一个适配层，大概两百行代码。

5. 排错实录：冲突、乱码与存档异常

这部分是我认为最有价值的内容，因为是文档里绝对不会写的。下面这些症状我都实际遇到过，处理路径也验证过。

5.1 症状速查表

白屏这一类我多说一句。永远先看控制台第一条错误，不要看最后一条。第一条往往是根因，后面全是连锁反应。很多人截图给我看最后一条“undefined is not a function”，其实真正的问题在前面某个模板变量没定义。

5.2 文本溢出与排版错乱

中文排版问题我总结出一个优先级顺序，按这个顺序改，基本不用反复试：

1. 先调行高，不动字号。中文字符的视觉重心比英文低，行高从 1.2 调到 1.5，观感改善最明显，且不会破坏原有布局的计算。
2. 再放开换行限制。很多按钮样式写了white-space: nowrap，英文短词够用，中文四个字就爆。改成normal并配合min-height兜底。
3. 最后才动宽度。宽度一改，整个栅格都可能塌，属于最后手段。

我还加了一个运行时溢出检测，只在调试模式开启：遍历所有文本节点，比较scrollWidth和clientWidth，超出的在元素上加一个红色描边。这样扫一遍界面，哪里溢出标注得一清二楚，不用一个个点。

5.3 存档损坏后的应急处理

这是最需要预案的场景。我的做法是三层防护：

第一层，启动前自动快照。每次启动把当前本地存储内容序列化一份，写到saves-backup/下，带时间戳，只保留最近 10 份。这个成本几乎为零，但救命次数最多。

第二层，导入时的结构校验。导入存档时先解析，检查必需字段是否存在、类型是否正确。不通过不写入，只提示。

第三层，宽松模式。用户明确选择“强制导入”时，缺字段用默认值补，多余字段直接丢弃。这一步会丢数据，所以必须让用户知情，界面上明确写“可能丢失部分自定义数据”。

有一次我自己踩的坑是：快照逻辑写在了加载完成之后，结果加载阶段就崩了，快照根本没来得及生成。后来改成在任何资源加载之前先做快照，这个顺序问题看起来很傻，但它导致的是一整天的进度丢失。

6. 踩坑之后沉淀的几条经验

写到这里，几个技术点都摊开了。最后分享几条不太像技术、但实际影响很大的体会。

6.1 关于“最小可运行版本”

我一开始就想着把功能做全：自动更新、多语言热切换、可视化模组管理界面。结果是三周过去，连一个能启动的版本都没有。后来砍到只剩“按目录优先级加载 + 静态文本替换 + 文本键校验报告”三件事，两天就跑通了。有了能跑的东西，后面所有功能都是加法，加一个测一个。反过来，如果地基一直不稳，你加的任何功能都只是让调试范围变大。

我的建议是：第一版永远只做“能启动 + 能回滚”。能启动证明加载链路通了，能回滚证明隔离机制有效。有了这两条，剩下的都是可迭代的。

6.2 关于文档

整合包的文档，我最后悔的是最初按“功能模块”组织，写了一堆“优先级机制说明”“文本注入原理”。用户根本不看。后来改成按场景组织，标题全是“打开就白屏怎么办”“中文挤在一起怎么办”“更新后存档读不了怎么办”，询问量直接掉了七成。

结论很简单：用户不是来学架构的，是来解决问题的。文档的目录就应该是故障现象目录。原理可以放附录，但入口必须是症状。

还有一条：每个模组目录里放一个README.md，写清楚它改了哪些路径。这个成本很低，但当你想排查“到底是谁改了这个文件”的时候，它就是唯一的信息源。我后来在加载器里加了个功能，能直接列出“某个路径被哪些层覆盖过”，这个功能的数据来源就是各模组的清单，而清单的维护动力就来自 README——作者写明白了，用户才好排查。

6.3 关于“不要相信用户的描述”

用户说“我什么都没改”，通常意味着“我改了我认为不重要的东西”。所以加载器的日志要足够细：每次启动记录加载了哪些模组、什么顺序、哪些文件被覆盖、哪些译文发生漂移。日志不必展示给所有人，但必须存在，且一键导出。有了完整日志，八成的问题描述不准确都能自动纠正。

我自己现在遇到报错，第一件事就是要日志，而不是要截图。截图看到的是结果，日志看到的是过程，过程才能定位原因。