mtkclient-gui 二次开发实战：从读懂 131 行源码到新增自定义刷机功能

mtkclient-gui 二次开发实战：从读懂 131 行源码到新增自定义刷机功能

【免费下载链接】mtkclient-guiGUI tool for unlocking bootloader and bypassing authorization on Mediatek devices (Not maintained anymore)项目地址: https://gitcode.com/gh_mirrors/mt/mtkclient-gui

如果你手里恰好有一台搭载联发科（MediaTek）芯片的老手机，比如红米 9A、红米 Note 9，又恰好想给它的 bootloader（引导加载程序）解锁、然后刷入第三方 ROM，你大概率会撞上这样一面墙：网上现成的刷机工具要么收费、要么只支持特定机型；功能最全的官方命令行工具 mtkclient 参数又多又长，对新手极不友好。而 mtkclient-gui 正是为打破这面墙而生——它在 mtkclient 命令行外面包了一层图形菜单，把"解锁、上锁、绕过 SLA/DAA 授权验证"变成几次回车就能完成的操作。更妙的是，它的项目描述里明确写着Not maintained anymore（已停止维护）。一个停更、但结构极简、底层依赖又成熟的项目，恰恰是二次开发价值最高的练手样本。这篇文章就带你从零开始，完成一次完整的 mtkclient-gui 源码改造。

扩展价值：停更的壳，反而给了你最大的舞台

先说结论：mtkclient-gui 不是一个"大而全"的工具，它是一层很薄的壳。整个项目只有 4 个文件，核心代码mtkclient-gui.py一共 131 行。它的运行机制可以用一句话概括——"菜单选动作 → 用户确认 → subprocess 调用 mtkclient 命令行"。这种薄封装设计，让它在功能上有明显短板，但也正因为薄，改造起来几乎没有任何心智负担。

把"基础能力"和"可扩展能力"摆在一起看，你的发挥空间一目了然：

换句话说，别人看到的是"这个项目没人管了"，而二次开发视角下，你看到的是"功能边界清清楚楚、底层由强大的 mtkclient 兜底、改造点高度集中"——这正是把它练成自己趁手工具的最佳条件。

二次开发第一步：改造前必做的环境准备

动手之前，先把环境跑通。这一步决定了后面所有调试是否顺畅。

1. 获取源码。克隆仓库到本地：

   git clone https://gitcode.com/gh_mirrors/mt/mtkclient-gui

2. 准备 Python 环境。项目要求 Python 3.9，安装依赖：

   pip install -r requirements.txt

   requirements.txt里只有三个包：windows-curses（Windows 下的终端图形库）、curses-menu（字符菜单框架）、requests（网络下载）。依赖之精简，对二次开发是大利好。

3. 注意启动方式。不要直接双击mtkclient-gui.py！程序第一行就读取了环境变量os.environ["RUNTIME_PATH"]，这个变量由start.bat里的set RUNTIME_PATH=runtime\python注入。作者原本的发布思路是：把 Python 3.9 装进项目内的runtime文件夹，连同脚本一起打包成绿色压缩包分发。本地开发时，要么用start.bat启动，要么在命令行先set RUNTIME_PATH=python再运行。

三步定位核心入口，看懂 131 行源码

整份源码只有一个文件，读起来很快。但为了让你在二次开发时能"指哪打哪"，建议按下面三步建立地图：

第一步：找CursesMenu——主菜单本体。文件末尾的几行就是程序的心脏：

menu = CursesMenu("mtkclient-gui", "Choose an action.", show_exit_option=False) menu.append_item(FunctionItem("Unlock bootloader", unlock_bootloader)) menu.append_item(FunctionItem("Lock bootloader", lock_bootloader)) menu.append_item(FunctionItem("Bypass SLA/DAA", bypass_sla_daa)) menu.append_item(FunctionItem("Exit", exit_curses, should_exit=True)) menu.show()

FunctionItem("显示名", 回调函数)就是"一个菜单项 = 一个动作"的注册方式。想加新功能，本质上就是写一个新函数，然后追加一行append_item。

第二步：找subprocess.call——真正干活的命令。每个回调函数内部都是一模一样的套路：确认 → 清屏 → 拼命令 → 执行。比如解锁：

def unlock_bootloader(): exit_curses() choice = input("Do you want to continue? (y/N) ") if choice == "y": clear_terminal() subprocess.call(f"{runtime} mtkclient/mtk da seccfg unlock")

项目实际只有三条命令，对应 mtkclient 的三大能力：

第三步：看启动自检——理解程序的"韧性"设计。在显示主菜单前，程序会做两件事：检查 Windows 是否装了 UsbDk 驱动（没有就自动下载并用msiexec静默安装），检查当前目录是否有mtkclient文件夹（没有就从网络拉取源码包解压）。理解这段逻辑很重要：你后续新增的功能如果依赖 mtkclient 的新命令，只要底层版本跟上，GUI 这边几乎零改动。

实战一：给 mtkclient-gui 新增"分区备份"菜单项

现在进入动手环节。第一个实战案例，给菜单加上devinfo / proinfo / seccfg 分区备份功能。为什么要备份这三个分区？因为它们保存着设备的硬件信息、区域设置和安全性配置，README 也明确建议解锁前先备份。mtkclient 恰好原生支持mtk r命令读取分区，我们只需要把它封装进菜单。

在bypass_sla_daa函数后面加一个新函数，代码风格和原文件保持一致：

def backup_partitions(): exit_curses() choice = input("Backup devinfo/proinfo/seccfg partitions? (y/N) ") if choice == "y": clear_terminal() subprocess.call(f"{runtime} mtkclient/mtk r devinfo,proinfo,seccfg") input("Press Enter to continue")

然后在主菜单注册处追加一行：

menu.append_item(FunctionItem("Backup devinfo/proinfo/seccfg", backup_partitions))

就这么简单——一个新的二次开发功能落地了。整个过程验证了一个判断：mtkclient-gui 的扩展模式是"1 个函数 + 1 行注册"，你真正要研究的其实是 mtkclient 的命令能力，而非 GUI 本身。

实战二：把终端菜单升级为 Web 界面

第二个实战更有想象力：把字符菜单换成 Web 界面。动机很实际——终端菜单必须坐在电脑前操作，而 Web 界面可以在局域网内用手机远程触发，还能优雅地展示执行日志，为将来插件化铺路。

核心思路是"换壳不换核"：把三个动作抽成一份动作表，再用 Flask 暴露成 HTTP 接口：

from flask import Flask, request import subprocess app = Flask(__name__) runtime = "python" ACTIONS = { "unlock": ["mtkclient/mtk", "da", "seccfg", "unlock"], "lock": ["mtkclient/mtk", "da", "seccfg", "lock"], "bypass": ["mtkclient/mtk", "da", "payload"], "backup": ["mtkclient/mtk", "r", "devinfo,proinfo,seccfg"], } @app.post("/run/<name>") def run(name): if name not in ACTIONS: return {"error": "unknown action"}, 404 subprocess.call([runtime, *ACTIONS[name]]) return {"status": "ok"}

再配一个最简单的 HTML 页面，放四个按钮，一个 Web 版 mtkclient 前端就诞生了。这还没有改变任何底层能力，但界面的想象空间被彻底打开：进度条、分区列表、日志回显，全都变成可能。如果你愿意，甚至可以保留原来的字符菜单作为"命令行入口"，与 Web 入口并存——这就是二次开发中典型的"双入口"架构。

mtkclient-gui 源码改造避坑指南

写代码时踩过的坑，提前告诉你：

1.clear_terminal是一个未定义函数（真实 Bug）。全局搜索会发现，clear_terminal()被调用了 4 次，但整个项目里没有任何地方定义它。这意味着只要程序走到退出或执行动作的流程，就会抛出NameError。二次开发第一件事，建议补上这个函数：

def clear_terminal(): os.system("cls" if os.name == "nt" else "clear")

2. 直接运行脚本会报KeyError: 'RUNTIME_PATH'。记得通过start.bat启动，或者给代码加一个兜底：runtime = os.environ.get("RUNTIME_PATH", sys.executable)，顺手就解决了一个易用性问题。

3. 依赖的跨平台陷阱。requirements.txt里的windows-curses只能在 Windows 上用。如果你想做跨平台改造，Linux / macOS 应该依赖系统自带的curses模块，需要按平台拆分依赖清单。

4. 自动下载机制在无网环境会卡死。程序首次运行会从网络拉取 mtkclient，一旦断网或在内网环境，会一直卡在下载环节。二次开发时建议把mtkclient目录随包发布，并把下载逻辑包进try/except，失败时给出明确提示而不是无限重试。

5. subprocess 的工作目录假设。命令mtkclient/mtk ...隐含了"当前目录下必须有 mtkclient 文件夹"的假设。封装更稳妥的方式是用绝对路径拼接，避免从别的目录启动时踩空。

6. 设备兼容性不是玄学，是清单。README 里明确列了可用机型（红米 Note 9、红米 9A/9C、红米 Note 8 Pro 等）和不支持的机型（红米 6、红米 6A）。新增功能时，尽量在 UI 层加入机型提示，避免用户盲目操作损坏设备。

二次开发最佳实践：5 条能直接用的经验

1. 永远保持薄封装。mtkclient 是负责干活的引擎，你的 GUI 只负责交互。别把刷机逻辑塞进界面代码，否则后面寸步难行。
2. 动作函数化。每一个功能都写成无副作用、可独立调用的函数，这样无论接终端菜单还是 Web 界面，都能直接复用——案例二已经示范了这一点。
3. 配置外置。把RUNTIME_PATH、mtkclient 路径、下载地址这类易变项抽成常量或配置文件，别硬编码在逻辑里。
4. 补日志。原版把 subprocess 的输出直接丢到终端，改造时建议重定向到日志文件，刷机失败时能回溯原因。
5. 同步维护文档。尤其是 README 里的设备兼容性清单——每次实测后把机型、结果更新进去，这是对社区最直接、最有价值的贡献。

参与方式与下一步：让停更项目重新活起来

二次开发的终点，从来不是"改完自己用"，而是让代码回到社区。你可以按这个路径参与进来：

• 先跑通，再提 PR。克隆仓库、复现环境、修掉clear_terminal这个 bug，就是一份合格的首次贡献。
• 用真实设备报告兼容性。如果你手头有 README 未列出的机型，解锁后把结果反馈到 issue 区，这条信息对后来者价值巨大。
• 长期维护者缺位时，考虑接管。原项目停更不等于死亡，很多经典工具都是被社区 fork 后重新焕发生机的。你可以把上面两个实战案例整理成补丁提交，如果维护者长期没有响应，就大胆 fork 并建立自己的版本。

行动号召很简单：今天就把仓库克隆下来，跑一次原版，然后亲手补上那个clear_terminal函数。当你看到自己改的第一行代码让"Exit"菜单不再崩溃时，一次完整的 mtkclient-gui 二次开发旅程，就从这里正式开始了。

【免费下载链接】mtkclient-guiGUI tool for unlocking bootloader and bypassing authorization on Mediatek devices (Not maintained anymore)项目地址: https://gitcode.com/gh_mirrors/mt/mtkclient-gui