Troubleshooting

常见问题

先保留失败阶段、错误摘要、开发机平台、包类型、工具版本和入口显示的本机日志位置。下载字节数、速度及已用时间属于进度；服务器未提供总大小时可能没有百分比。

现象	原因与处理	验证恢复
DNS、连接、代理或证书失败	按实际网络错误检查 DNS、代理、连接和证书；不要跳过 TLS 或摘要校验	重启同一 setup，观察下载和摘要阶段成功
HTTP 404	版本、资产地址错误，或资源不可用；回到正式 Release 核对平台及资产名称	正确地址可下载，入口校验通过
SHA-256 不匹配	文件损坏或不是可信发布资产；重新取得可信包	大小、摘要与归档检查全部通过再安装
找不到 webman-aot	新终端尚未读取 PATH，或安装未完成	重新打开终端，对照安装位置检查入口，再运行 version
build requires a Webman project root	当前目录错误或前置文件不全	进入后端根目录，确认 Composer 依赖和根文件，再构建
缺少工具链或空间不足	轻量包组件尚未准备，或磁盘无法完成构建	查看 doctor --check；有网络/空间后运行 doctor 或显式 doctor --repair
stray code 指向第三方条件声明	依赖组合超出已锁定适配；已有修复记录不保证其他组合通过	核对实际依赖及适配输入，完成对应回归；不要凭工具版本号认定问题已解决
依赖版本/源码摘要不匹配	输入超出锁定适配，不能静默忽略	恢复已知输入或完成适配后重新构建，随后接口回归
构建提示源树变化	构建期间真实源码或依赖变化；项目构建忽略任意层级精确名称 .DS_Store	检查列出的变化路径，待编辑或依赖安装写入结束后再重试
服务启动但验证码失败	字体、模板等运行资源缺失或配置错误	完整部署目录，检查资源及启动日志，重测验证码
普通 PHP 8.4 权限拒绝变业务 500	SaiAdmin 隐式可空参数弃用可触发项目异常处理	按SaiAdmin 迁移说明修复，保留 E_ALL 重测四条业务路径
verify 通过但目标接口失败	本机包校验不覆盖数据库、服务启动和业务配置	按Linux 部署在目标环境重测

仍无法解决时向 Issues 提供上述摘要和脱敏日志。日志不会自动上传；提交前检查账号、密钥及个人路径。