82. 错误码与诊断 · 玄武屏使用手册

玄武屏的所有错误都有明确编码 + 诊断指南。本节是错误码大全，按类别分组。

错误码格式

XWP-XYY
   │ │
   │ └─ 编号（01-99）
   └─── 类别（X = 1-9）

类别	范围	含义
1xx	100-199	文件 / 加载错误
2xx	200-299	渲染错误
3xx	300-399	元素错误
4xx	400-499	网络错误
5xx	500-599	服务端错误
6xx	600-699	权限 / 认证
7xx	700-799	AI 错误
8xx	800-899	协作错误
9xx	900-999	配额 / 计费

1xx 文件错误

XWP-101 文件无法打开

可能原因：

文件损坏（zip 不完整）
版本不兼容（太新）
缺失必要字段

排查：

用 xwp-cli validate 检查
"文件 → 历史版本"恢复
联系客服

XWP-102 资源丢失

某个 assets/ 文件缺失：

检查 .xwp 是否被压缩工具破坏
重新下载文件
用 xwp-cli inspect 列出资源清单

XWP-103 版本过旧

.xwp 版本低于客户端最低支持：

在最新客户端打开 → 自动迁移
极旧文件需联系客服

XWP-104 文件超过大小限制

200MB → 拒绝加载：

用 xwp-cli optimize 压缩
拆分成多个 .xwp
大视频改为外链

2xx 渲染错误

XWP-201 画布初始化失败

可能原因：

浏览器不支持 WebGL（极老浏览器）
显卡驱动问题
内存不足

排查：

升级浏览器（Chrome 95+）
重启浏览器 / 系统
关闭其他大型 Web 应用

XWP-202 字体加载失败

某字体未能加载：

字体服务超时（网络慢）
字体文件被防火墙阻断
自上传字体已失效

降级：自动用相似系统字体替换。

XWP-203 LaTeX 渲染失败

公式语法错误：

检查 LaTeX 语法
反引号 / 花括号不匹配
不支持的命令

详见「16. 数学公式」。

3xx 元素错误

XWP-301 GGB 加载失败

最常见错误：

网络问题（无法访问 GeoGebra 域名）
workId 无效
没有访问权限

排查：

检查网络
验证 workId 在平台搜得到
确认账号已购买

XWP-302 HTML 组件沙盒拒绝

HTML 组件违反沙盒规则：

调用了被禁的 API（fetch / WebSocket）
访问父页面
危险操作（eval）

修复：组件作者需修改代码符合沙盒。

XWP-303 视频解码失败

编码不支持（H.265 在某些设备）
文件损坏
浏览器不支持

降级：自动选 MP4 或显示首帧。

XWP-304 元素类型未知

未来版本元素在旧客户端：

显示占位"元素需要更新版本"
升级客户端即可

4xx 网络错误

XWP-401 WebSocket 连接失败

多端联动核心错误：

防火墙阻断 WebSocket
网络不稳
服务端压力

排查：

检查 WSS 端口（默认 443）
临时切到 4G / 其他网络
等待服务恢复

降级：自动切换到 HTTP 长轮询。

XWP-402 心跳超时

客户端 60s 未发心跳被踢：

客户端进入后台（手机 / 平板）
网络抖动
客户端崩溃

自动恢复：重连后同步当前状态。

XWP-403 资源请求失败

CDN / OSS 资源 404 / 5xx：

资源被删除
CDN 缓存问题
临时服务故障

刷新页面 / Hard Reload (⌘+Shift+R)。

5xx 服务端错误

XWP-501 服务器内部错误

未预期错误：

报告给平台（错误日志已自动上传）
等待修复（通常 < 1 小时）
继续等待 → "状态页"查看

XWP-502 数据库连接失败

后端基础设施问题：

等待恢复
数据有备份，不会丢失

XWP-503 服务过载

高并发场景：

自动降级（部分功能暂停）
队列等待

6xx 权限错误

XWP-601 未登录

需要登录：

引导到登录页
登录后回到原页面

XWP-602 权限不足

操作	需要权限
编辑	编辑者
评论	评论者 + 以上
看	查看者 + 以上
发起房间	主讲人

XWP-603 超出会员等级

要求专业 / 团队 / 企业版：

升级会员
或转给有权限的人

XWP-604 内容受限（敏感）

平台审核拦截：

政治敏感
暴力 / 色情
联系客服申诉

7xx AI 错误

XWP-701 AI 余额不足

订阅额度用完：

加购按量
升级会员
等下个计费周期

XWP-702 AI 调用超时

某次调用超过 60s：

重试
检查输入是否过长
切换备用模型

XWP-703 AI 内容拒绝

AI 模型拒绝生成（可能涉敏）：

修改 Prompt
联系客服

XWP-704 AI 服务故障

模型服务暂时不可用：

自动降级到非 AI 版本
等待恢复

8xx 协作错误

XWP-801 元素被锁

其他人正在编辑：

等待锁释放
联系对方
强制接管（仅文件主）

XWP-802 版本冲突

两人同时改了同一元素：

自动合并（CRDT）
提示选择保留哪个版本

XWP-803 协作者超限

超出会员等级允许的协作人数：

移除多余协作者
升级会员

9xx 配额错误

XWP-901 演示文稿数超限

免费版 5 份，需要升级或删除旧文件。

XWP-902 单页元素数超限

200 个元素，建议拆页或简化。

XWP-903 上传文件超大

单文件 > 50MB：

压缩
大视频用外链
升级会员

XWP-904 月度流量超限

企业版有月度配额，需要升级套餐。

诊断报告

任何错误页面有"提交诊断报告"按钮：

自动收集错误码 + 上下文
浏览器版本 / 设备
错误堆栈
不会上传演示内容

提交后到"我的演示 → 反馈"查看。详见「88. 反馈渠道与支持」。

状态页

实时查看玄武屏服务状态：

https://status.bahuangqi.com
各模块在线状态
历史故障记录
维护通知

下一节讲开发者 API。