1. 为什么我要折腾一个游戏助手工具
打英雄联盟有些年头了，从最早的盒子时代到后来的各种助手工具，我基本都试过一圈。大部分工具要么广告满天飞，要么后台偷偷跑一堆进程，要么用着用着就停止维护了。去年开始我注意到一个叫 Akari 助手的开源项目，作者把整套东西放在 GitHub 上，基于 LCU API 做了一套功能相当完整的对局辅助工具。用了一段时间之后我发现这东西确实值得好好聊一聊，不只是因为它免费，更因为它的技术选型和架构思路对于想自己动手做工具的人来说很有参考价值。
Akari 助手的核心定位是一个本地运行的游戏效率工具，它通过 LCU API（League 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 作为包管理器的选择也值得说一下。相比 npm，Yarn 在依赖锁定和安装速度上有优势，尤其是这个项目依赖比较多的时候，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 node@18Linux 用户建议用 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 以后都内置了 corepack：
corepack enable corepack prepare yarn@stable --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 下通常是.exe，macOS 下是.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 应用。在开发模式下按Ctrl+Shift+I可以打开开发者工具，跟调试网页一样调试 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 或者类似的工具来监听文件变化自动重启，能省不少时间。具体配置在项目的开发文档里应该有提到，没有的话自己加一个也不复杂。
