Bootstrap 安装失败——首次启动卡住最常见问题

表现

首次启动卡在「正在安装 Bootstrap」进度条不动、或报错退出，打开终端后基础命令找不到。

常见原因和处理

1. 安装过程被切后台或进程被杀

Android 系统会杀掉长期在后台运行的应用。ZeroTermux 首次启动下载 Bootstrap 需要 3–5 分钟，如果这期间切到别的 App 或手机锁屏，进程可能被系统回收。

处理：

• 重新打开 ZeroTermux，保持在前台直到安装完成
• 锁屏时不要太久，亮屏保持 ZeroTermux 在前台
• 给 ZeroTermux 开电池优化豁免：系统设置 → 电池 → ZeroTermux → 无限制

2. 设备存储空间不足

Bootstrap 大约需要 300–500 MB。如果设备存储剩余不多，安装会失败。

处理：

• 卸载不常用 App
• 清理缓存（系统设置里清其他 App 的缓存）
• 删除大文件

3. 旧 Termux / ZeroTermux 残留

没卸载干净直接覆盖安装，两个应用的文件互相冲突。

处理：

1. 系统设置 → 应用管理
2. 搜 Termux 和 ZeroTermux，全部卸载
3. 确认没有残留后再装 ZeroTermux

4. 非 Android 主用户

工作资料夹（Work Profile）、第二用户环境的存储权限受限，Bootstrap 无法正常写入。

处理：切换到 Android 主用户环境再装 ZeroTermux。

5. 网络问题

Bootstrap 下载走的是默认源（海外），国内用户如果没切镜像源可能超时。

处理：

• 确认 Wi-Fi/数据网络正常
• 如果能进终端（部分 Bootstrap 功能已装好），手动 pkg update 看报什么错
• 等首次启动完成后进「切换源」切国内镜像

还没好

截图错误信息到 ZeroTermux 社群（Diving Group）或项目 Issues，附上设备型号、Android 版本、ZeroTermux 版本。