企业官网建设流程全解析

LunaTranslator 视觉小说实时翻译：下载部署、首次启动与报错自查终极指南

【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator

LunaTranslator 是视觉小说实时翻译工具：它通过 HOOK（往游戏进程里注入一段代码、从里面读出正在显示的文字）、屏幕 OCR 或剪贴板拿到原文，再交给内置的数十种翻译引擎即时出译文，让没有官方中文的游戏也能边玩边读。照本文操作，你能独立完成选包、解压、启动、更新和常见报错自查，全程不用再翻官方文档。

它适合谁：先用场景判断值不值得装

它管用的场景：

• 视觉小说 / Galgame 没有官方中文，想用 HOOK 直接读游戏内文字
• 模拟器游戏（PS2 / PSP / NS 等）里文字读不出来，改用 OCR 认屏幕
• 看图、读文档、剪贴板批量过一遍译文
• 需要把译文嵌回游戏窗口（支持内嵌翻译的游戏）

别指望它的场景：

• 大型 3A 整句剧情实时跟翻——它的设计对象是视觉小说式短文本
• 专业术语密集的学术论文翻译
• 非 Windows 平台：它深度依赖 Windows 的进程注入与 Hook 机制

该拿哪个版本包：默认推荐 + 例外

默认答案只有一个：Windows 10 1803 及以后 / Windows 11，直接拿 64 位主版本包（x64_win10）。这是主力构建目标，高 DPI、DirectML 加速等特性都只在这套里。

例外情况用下表核对，别拿错：

| 你的系统 | 该拿的包 | 备注 | | - | - | - | | Windows 11 / Windows 10 1803+ | 64 位主版本包（x64_win10） | 默认推荐，体验与功能最全 | | Windows 7 ~ Windows 8.1 | 旧系统兼容包（x64_win7） | 能升级就别用：性能、稳定性缩水，杀软误报更多 | | Windows XP / Vista | 仅 32 位兼容包（x86_winxp） | 无 64 位可选，属极限兼容 |

源码里这个划分有据可查：src/LunaTranslator/gobject.py按系统版本挑 Python 运行时目录（runtime3.13-64、runtime3.7-64、runtime3.4-32等），并维护sys_win10_release_supported、sys_le_win7、sys_le_xp等判定标志，启动时据此决定加载哪套运行时。拿错包，启动就会缺组件。

三步装好：每步一个坑

1. 下包：从官方发布页拿对应版本的新包。坑：别拿老版本存档里的旧包，杀软规则早就变了。
2. 解压到一个你有完整读写权的普通目录（数据盘自建文件夹、用户目录都行）。坑：别解压进C:\Program Files这类受保护路径——原因一句话：Windows 的 UAC（用户账户控制，系统对普通进程访问受保护目录的默认拦截机制）会让程序写不进自己的配置和缓存，轻则报错，重则起不来，提权也救不干净。
3. 启动前扫一眼目录：确认LunaHook目录、Magpie目录、runtime3.13-64这类运行目录都在。坑：HOOK 靠往游戏进程注入 DLL（LunaHost32/64.dll、LunaSubProcess32/64.exe就是干这个的），这类文件天然容易被杀软当病毒隔离——刚解压就挨一刀很常见，组件不全直接启动失败。

如果目录完整却仍启动报错，跳到下方「诊断卡」按现象处理。

启动入口与十秒自检

三个入口按用途选：

| 入口 | 用途 | | - | - | |LunaTranslator.exe| 日常入口：HOOK 游戏、OCR、剪贴板，普通权限即可 | |LunaTranslator_admin.exe| 仅当游戏必须以管理员身份运行、普通权限注入不进去时用它 | |LunaTranslator_debug.bat| 启动时带命令行窗口，看日志排查问题 |

启动后 10 秒自检：主界面应完整加载、不弹任何错误框；接着切到 OCR 模式，框选屏幕上任意一段有字的区域（文档、网页都行），能识别出原文并出译文，说明「取文 → 翻译」链路已经通了。这一步同时验证了 OCR 组件与翻译引擎配置，比干等游戏连接更快。

一个值得知道的细节是单实例机制：程序用userconfig配置目录的绝对路径做哈希生成互斥量（操作系统提供的命名锁，同一时刻只允许一个进程持有），因此用--userconfig <路径>参数各开各的配置档案时互不干扰；普通模式下若检测到已有同类实例，会弹窗询问是否再启动。这套逻辑在src/LunaTranslator/main.py的启动流程里可以逐段对照。

更新机制与必须保住的目录

自动更新默认开启（autoupdate开关），拆成 4 个动作，实现在src/LunaTranslator/myutils/updater.py：

1. 查询：versioncheckthread线程向主服务器请求/version接口，带arch（x86/x64）与target（winxp/win7/win10）参数，拿回最新版本号、下载链接和 sha256（文件指纹，用于确认包没损坏）。
2. 比对：读本地 exe 的版本号，只有远端更新、且autoupdate为开才继续。
3. 下载校验：流式下载更新包并显示进度，下完核对 sha256。
4. 退出替换：新包解压到cache/update目录，提示「将在退出后更新」；程序完全退出后由LunaSubProcess拉起Updater.exe完成文件替换——更新从不和运行中的文件抢锁。

铁律：userconfig目录必须保住。它是全局配置、各翻译引擎自定义脚本副本的存放地，删掉就等于全部设置清零。手动更新更简单：新包解压直接覆盖到原目录，旧配置原样保留。想要多套配置档案，各建一个目录并用--userconfig <路径>启动即可。

诊断卡：六张常见故障速查

| 现象 | 判断 | 解决 | | - | - | - | | 启动即提示「找不到重要组件」或 Missing embedded Python3 | 杀软隔离了注入类文件或整段删掉了内嵌运行时目录（完整性清单见src/LunaTranslator/myutils/config.py的checkintegrity()） | 关闭杀软，或 Defender 走「病毒和威胁防护 → 排除项 → 添加排除范围 → 文件夹」把 Luna 目录加进去，然后重新下载并解压让组件回来 | | 启动报 Error/PermissionError | 解压在C:\Program Files等受保护路径，配置与缓存写不进去 | 整个目录原样挪到普通可写文件夹再启动 | | HOOK 选完进程，一直停在「正在等待 DLL 注入到游戏中……」 | 注入用 DLL 被杀软隔离，注入自然完不成 | 同上：加信任 + 重新解压，补齐LunaHook目录与子进程组件 | | 跑了几小时，到选进程时才报 Error/FileNotFoundError | 杀软后台扫描的延迟清理——启动时组件还在，后台扫描才删掉，真正用到时暴露 | 提前把目录加入排除项并重新解压，让组件全程完整 | | 界面提示「自动更新失败，请手动更新」 | 网络不通或 sha256 校验未通过 | 手动下载新包，解压覆盖到原目录，userconfig不动 | | HOOK 连上游戏，候选文本行一直是空的 | 游戏当时没显示文字，或选错了同名进程 | 让游戏跑一段把文字显示出来，候选行会刷新后再选 |

参考资料

• 下载与常见错误总览：docs/zh/README.md
• 基本用法（HOOK / OCR / 拖拽快捷启动）：docs/zh/basicuse.md
• HOOK 模式设置：docs/zh/hooksettings.md
• OCR 参数说明：docs/zh/ocrparam.md
• 主入口与单实例逻辑：src/LunaTranslator/main.py
• 组件完整性检查：src/LunaTranslator/myutils/config.py
• 更新机制：src/LunaTranslator/myutils/updater.py
• 配置目录与平台判定：src/LunaTranslator/gobject.py

【免费下载链接】LunaTranslator视觉小说翻译器 / Visual Novel Translator项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTranslator