LunaTranslator 快速上手：视觉小说实时翻译工具的版本选择、部署与启动指南

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

LunaTranslator 是一款面向视觉小说的实时翻译工具：它通过 HOOK 注入读取、屏幕 OCR 或剪贴板监听拿到游戏里的外文原文，再交给内置的多种翻译引擎即时产出译文，让没有官方中文的游戏也能边玩边读。本文按「先跑起来，再按场景查问题」的顺序组织，读完后你可以独立完成下载选版、免安装部署、三种入口的启动方式，以及更新与常见报错的处理。

第一次跑通：选版本、放目录、点入口

按系统版本选构建包

选版本只需要回答一个问题：你的系统是 Windows 10（1803 及以后）还是 Windows 11？

• 是的话，下载 64 位主版本即可。这是默认构建目标，功能最全，高 DPI、DirectML 等特性都包含在这一套里。
• 如果是 Windows 7 及更早的旧系统，可以选择 32 位或 64 位的兼容包。官方说明这类版本性能与稳定性有所取舍，且更容易触发安全软件提示，能升级系统的话建议优先升级。
• 只有 XP / Vista 才需要 32 位兼容包，同样受上一条取舍的约束。

这里的机制对应关系可以在源码里看到：src/LunaTranslator/gobject.py 按运行时环境挑选 Python 运行时目录（runtime3.13-64、runtime3.7-64、runtime3.4-32），并维护sys_win10_release_supported、sys_le_win7、sys_le_xp等判定标志，启动时据此决定加载哪套 DLL 与运行时。

解压到普通可写目录

发布包是绿色免安装的，解压即得完整程序。建议放在数据盘或用户目录下的自建文件夹，不要放在C:\Program Files这类受保护路径。

原因是 LunaTranslator 采用便携结构，运行中会持续往自身目录写入配置、缓存和运行时文件；而 Windows 的 UAC 机制默认只给普通进程对受保护目录的只读权限，配置写入失败轻则报错、重则无法启动。这一步没有成本，却覆盖了后面一大类 PermissionError 的来源。

点哪个入口启动

解压后的目录里有三个启动入口，按场景对应：

• LunaTranslator.exe：默认入口，覆盖游戏 HOOK 翻译、屏幕 OCR、剪贴板监听等全部日常场景，普通权限即可。
• LunaTranslator_admin.exe：以管理员权限启动。只有一种情况需要它——游戏以管理员身份运行，普通权限的进程无法向其注入 HOOK。平时不必默认使用。
• LunaTranslator_debug.bat：启动时附带命令提示符窗口，想在窗口里看到日志再判断问题选它。

有一个值得知道的行为细节：程序会以userconfig配置目录的绝对路径做哈希，生成一个互斥量（操作系统中同一时刻只允许一个进程持有的命名锁）。由此带来两个结果——用不同--userconfig参数启动的实例互不干扰，适合维护多套配置；普通模式下若检测到已有同类实例，则会弹出确认框询问是否再次启动。这段逻辑集中在 src/LunaTranslator/main.py 的启动流程里：工作目录切换、命令行解析（--URLProtocol/--Exec/--userconfig）、组件完整性检查、Qt 环境准备、单实例检测，最后加载主界面。

按场景查阅

场景一：HOOK 模式选进程时卡在「正在等待 DLL 注入到游戏中……」

这种情况通常不是注入逻辑本身的问题，而是注入用的组件被安全软件动过了。HOOK 的原理是把 DLL 注入游戏进程再从其中读出显示文字，LunaSubProcess32/64.exe、LunaHost32/64.dll这类「注入型」文件因此容易被误判，被隔离后注入自然完不成。

处理路径：把 Luna 所在目录加入安全软件的排除项（Windows Defender 的路径是「病毒和威胁防护 → 管理设置 → 排除项 → 添加排除项 → 文件夹」），然后重新下载解压一遍，让被清掉的组件回来。发布包由 CI 流水线自动构建，构建环节之外的链路很短，可以放心加信任。

场景二：平时正常，运行几小时后选进程才报 Error/FileNotFoundError

这是安全软件「延迟清理」的典型表现：启动时组件齐全所以一切正常，后台扫描在几个小时后删掉了部分必要文件，等到真正要用那个 DLL 时才暴露。启动阶段的完整性检查（src/LunaTranslator/myutils/config.py中的checkintegrity()会逐一核对运行库、HOOK 组件与子进程）只覆盖启动那一刻，管不到运行期。

处理方式和场景一相同：提前加信任 + 重新下载解压，让组件在整个游戏会话期间保持完整。

场景三：启动即报 Missing embedded Python3 或「找不到重要组件」

这类提示指向同一个根源：内嵌的 Python3 运行时目录或关键 DLL 被安全软件整目录清掉了。处理路径仍是加信任、重新下载解压，之后再启动。

场景四：启动报 Error/PermissionError

这类错误与安全软件无关，多半是程序目录选在了受保护路径下，配置与缓存写不进去。把整个目录移到普通可写位置再启动即可，对应部署一节说的 UAC 权限限制。

场景五：想更新，或者删掉重装

• 自动更新：默认开启。程序会向服务器查询最新版本、下载 zip 并按 sha256 校验，解压到cache/update目录，完全退出后由LunaSubProcess拉起更新器做文件替换——更新从不与正在运行的文件抢占。机制见 src/LunaTranslator/myutils/updater.py。
• 手动更新：下载新包后直接解压覆盖到原目录，旧配置原样保留。
• 删除重装：保留userconfig文件夹。它是全部用户设置的根目录（gobject.py中定义为thisuserconfig），各翻译引擎的自定义脚本副本也放在里面，删掉等于设置清零。

高频问题速查

• 杀毒软件反复报警告怎么办？加信任 + 重新下载解压，一次到位；CI 自动构建的发布包可以放心信任。
• 管理员入口要日常使用吗？不需要，只在游戏本身以管理员运行、需要 HOOK 注入时使用。
• 多个配置档案能并存吗？可以，给不同实例传不同的--userconfig <路径>，互不干扰。
• 自动更新失败了怎么办？界面会提示「自动更新失败，请手动更新」，直接走手动覆盖流程。
• 换机器时设置能带走吗？把userconfig文件夹复制过去即可。

延伸阅读：中文文档主页 docs/zh/README.md 附 ChangeLog，基本用法（HOOK / OCR / 拖拽快捷启动）见 docs/zh/basicuse.md；需要对照行为细节时，启动入口在 src/LunaTranslator/main.py，组件完整性检查在 src/LunaTranslator/myutils/config.py。

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