排障

现象	原因与处理
ModuleNotFoundError	确认 pip 与运行代码使用同一 Python/虚拟环境。
VfpError: 不支持的 VFP 文件版本	Python SDK 只实现 VFP 1.3；不要把 HarmonyOS 的 1.2 读取兼容误写为 Python 能力。
thumbnail() 为 None	输入没有 THMB；当前 Python 编译器不生成缩略图。
read_section("PRVW") 失败	输入没有 PRVW 或区段 CRC 错误；重新由 JSON 编译时启用 include_preview=True。
GLTI 需要 ffmpeg	传入已有 video_path，或安装 ffmpeg，或设置 include_video=False。
GLTI 无法恢复	该文件可能是 embed_editable_vfp=False 的展示专用包；不能从视频/GLB 反推 VFP。

跨网络、导出或 GLTI 打包前执行 Vfp.parse(path).validate()。不要以 META、THMB、PRVW 或缓存存在性代替权威验证。