EasyLottie指南
为什么我的 Lottie 动画无法播放？ （以及如何修复它）
空白画布、缺失图像或动画无法移动？以下是 Lottie 无法渲染的常见原因，以及如何快速确定原因。
首先将文件与代码隔离
当 Lottie 无法在您的应用程序中播放时，第一个问题是问题是文件还是集成。最快的查找方法是在独立的 Lottie 查看器中打开同一文件。如果它在那里播放但不在您的应用程序中播放，则问题出在您的运行时设置上；如果在查看器中也失败，则文件本身需要注意。
将 JSON（或 ZIP）放入 EasyLottie 预览中。它在您的浏览器中本地呈现，因此您无需接触代码库即可立即获得诚实的答案。
最常见的原因
大多数“Lottie 无法播放”报告都归结为简短的原因列表。按顺序完成它们。
| 症状 | 可能的原因 | 修复 |
|---|---|---|
| 应该放置图像的空白框 | 外部图像资源丢失 | 上传包含 JSON + 图像的 ZIP，或嵌入图像 |
| 根本没有显示任何内容 | JSON 损坏/无效，或文件错误 | 重新导出动画；确认它是真的 Lottie JSON |
| 在查看器中播放，而不是在您的应用程序中播放 | 渲染器或运行时设置 | 检查lottie-web/lottie-react配置、自动播放和循环 |
| 零件缺失或错误 | 不支持的表达式/效果 | 重新导出而不包含不支持的功能，或栅格化 |
| 在页面上不可见 | 无尺寸或相同颜色的背景 | 给出容器的宽度/高度；改变背景 |
修复#1：丢失图像（最常见的图像）
一个非常常见的情况是引用外部图像文件的 Lottie JSON。 JSON 本身无法加载这些图像，因此您会看到空白框。修复方法是上传包含 JSON 及其图像文件夹的 ZIP，或者重建嵌入图像的文件。如果您不确定您的文件是否使用外部图像，预览它会立即显示空白。
修复#2：它在查看器中播放，但不在您的应用程序中播放
如果该文件在预览中具有动画效果，但在您的产品中没有，则该文件没问题 - 集成则不然。检查动画容器是否具有真实的宽度和高度，自动播放和循环是否按照您期望的方式设置，以及渲染器（SVG 与画布）是否支持动画使用的内容。与动画颜色相同的背景也可以使完美工作的 Lottie 看起来隐形。
快速清单
- 在 Lottie 预览中打开文件以隔离文件与集成。
- 如果图像为空白，请上传带有 JSON + 图像文件夹的 ZIP。
- 如果没有任何显示，请重新导出并确认其有效 Lottie JSON。
- 如果它仅在查看器中播放，请检查容器大小、自动播放、循环。
- 切换背景颜色以排除同色不可见的情况。
重现工作流程
使用这些本地示例文件重复本指南中描述的检查。在生产项目中使用该文件之前请先检查该文件。
诊断基线：在更改文件之前证明播放器
旋转器和脉冲下载是已知良好的控件，具有相同的结构元数据：240 x 240、30 fps、60 帧、两秒、一层，并且没有外部资源。测试两者可以防止单个幸运渲染隐藏间歇性加载或容器问题。
| 观察结果 | 可能的边界 | 下一步行动 |
|---|---|---|
| 底线都没有发挥 | 页面、播放器、容器、策略或 JavaScript 设置 | 检查加载错误和运行时初始化 |
| 基线播放，原始为空白 | 原始 JSON、帧范围、不支持的功能或对比度 | 检查元数据和渲染器支持 |
| 形状发挥作用，图像为空白 | 外部资源路径或缺少包文件 | 使用完整 ZIP 和 assetsPath 重新测试 |
| 浏览器正常，应用程序失败 | 目标运行时支持或集成 | 比较目标支持的特征矩阵 |
| 动画可见但冻结 | 自动播放、循环、分段、方向或零大小时间范围 | 检查播放选项和输入/输出点 |
使用加载事件作为证据。 lottie-web 公开了 data_failed、loaded_images、DOMLoaded 和相关事件，这些事件比重复更改 CSS 更可靠地缩小失败阶段。
空白区域并不总是解析失败。零大小的容器、匹配的前景色和背景色、画布外变换以及暂停的第一帧都可能看起来像一个空的播放器。
了解极限
- 成功的浏览器渲染并不能证明与每个移动或本机渲染器兼容，因为支持的功能因平台和渲染引擎而异。
- 控制台错误可以识别加载和解析失败，但视觉上不正确的蒙版、表达式、文本层或混合模式可能需要逐层导出测试。
- 更改自动播放或循环无法修复丢失的资源、格式错误的 JSON、不受支持的功能或无效的帧范围。
如果你的结果不同
- 1.在同一容器中加载已知良好的本地 JSON，并使用与失败文件相同的播放器配置。
- 2.记录 data_ready、loaded_images、DOMLoaded 或 data_failed 是否触发。利用最后一个成功的阶段来缩小故障范围。
- 3.给容器明确的宽度和高度，临时设置对比背景，然后移动到第一个可见帧。
- 4.恢复完整的资源包，然后比较渲染器支持，如果结构加载但视觉结果错误，则隔离复杂层。
常见问题
为什么我的 Lottie 显示空白框而不是图像？
JSON 引用未与其捆绑的外部映像。上传包含 JSON 及其图像的 ZIP，或嵌入图像。
我的 Lottie 在查看器中播放，但不在我的应用程序中播放 - 为什么？
文件没问题；整合则不然。检查lottie-web 或lottie-react 中的容器大小、自动播放/循环设置以及渲染器配置。
我如何知道文件本身是否已损坏？
在 EasyLottie 预览中打开它。如果也无法在那里渲染，请重新导出动画并确认它是有效的 Lottie JSON。
为什么我的 Lottie 即使加载也看不见？
容器可能没有大小，或者背景颜色与动画相同。指定其宽度/高度并更改背景进行检查。
主要来源
根据下面的原始运行时或格式文档检查了技术行为。