开源游戏助手Akari：基于LCU API的架构解析与实战搭建

1. 为什么我要折腾一个游戏助手工具打英雄联盟有些年头了从最早的盒子时代到后来的各种助手工具我基本都试过一圈。大部分工具要么广告满天飞要么后台偷偷跑一堆进程要么用着用着就停止维护了。去年开始我注意到一个叫 Akari 助手的开源项目作者把整套东西放在 GitHub 上基于 LCU API 做了一套功能相当完整的对局辅助工具。用了一段时间之后我发现这东西确实值得好好聊一聊不只是因为它免费更因为它的技术选型和架构思路对于想自己动手做工具的人来说很有参考价值。Akari 助手的核心定位是一个本地运行的游戏效率工具它通过 LCU APILeague Client Update API与游戏客户端进行通信实现自动接受对局、战绩查询、符文配置、英雄选择辅助等一系列功能。整个项目基于 Node.js 运行环境使用 Yarn 作为包管理器代码完全开源。这意味着你不需要担心什么后门或者数据泄露的问题所有逻辑都摆在明面上懂代码的人可以自己审计。这篇文章适合几类人看一是想找一个干净好用的游戏辅助工具但不想装那些商业软件的玩家二是对 LCU API 感兴趣、想自己写点小工具的开发者三是想学习一个完整开源项目是怎么组织代码和发布流程的技术爱好者。我会从架构设计、环境搭建、核心功能实现、常见问题排查几个维度把 Akari 助手拆开来讲清楚尽量让不管什么基础的人都能看懂并且能自己跑起来。2. Akari 助手的整体架构与设计思路2.1 为什么选择 LCU API 作为核心通信层LCU API 是游戏客户端在本地启动后暴露出来的一套 RESTful 接口默认监听在本地回环地址上。它本质上就是客户端自己跟自己通信用的内部接口Akari 助手做的事情就是找到这个接口的端口和认证信息然后以合法的身份去调用它。这个设计的好处非常明显不需要注入游戏进程不需要修改任何游戏文件也不需要 hook 系统调用从技术层面来说就是一个普通的 HTTP 客户端在跟本地服务通信。具体来说客户端启动后会在锁文件里写入端口号和认证令牌这个锁文件的位置在 Windows 上通常是游戏安装目录下的lockfile。Akari 助手启动时会去读取这个文件解析出端口和 token然后用 Basic Auth 的方式构造请求头。整个过程不涉及任何内存读写或者进程注入这也是为什么它相对安全的原因。注意LCU API 的端口每次启动客户端都会变化所以不能硬编码端口号必须动态读取 lockfile。2.2 Node.js 与 Yarn 的技术选型考量项目选择 Node.js 作为运行时环境这个决策我觉得挺务实的。首先 LCU API 就是 HTTP 接口Node.js 处理异步 HTTP 请求天然顺手axios或者node-fetch几行代码就能搞定。其次 Electron 桌面应用生态跟 Node.js 是无缝衔接的Akari 助手本身就是一个 Electron 应用主进程和渲染进程之间的通信、窗口管理、系统托盘这些功能用 Node.js 生态来做效率很高。Yarn 作为包管理器的选择也值得说一下。相比 npmYarn 在依赖锁定和安装速度上有优势尤其是这个项目依赖比较多的时候Yarn 的yarn.lock能确保不同机器上安装的依赖版本完全一致。对于开源项目来说这一点很重要否则用户 A 能跑起来用户 B 跑不起来issue 区就会炸锅。2.3 项目目录结构与模块划分Akari 助手的代码组织比较清晰大致分为几个层次。最底层是 LCU 连接模块负责发现客户端、维护连接状态、封装请求方法。往上是业务逻辑层包括自动接受对局、战绩查询、符文管理这些具体功能。再往上是 UI 层用 Vue 或者 React 写的界面具体版本不同可能技术栈有调整。最后是主进程入口负责生命周期管理和模块调度。这种分层的好处是每个模块职责单一LCU 连接层不需要关心业务逻辑业务层不需要关心界面怎么渲染。如果你想自己加功能只需要在业务层新增一个模块然后在 UI 层加个入口就行不用动底层代码。3. 从零搭建运行环境的完整实操3.1 Node.js 安装与版本选择Akari 助手对 Node.js 版本有要求建议使用 18 LTS 或更高版本。我实测过 16.x 也能跑但偶尔会有兼容性问题所以直接上 18 或者 20 最省心。安装方式看你习惯官网下载安装包双击下一步也行用包管理器也行。Windows 用户直接去 Node.js 官网下载 LTS 版本的.msi安装包双击安装一路下一步安装程序会自动把node和npm加到系统 PATH 里。安装完成后打开命令行输入node -v和npm -v确认版本号能正常输出。macOS 用户如果用 Homebrew 的话一条命令搞定brew install node18Linux 用户建议用 nvm 来管理版本避免跟系统自带的 Node.js 冲突curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 18 nvm use 18提示如果你之前装过其他版本的 Node.js建议先卸载干净再装否则可能出现 PATH 冲突导致命令行调用的还是旧版本。3.2 Yarn 的安装与配置Node.js 装好之后 npm 就有了但项目用的是 Yarn所以还得单独装。最推荐的方式是通过 corepack 来启用Node.js 16.10 以后都内置了 corepackcorepack enable corepack prepare yarnstable --activate这样装出来的 Yarn 版本跟项目要求的能对上。如果你习惯用 npm 全局安装也行npm install -g yarn装完之后yarn -v确认一下版本。有时候国内网络环境下载依赖会比较慢可以配置一下镜像源yarn config set registry https://registry.npmmirror.com这个镜像源是国内的速度会快很多而且同步频率也高基本不会出现包版本落后的问题。3.3 克隆项目与安装依赖环境准备好之后就可以拉代码了。打开命令行找一个你放项目的目录git clone https://github.com/your-repo/akari-assistant.git cd akari-assistant然后安装依赖yarn install这一步会下载所有依赖包第一次跑可能需要几分钟取决于网络速度。如果中途卡住或者报错大概率是网络问题可以试试清一下缓存重来yarn cache clean yarn install安装完成后项目目录下会多出一个node_modules文件夹里面就是所有依赖。这时候可以试着启动开发模式看看能不能跑起来yarn dev如果一切正常应该会弹出一个应用窗口说明环境搭建成功了。3.4 打包与生产环境部署开发模式跑通之后如果你想打包成可执行文件分发给别人用可以用项目自带的打包脚本yarn build打包完成后在dist或者release目录下会生成安装包。Windows 下通常是.exemacOS 下是.dmg。打包过程可能会比较慢因为要压缩和签名耐心等就行。注意打包之前确保你的代码没有引用开发环境才有的路径或者变量否则打出来的包运行时会报错。4. 核心功能模块的深度拆解4.1 自动接受对局是怎么实现的自动接受对局这个功能看起来简单但实现起来有几个细节要注意。核心逻辑是轮询 LCU API 的/lol-matchmaking/v1/ready-check接口当返回的状态是InProgress时就调用/lol-matchmaking/v1/ready-check/accept来接受对局。轮询频率是个关键参数。太快了浪费资源太慢了可能错过接受时机。我实测下来 1 到 2 秒的间隔比较合适既能及时响应又不会给客户端造成负担。Akari 助手内部应该也是类似的策略具体实现可以在源码里找到对应的定时器配置。还有一个细节是错误处理。如果接受请求失败了比如网络抖动或者客户端状态变了需要有重试机制。简单的做法是捕获异常后等一秒再试一次连续失败三次就放弃并通知用户。4.2 战绩查询的数据来源与展示逻辑战绩查询走的是 LCU API 的/lol-summoner/v1/summoners和/lol-match-history/v1/products/lol/current-summoner/matches这两个接口。前者获取召唤师基本信息后者拉取最近的对局记录。数据拿到之后需要做一层转换因为 LCU 返回的原始数据字段名很冗长直接展示给用户看体验很差。Akari 助手在业务层做了一层映射把gameDuration转成分钟、把participants数组里当前玩家的数据提取出来、把 KDA 算好然后再交给 UI 层渲染。这里有个坑是分页。LCU 的战绩接口默认只返回最近 20 局如果你想看更多需要传begIndex和endIndex参数。但也不是无限翻的客户端本身对历史记录有存储上限太久远的对局查不到。4.3 符文配置的读写与同步符文功能涉及两个方向读取当前符文页和写入新符文。读取走/lol-perks/v1/currentpage写入走/lol-perks/v1/pages。写入的时候需要构造完整的符文页对象包括主系、副系、碎片、名称这些字段。比较麻烦的是符文 ID 的映射。游戏里每个符文都有一个数字 ID但用户看到的是名字和图标。Akari 助手需要维护一份 ID 到名称的映射表这份表通常会随着游戏版本更新而变化。开源项目的好处就在这里版本更新后如果有人发现映射不对提个 PR 就能修不用等官方发版。提示写入符文页之前建议先检查当前符文页数量是否已达上限否则请求会失败。客户端的符文页上限通常是 20 个。4.4 英雄选择阶段的辅助功能英雄选择阶段是 LCU API 能做的事情最多的地方。你可以获取当前对局的选人状态、队友预选了什么英雄、对面 ban 了什么甚至可以自动设置召唤师技能和符文。Akari 助手在这个阶段做的事情主要是信息聚合把队友的预选英雄和胜率展示出来把对面的阵容倾向分析一下帮你在选人时做决策。这些功能的数据来源是/lol-champ-select/v1/session接口它返回的 JSON 结构相当复杂需要仔细解析。我个人的经验是这个接口的字段在不同版本之间偶尔会有微调所以代码里最好做一层容错某个字段取不到的时候不要直接崩溃给个默认值继续跑。5. 常见问题排查与避坑指南5.1 连接不上客户端怎么办这是最常见的问题表现是应用启动了但一直显示未连接。排查思路按顺序来先确认游戏客户端是不是已经登录到主界面了LCU API 只有在客户端完全启动后才可用然后检查 lockfile 是否存在路径通常是C:\Riot Games\League of Legends\lockfile如果你装在别的盘符要对应调整再然后确认应用有没有读取 lockfile 的权限某些安全软件会拦截文件读取操作。如果以上都没问题可以手动测试一下 LCU 接口是否可达。从 lockfile 里读出端口号和 token然后用 curl 发个请求curl -k -u riot:你的token https://127.0.0.1:端口号/lol-summoner/v1/current-summoner能返回 JSON 就说明接口是通的问题出在应用层返回 403 就是 token 不对连接被拒绝就是端口不对或者客户端没启动。5.2 依赖安装失败的各种情况yarn install报错的原因五花八门我整理了几种常见的错误现象可能原因解决方法网络超时默认源访问慢切换镜像源node-gyp 编译失败缺少构建工具安装 Python 和 VS Build Tools版本冲突lockfile 与 package.json 不一致删除 yarn.lock 重新 install权限错误没有写入权限用管理员权限运行或修改目录权限缓存损坏上次安装中断yarn cache clean 后重试node-gyp 编译失败在 Windows 上特别常见因为有些依赖包含原生模块需要编译。解决办法是装一套构建工具npm install -g windows-build-tools或者手动安装 Visual Studio Build Tools 和 Python 3.x然后在 npm 配置里指定 Python 路径。5.3 功能时灵时不灵的排查思路有时候自动接受对局能用有时候不能用这种间歇性问题最难查。我的经验是先看日志Akari 助手在控制台会输出请求日志看看失败的时候返回了什么状态码。如果是 404 说明接口路径变了需要更新代码如果是 500 说明客户端内部出错了等一会儿再试如果是超时说明网络或者客户端卡了。另一个常见原因是客户端版本更新后 LCU API 有变动。这种情况只能等项目维护者更新适配或者你自己去看客户端的开发者文档找新接口。开源项目的好处就是你可以自己动手改不用等官方发版。5.4 性能优化与资源占用控制Akari 助手本身资源占用不高但如果轮询频率设置不合理或者日志输出太多也会导致 CPU 和内存占用上升。我建议把不必要的轮询关掉比如你不需要自动接受对局的时候就别开那个功能。日志级别也可以调开发的时候用 debug日常使用用 info 或者 warn 就够了。Electron 应用本身内存占用会比原生应用高一些这是技术栈决定的没办法完全避免。但通过合理的窗口管理和进程回收可以把占用控制在一个可接受的范围内。Akari 助手在这方面做得还行我开着它打一晚上游戏也没见内存暴涨。6. 自己动手扩展功能的思路6.1 如何新增一个自定义功能模块如果你想在 Akari 助手基础上加自己的功能步骤其实不复杂。先在业务层新建一个模块文件导出一个类或者函数里面实现你的逻辑。然后在主进程入口里注册这个模块让它随应用启动。最后在 UI 层加一个入口或者配置项让用户能开关这个功能。举个例子假设你想加一个“自动发送开局问候”的功能。你需要在业务层监听游戏进入加载阶段的事件然后调用 LCU 的聊天接口发送消息。聊天接口是/lol-chat/v1/conversations/{id}/messages构造一个 POST 请求就行。代码量不大核心是找到正确的触发时机。6.2 调试技巧与日志分析开发过程中最常用的调试手段就是看日志。Akari 助手在控制台输出的日志包含了请求 URL、请求方法、响应状态码和响应体摘要。如果你在开发新功能可以在关键位置加console.log把中间变量打出来。另外 Chrome DevTools 也可以用来调试 Electron 应用。在开发模式下按CtrlShiftI可以打开开发者工具跟调试网页一样调试 UI 层。主进程的调试稍微麻烦一点需要在启动命令里加--inspect参数然后用 Chrome 的chrome://inspect页面连接。6.3 参与开源贡献的注意事项如果你想给 Akari 助手提 PR有几个事情要注意。先看项目的 CONTRIBUTING.md 文件里面通常写了代码风格要求和提交规范。然后确保你的改动有对应的 issue 或者讨论不要直接提一个大 PR 上去维护者可能不认可你的方向。代码风格方面项目用了 ESLint 和 Prettier 的话提交前跑一下yarn lint确保没有格式问题。提交信息要写清楚改了什么、为什么改不要就写一个“fix bug”就完事了。提示第一次贡献建议从文档修正或者小 bug 修复开始熟悉一下项目的协作流程再做大功能。7. 我对这类工具的一些个人看法用 Akari 助手这段时间最大的感受是开源工具在透明度和可控性上确实有优势。你知道它做了什么、没做什么不用担心它在后台偷偷收集你的数据或者给你推广告。当然代价就是遇到问题得自己排查没有客服可以找。从技术角度来说LCU API 这套东西给了开发者很大的发挥空间但官方并没有把它当作公开接口来维护所以版本更新导致接口变动是常态。做这类工具的人需要有一定的逆向能力和快速适配的觉悟。Akari 助手的维护者在这方面响应还算及时社区也比较活跃有问题提 issue 基本都能得到回复。如果你只是想找个工具用直接下载 release 包就行不用折腾源码。如果你想学点东西或者有定制需求那从源码跑起来自己改是最合适的路径。Node.js 和 Yarn 的环境搭建门槛不高照着步骤走基本都能跑通。真正花时间的是理解 LCU API 的各种接口和数据结构这部分只能靠看文档和实际调试来积累经验。最后分享一个小技巧如果你在开发过程中经常需要重启应用来测试可以配一个 nodemon 或者类似的工具来监听文件变化自动重启能省不少时间。具体配置在项目的开发文档里应该有提到没有的话自己加一个也不复杂。