QCL-CE 使用文档
安装、启动器用法、以及遇到问题时的排查方法。当前对应版本 v2.0.6。
安装
装之前一定要做两件事
- 卸载官方版 QCL。QCL-CE 和官方包签名不同，不卸载会装不上。
- 清除应用数据（如果之前装过 QCL-CE）。旧设置文件会自我延续，可能导致一些难以理解的现象。
直接下载： GitHub 直链 ｜ 国内镜像（gh-proxy）
gh-proxy 只是把同一条 GitHub 直链转发一遍，下载到的文件完全一样。 也可以到 Releases 页面查看全部发布：
| 文件 | 用途 |
|---|---|
QCL-CE-v2.0.6-arm64.apk | 给手机用。绝大多数现代手机都是这个。 |
第一次启动
第一次打开会解压内置运行时，约 452 MB，需要几分钟。这一步是离线解压 —— 断网也能装完。
如果卡在这一步不动，先确认手机剩余空间够（建议留 2 GB 以上）。
确认手机架构
本项目只提供 arm64 包。确认方法：
- 设置 → 关于手机 → 处理器，写着
arm64-v8a或aarch64就是。 - 2017 年之后的手机基本都是 arm64。
- 如果是
x86_64（模拟器常见），需要另外构建 x86_64 包。
使用
启动游戏
- 主页显示当前要启动的版本和已装版本数（都是实时读出来的）。
- 点启动游戏即可。
- 启动日志会实时显示在弹窗里 —— 出问题就看那里。
装版本
- 左侧「≡ 菜单」→ 下载，或直接进版本列表。
- 选版本安装。下载会走国内镜像加速。
装模组
在下载 → 模组里搜索并安装。安装时 QCL-CE 会自动把前置也一起装上：
- 只装必需的前置，可选/不兼容/内置的会跳过。
- 会按你当前的游戏版本挑合适的前置版本。
- 已经装过的会自动跳过，不会重复下载。
- 整条依赖链都会拉下来 —— A 需要 B、B 又需要 C 时，C 也会被装上。
装整合包
「安装包」里选整合包文件即可。目前支持：
| 格式 | 说明 |
|---|---|
| MultiMC / Prism | ✓ 完整支持 |
Modrinth（.mrpack） | ✓ 支持，限 Fabric 加载器 |
| CurseForge | ✓ 支持，限 Fabric 加载器 |
| HMCL / MCBBS | ✗ 还没接通，先手动解压把 mods/ 拷进游戏目录 |
装整合包时会自动下载游戏本体，并逐条列出下载任务，能看到装到哪一步。
深色模式
内置插件页 → 界面 → 深浅色模式，三个选项：跟随系统 / 始终浅色 / 始终深色。
不用去改手机系统设置，在应用里就能切，方便试。
菜单排版
点左侧「≡ 菜单」打开功能菜单，右上角有排版按钮：
- 勾选要显示哪些入口
- 用 ↑↓ 调顺序
- 保存 / 恢复默认
界面排版自定义
长按任意页面就能进编辑模式：
- 单击一个控件 = 显示 / 隐藏
- 长按控件再拖动 = 在同层里换位置
- 底部浮动条：保存 / 取消 / 恢复默认
支持 13 个页面：主页、下载、版本列表、设置、账号、游戏管理、大厅、实验室、备份、启动诊断、资源下载、插件、联机。
想把排版分享给别人：插件页 → 界面 → 排版导入 / 导出 → 复制到剪贴板 → 发群里。别人复制后点「从剪贴板导入」即可。
插件
左侧「≡ 菜单」→ 插件。顶部有搜索框，可以按名字搜。
插件分几类：下载、界面、资源、模组、账号、联机、系统、安全与备份等。
插件市场
插件页 → 资源 → 插件市场，可以直接在应用内安装资源型插件。
- 市场里的插件是资源型的（控键布局 / 界面排版）—— 启动器没有插件运行时，所以不加载代码。
- 每个包都会校验 sha256，对不上就拒装。
- 安装完如果是排版类，退出再进主页生效；控键类到「设置 → 控键布局」里选。
- 市场网页：weeb123321.github.io/QCL-Plugins
排错
出问题先做这个
「我的 → 启动诊断」→ 分享给作者。
这一页会生成一份完整报告：设备信息、上次启动断点、本次启动路标、系统记录的进程退出原因、以及输入链路自检。把这段发出来，绝大多数问题能直接定位。
一打开就闪退
按顺序排查：
- 先卸载官方版 QCL。两个包签名不同却曾共用同一个数据目录，会导致读写失败。
- 清除应用数据再打开。
- 看日志：
/sdcard/QCL-CE/crash.log（1.9.3 起的新路径）。 - 把「启动诊断」的报告发出来。
游戏里点不了
表现是画面正常、游戏也能进去，但点什么都没反应。这类问题的根因在输入层，从界面看不出来。
去「我的 → 启动诊断」，报告里有一段 ----- 输入链路自检 -----，它会列出：
- 进程实际加载了哪些输入相关库（读
/proc/self/maps） - 磁盘上有哪些输入库
- 控制布局目录的内容
判读方法写在报告末尾。把这段发出来即可定位。
插件市场连不上 / 网页打不开
先看浏览器报什么错 —— 不同错误码指向完全不同的原因：
| 浏览器报错 | 真正的原因 | 怎么办 |
|---|---|---|
ERR_PROXY_CONNECTION_FAILED |
系统代理坏了（最常见） | 见下面的「关掉系统代理」 |
ERR_CONNECTION_TIMED_OUT / 一直转圈 |
域名被拦 / 网络太慢 | App 会自动换镜像重试，也可以挂代理 |
| 浏览器能打开，但 App 里不行 | App 侧的问题 | 去「我的 → 启动诊断」把报告发出来 |
- Windows：设置 → 网络和 Internet → 代理 → 关掉「使用代理服务器」
- 安卓：设置 → WLAN → 长按当前网络 → 修改网络 → 代理 → 无
常见情况：某个代理 / VPN 客户端已经关了， 但系统代理设置还留着 —— 于是浏览器和 App 都往一个死掉的端口发请求。
2.0.5 起，App 里读市场索引会先直连、失败再走系统代理， 所以代理坏了也能读到 ✓ 但修好代理更彻底。
下载失败
- 默认会走国内镜像。如果某个镜像挂了，会自动回退到官方源。
- 可以在插件页的「下载镜像自定义」里换一个镜像。
- 如果一直失败，检查网络是否有限制。
装不上 / 提示签名冲突
- 签名冲突：官方版没卸干净。到「设置 → 应用」卸载 QCL 后再装。
- 版本降级：装了更高 versionCode 的包。卸载后重装即可。
- 解析包出错：文件没下载完整，重新下载。
FAQ
能和官方版同时装吗？
能。QCL-CE 的包名是 com.qcl.launcher.ce，和官方版不同，可以共存。
装 QCL-CE 会不会影响官方版的存档？
不会动官方版的存档。但两者曾经共用同一个外部目录，所以建议先把官方版的存档备份一份再折腾。
为什么只提供 arm64？
因为绝大多数手机是 arm64。内置运行时会按架构分包，只带一份能让安装包小约 100 MB。
支持正版登录吗？
支持微软账号登录。离线账号也能用，但只能进单人游戏或离线服务器。
怎么反馈问题？
到 GitHub Issues 提，或者带上「启动诊断」的报告。
许可
QCL-CE 以 GPL-3.0 发布。它基于 QCL（HMCL-PE → FCL → PojavLauncher 血统）。
第三方组件与许可清单见仓库里的 THIRD_PARTY_NOTICES.md。