安卓端初始化失败排查
首次启动卡进度条、QQ 二维码不弹、机器人莫名掉线——这类问题九成出在初始化和运行环境上。本篇按症状给排查顺序，多数不用重装就能解决。相关文档：手机上把QQ号变成AI机器人.md · 大模型接入与插件玩法.md
一、排查总原则：先看日志再说
安卓端的初始化（下载 Ubuntu 容器环境、部署 AstrBot 核心、安装 NapCatQQ）是全自动的，但也因此「看不见发生了什么」。所有排查都从同一个动作开始：点按屏幕任意位置，切到模拟终端日志页，看它到底卡在哪一行——是下载不动、报错退出，还是在慢慢装。对症才好下药。
二、症状对照表
| 症状 | 多半是 | 这样处理 |
|---|---|---|
| 白色进度条长时间不动 | 下载被网络卡住 | 换家用 Wi-Fi 或手机流量；点屏幕切日志页确认卡点 |
| napcat 安装卡住或报错 | 这一步耗时长、对网络敏感 | 关闭 App 重新打开，会从断点继续装 |
| 重启几次仍初始化失败 | 本地环境包损坏 | 系统设置 → 应用管理 → 清除应用数据，重新初始化 |
终端提示 dpkg was interrupted | 系统软件包安装被中断 | 别照终端提示修，清数据重装最干净 |
| 初始化完成但二维码一直不弹 | 协议组件安装失败 | 关闭 App 重开，多数能自愈 |
| 机器人突然不回消息 | 常驻通知被清掉了 | 重开 App 让服务跑起来，以后别清那条通知 |
| 服务在、日志无报错，就是不回 | 同一个号刚在电脑 QQ 登录，协议端被挤下线 | 电脑 QQ 退出该号，重开 App 重新扫码 |
日志里一堆英文看不懂是正常现象——只盯 error、failed、timeout 出现的位置，对照上表处理即可。
三、几条预防措施
- 网络：初始化只用家用 Wi-Fi 或手机流量。校园网、公司内网、公共 Wi-Fi 经常拦大文件下载，是「卡在进度条」的头号原因。
- 初始化期间别锁屏：保持屏幕常亮、盯着日志，出问题第一时间能看到。初始化完成后就没这么多讲究了。
- 通知权限必须给：机器人靠常驻通知保活。当时点了拒绝的，去系统设置 → 应用管理 → 通知，手动打开。
- 别让系统杀后台：部分手机的省电策略会冻结后台应用。把应用加进电池白名单 / 允许后台运行（各品牌入口不同，一般在电池或应用管理设置里），不然息屏久了服务可能被系统掐掉。
四、清数据等于回到出厂
「清除应用数据」会把容器环境、配置全部清空重来，相当于重新初始化一遍：之前填的 API Key、改的密码、装的插件都会没，需要按大模型接入与插件玩法.md重配一遍。QQ 登录态本来就在你的 QQ 账号里，不存在丢失问题。多次重启 App 都无效时，这是项目说明给出的最终手段。
五、还不行怎么办
该项目是开源社区项目，社区 QQ 群是主要的支持入口，框架层面的问题可以查阅 AstrBot 的在线文档。提问时把终端日志页的报错一起发出去，能得到更快的回复。安装流程本身没走通的话，先回到起点对照每一步：手机上把QQ号变成AI机器人.md；也可以到 astrbot.fedq.ren 看首次启动的实拍截图，对照自己卡在哪一屏。