排查显示问题
修复 PDF 未在店铺前台显示的常见问题。
PDF 完全不显示
请检查以下三个条件：
✅ PDF 已链接到相关资源（产品、页面等）
✅ PDF 状态为已激活（未设为未激活）
✅ 主题应用扩展 已添加到您的主题
三个条件必须同时满足。逐一检查：
- 打开您的 PDF 库
- 点击应显示的 PDF
- 确认它已链接到正确的资源
- 检查状态是否设置为已激活
- 进入主题编辑器，确认扩展已添加
如果您使用的是手动区块（PDF Embedded Manual 或 PDF Button Manual），则上述链接检查不适用，请使用以下手动区块检查项。
手动 URL 区块不显示任何内容
- 确认您输入了至少一个有效的
https://...pdfURL - 确认该区块位于激活中的产品模板上
- 在主题编辑器中保存，并对店铺前台进行强制刷新
- 暂时将查看器类型设为原生浏览器，以排除自定义查看器参数问题
- 如果使用手动按钮标签，请确认标签行数与 URL 行数相符
PDF 显示在错误的页面上
可能原因：
链接了错误的资源
- 检查该 PDF 已链接到哪些资源
- 从错误的资源中取消链接
- 链接到正确的资源
模板筛选条件不匹配
- 检查模板筛选设置
- 确认页面正在使用预期的模板
- 删除或调整模板筛选条件
部分 PDF 显示，其他 PDF 不显示
检查各 PDF 的状态：
- 未显示的 PDF 可能已设为未激活
- 将缺失的 PDF 状态更改为已激活
检查模板筛选条件：
- 部分 PDF 可能已应用模板筛选条件
- 检查未显示 PDF 的筛选设置
主题编辑器中找不到主题应用扩展
主题兼容性问题：
您的主题可能不支持应用扩展：
- 查看主题文档，确认是否支持应用扩展
- 将主题更新至最新版本
- 联系主题开发者寻求支持
- 考虑切换至支持扩展的主题
大多数现代 Shopify 主题（2.0+）均支持应用扩展。
PDF 加载缓慢
优化文件大小：
- 上传前压缩 PDF
- 尽量将文件控制在 5MB 以内
- 删除不必要的页面或图片
检查网络连接：
- 慢速网络会影响加载速度
- 更换网络环境进行测试
- 比较移动数据与 WiFi 的速度
使用按钮显示方式：
- 按钮样式加载速度比嵌入式更快
- 顾客只有点击后才加载 PDF
- 更适合移动端用户
嵌入式查看器显示空白
PDF 可能已损坏：
- 尝试重新上传 PDF
- 先在您的电脑上打开 PDF，确认文件可正常使用
- 使用其他软件重新保存 PDF
浏览器兼容性：
- 尝试使用其他浏览器
- 将浏览器更新至最新版本
- 清除浏览器缓存
显示了错误的 PDF
检查链接关系：
- 查看该 PDF 已链接的资源
- 从不应显示的页面取消链接
- 确认每个资源链接了正确的 PDF
链接了多个 PDF：
- 如果链接了多个 PDF，它们都会显示
- 取消不需要显示的 PDF 的链接
- 如有需要，重新排序
对于手动区块，请直接在区块设置中检查 URL 行，而非检查链接关系。
PDF 按钮无法打开
JavaScript 问题：
- 在浏览器控制台中检查错误信息
- 尝试使用其他浏览器
- 暂时禁用可能冲突的应用
主题冲突：
- 部分主题会阻止弹窗
- 检查主题设置
- 联系主题开发者
模板筛选不起作用
常见错误：
模板名称有误：
- 模板名称区分大小写
- 仔细检查拼写
- 确认该模板存在于您的主题中
模板未激活：
- 页面可能正在使用其他模板
- 在主题编辑器中检查实际使用的模板
- 为页面分配正确的模板
更改后未显示效果
缓存延迟：
- 更改后等待 30-60 秒
- 刷新页面（强制刷新：Cmd/Ctrl + Shift + R）
- 如有需要，清除浏览器缓存
主题未保存：
- 确认您在主题编辑器中点击了"保存"
- 检查是否有未保存的更改提示
仍有问题？
请尝试以下步骤：
-
全面刷新：
- 强制刷新浏览器
- 在编辑器中重新保存主题
- 等待几分钟
-
在无痕模式下测试：
- 打开全新的浏览器会话
- 跳过缓存问题
- 排除浏览器扩展的干扰
-
检查不同页面：
- 查看不同的资源（产品/页面）
- 对比首页与产品页面
- 定位问题所在位置
-
联系支持：
- 描述您看到的情况与预期结果
- 如有可能，提供截图
- 说明您的主题名称
- 注明套餐类型