RSTGameTranslation构建与发布完整指南：游戏实时翻译工具的自包含打包、代码签名与杀毒误报规避实践

RSTGameTranslation 是一款开源的游戏实时翻译工具，基于 OCR 屏幕识别 + AI 翻译，把游戏画面上的文字甚至语音实时翻译成中文并覆盖显示。本文面向希望自行构建、打包发布该工具的开发者与进阶用户，完整拆解它的构建与发布流程：如何用 .NET 自包含（Self-Contained）方式产出免安装包的 win-x64 发布包、为什么刻意放弃单文件模式、如何通过代码签名与构建参数规避杀毒软件误报，以及版本号是如何在整个项目中保持同步的。

一、发布前置：一份"免安装"的构建产物

打开项目文件 RST.csproj 可以看到核心构建配置：

• <RuntimeIdentifier>win-x64</RuntimeIdentifier>：目标平台固定为 Windows x64
• <SelfContained>true</SelfContained>：自包含发布，把 .NET 运行时一起打进发布目录，用户无需安装 .NET SDK 即可直接运行rst.exe
• <PublishSingleFile>false</PublishSingleFile>：明确关闭单文件模式（原因见下文第三节）

自包含模式的代价是体积（运行时 DLL 会全部随包发布），但对游戏翻译工具这类面向普通玩家的桌面应用来说，"解压即玩"远比包体积重要。

另外 app.manifest 声明了requireAdministrator权限和 PerMonitorV2 高 DPI 感知——前者用于屏幕捕获与覆盖层渲染，后者保证翻译覆盖层在多显示器混用缩放比时不模糊。

二、一键发布脚本：MakeReleaseZip.bat 全流程拆解

项目的发布入口是 MakeReleaseZip.bat，在 Windows 上依次完成 6 个步骤（前置依赖：.NET 9 SDK、Node.js、7-Zip）：

其中第 5 步有几个值得注意的细节：

• AudioModel\ggml-tiny.bin：语音转文字的 ggml 小模型，发布时预置，用户无需首次启动再下载
• Supertonic目录：只预创建空目录，约 400 MB 的 TTS 模型由应用内一键下载器按需拉取
• onnxruntime.dll的保真复制（MakeReleaseZip.bat#L33-L35）：脚本刻意用发布目录里 NuGet 带的 OnnxRuntime 运行时覆盖旧文件，并删除.lib文件。注释里写明原因——OneOCR 的oneocr.dll与 Supertonic TTS 依赖同一个 Microsoft.ML.OnnxRuntime 1.20.1，若混用不同版本的托管封装层与原生运行时，应用会在启动时静默崩溃。

三、为什么放弃单文件模式：一个 190 MB 的"坑"

MakeReleaseZip.bat#L11-L16 的注释记录了一次真实的踩坑经历，这也是构建发布中很有参考价值的一课：

开启PublishSingleFile=true后，包括Microsoft.ML.OnnxRuntime.dll在内的托管程序集会被捆绑进单个rst.exe（约 190 MB）。此时 ONNX Runtime 的原生加载器路径不可靠，当用户配置tts_service=Supertonic时，应用在首次启动即崩溃。

最终决策是：保持默认的多文件自包含发布，让所有 DLL 与rst.exe并排放置——这正是日常dotnet build输出目录下已被验证可靠的布局。

经验总结：单文件模式对含原生依赖（ONNX、CUDA 等）的应用并不总是安全的，"能跑的多文件"优先于"好看的文件数"。

四、规避杀毒误报：构建层面的四个关键设置

未签名的屏幕捕获类工具是杀毒软件启发式查杀的重灾区。项目在 RST.csproj#L33-L53 中针对误报做了四组工程化处理：

1. 补全程序集元数据（RST.csproj#L34-L42） 填充Company、Product、Authors、Description、Copyright等字段。带有完整身份信息二进制的"路人感"更低，有助于杀软启发式规则判定其合法性。

2. 确定性构建（<Deterministic>true</Deterministic>） 相同源码永远产出完全一致的二进制。这意味着社区可以长期积累对同一构建的信任（如安全社区白名单），新版本哈希可复现、可验证。

3. 附带 PDB 调试信息（<DebugType>portable</DebugType>） 注释直接写道："AV engines trust binaries with debug info"——带调试信息的二进制更容易被杀软识别为正规开发产物。注意这里用portable而非embedded，因为 CsWinRT 的 IIDOptimizer 需要独立的 PDB 文件。

4. 关闭 IL 裁剪（<PublishTrimmed>false</PublishTrimmed>） 裁剪后的程序集结构异常，是触发杀软启发式误报的常见因素，项目选择放弃少量体积换取更低的误报率。

五、代码签名：用 SignPath 让 Windows 不再"拦路"

即使做了上述构建优化，未签名程序首次运行仍会触发 Windows SmartScreen 的"未识别的应用"提示。RSTGameTranslation 的解决方案是：使用 SignPath.io 提供的免费代码签名服务（证书由 SignPath Foundation 签发，在 README.md 致谢部分有注明）。

代码签名对玩家的实际价值：

• 🛡️ 显著降低 SmartScreen 拦截概率
• 🔍 Windows Defender 等杀软会直接信任已签名发布方的历史信誉
• 📦 配合确定性构建，签名还能保证"你下载到的文件与开发者发布的完全一致"

六、版本号同步机制：一个 JSON 驱动三处更新

发布流程中的版本管理值得单独说明，整个项目用一份 media/latest_version_checker.json 作为"单一事实来源"：

{ "name": "Real Time Game Translation", "latest_version": 6.1, "message": "Download V{VERSION_STRING} now from github?" }

它驱动三个位置保持同步：

1. 落地页：update-version.js 读取 JSON 中的latest_version，用正则更新 index.html 与 index_vi.html 中的版本徽章（英文Version x.x与越南语Phiên bản x.x双份文案）
2. 应用内版本检测：src/SplashManager.cs#L40-L46 中CurrentVersion常量记录当前版本，启动画面会加载该 JSON 远程文件比对，发现新版本即提示用户前往 Releases 页下载
3. 发布包文件名：MakeReleaseZip.bat 顶部APP_VERSION=6.1决定最终 zip 命名（RSTGameTranslation_v6.1.zip）

一个小的版本格式化细节（src/SplashManager.cs#L42-L45）：热修复版本如 5.85 若用"F1"格式化会被四舍五入成 "5.8"，导致更新检查"下载回旧版本"的 bug，因此改用"0.0#"格式保留必要的第二位小数——这是构建发布流程中一个极易踩、又极难排查的版本管理陷阱。

总结

RSTGameTranslation 的构建发布实践可以浓缩为五条经验：

1. 自包含多文件发布优先于单文件——原生依赖（ONNX Runtime）会打破单文件加载路径
2. 发布脚本化：clean → publish → 组装模型/语言资源 → 7z 打包，一条 bat 跑完
3. 用程序集元数据 + 确定性构建 + PDB + 关闭 IL 裁剪四板斧压低杀软误报
4. 代码签名（SignPath 免费签名）是消除 SmartScreen 警告的最后一块拼图
5. 单一 JSON 驱动落地页、应用内更新检查与包名三处版本号，避免"改一处漏两处"

按照 MakeReleaseZip.bat 的流程，任何一台装有 .NET 9 SDK 与 7-Zip 的 Windows 机器都能在几分钟内复现出与官方一致的发布包。