接入
引擎创建 / init() 失败
EngineConfig必须设置非空的licenseToken。Web 配置上没有appId/appKey字段。- 生产环境:你的服务器必须返回鉴权接口的响应体(
{success, token}或错误 JSON)。见 授权与许可。 - 确认页面能下载到 SDK 运行时文件(打包器 / CDN)。见 错误处理。
- 确认页面是 HTTPS 或 localhost。
- 查看
FacebetterError.code(错误处理)。
怎么传 AppID / AppKey?
不要写在EngineConfig 上。密钥放在服务器,换好 token 再传入 licenseToken。
浏览器能用离线 .lic 吗?
不能。Web 必须走在线 v2 鉴权。
如何升级包?
效果
美颜太弱或过猛
强度范围[0.0, 1.0]。美型范围 [-1.0, 1.0](0 为关闭)。静图可试 FrameType.Image。风格枚举见 参数枚举。
滤镜 / 贴纸没效果
把.fbd 的路径或字节直接传给 setFilter / setSticker。空字符串会抛错 — 关闭请用 clearFilter() / clearSticker()。
虚拟背景是黑的 / 没变化
调用setVirtualBackgroundBlur(level) 或 setVirtualBackground(path|Uint8Array),不要传 options 对象。虚化传 0 会关闭效果。绿幕时 setChromaKey 只设遮罩,仍需设置虚化或背景图。
输出全黑
视频可能还没有帧(videoWidth === 0),或拿不到 Canvas 上下文。仅在 engine.initialized 之后调用 processImage。
性能
预览卡
摄像头:使用FrameType.Video,限制采集分辨率(例如 720p),不要开关键点回调,循环放在 requestAnimationFrame 里。可看 engine.getStats().avgProcessTimeMs。
相册 / 影楼大图不要把原图每滑一次送进 processImage。打开文件时做一份较小的预览帧,导出时再处理原图一次。见 最佳实践。
SPA 里内存一直涨
离开页面时调用engine.destroy()。路由切换不要泄漏引擎实例。
兼容性
支持 Chrome 57+、Firefox 52+、Safari 11+、Edge 16+。移动端建议降低采集分辨率和参数强度。React 示例
demo/web/react。

