打包 APK 失败了怎么办

打包失败的常见表现

打包过程中出问题，WebCat 一般会有几种表现：

• 进度条跑到某个百分比卡住不动，最后超时
• 打包完了找不到生成的 APK 文件
• 提示「打包失败，请重试」但没有具体原因
• 生成的 APK 安装后打不开或闪退

按概率从高到低排查

① manifest.json 格式有错误

打包失败最常见的原因——manifest.json 里有 JSON 语法错误：

• 大括号没配对
• 逗号漏掉或多写了
• 字符串引号用了中文引号
• 字段值格式不对（比如版本号写成了中文）

解法：

1. 打开 manifest.json
2. 点格式化（5.21 新增的 JSON 编辑支持）——格式化报错就是 JSON 格式有问题
3. 格式化成功后肉眼扫一遍大括号是否成对闭合
4. 参考 WebCat 新建工程时的默认 manifest.json 值，对比你改了哪些

② 工程文件太大或太多

几十上百 MB 的大型项目、或文件数量特别多（比如带 node_modules），打包过程可能内存不够或超时。

解法：

1. 先导出 ZIP，看看最终有多大——如果超过 50MB，考虑精简一下（node_modules 等不需要打包的东西删掉）
2. 关掉 WebCat 里其他分屏、大文件编辑窗口，释放内存
3. 重启一次 WebCat 再试打包

③ 图标文件格式不支持

换图标时用了 WebCat 不认识的格式，比如：

• 用了 BMP / TIFF 等非常规格式
• PNG 里嵌了 CMYK 色彩空间（安卓只认 RGB）
• 图标太大（超过 1024×1024）

解法：换成标准 RGB 色彩空间、透明背景的 PNG，尺寸控制在 192×192 以内。

④ 存储权限不够

WebCat 需要存储权限才能把 APK 写入目标目录。如果之前拒绝过存储权限，打包完可能会提示找不到文件——实际上是没权限写进去。

解法：

1. 设置 → 应用 → WebCat → 权限 → 打开存储权限
2. 清一下 WebCat 的应用缓存（设置 → 应用 → WebCat → 存储 → 清除缓存）
3. 重新启动 WebCat 再试

⑤ 打包后的 APK 安装闪退

如果打包成功了、APK 也能装上，但一打开就闪退：

1. 看是不是 PHP 项目打包（PHP 不会进 APK，打包后只有静态页面）——如果项目依赖 PHP 后端逻辑，APK 里没有这些逻辑，页面可能白屏或报错
2. manifest.json 里的权限声明和实际功能不符（没声明但用到了的权限）
3. 安卓版本兼容性问题——在低于 5.0 的系统上打开打包的 APK 可能闪退

打包成功的标准

打包完后检查三件事：

1. 工程目录下的 build/ 或 output/ 子目录里有新生成的 APK 文件
2. 文件大小合理（至少几 MB 以上，太小说明打包有问题）
3. 安装到手机上能正常打开、首页能加载出来

三条都满足才算真的打包成功。