Shopify app embed 不显示：激活、深链与主题排查

Shopify 应用已安装，聊天气泡却不出现时，先确认它使用 app embed，再检查主题里的激活和保存状态。安装、编辑器预览、保存后的店铺表现，是三个需要分别取证的环节。本文沿着这条路径排查，并给应用开发者一份最小注入诊断示例。官方资料核验日期：2026 年 10 月 11 日。

1. 确认功能属于 app embed，并核对注入位置

App embed 常用于悬浮聊天窗口、覆盖层，或者没有可见界面的代码；放在商品信息之间、需要商家拖动位置的内容通常属于 app block。两者的 schema 不同：app block 使用 target: "section"，app embed 使用 head、body 或 compliance_head。Shopify 在 HTML 的 head 或 body 结束标签之前注入 embed；compliance_head 只应在确有优先插入需求时使用，例如 Cookie 同意功能。具体用途及取值见 Shopify 的 app embed 配置说明。

先向应用提供方确认嵌入名称、是否有可见组件，以及应在哪些页面出现。没有界面的 embed 不能用“看不到按钮”判断失效。App embed 支持旧版主题和 Online Store 2.0，不依赖 section 或 JSON 模板；主题应用扩展也不能通过这一入口渲染结账步骤页面。见官方的 主题支持说明和 页面限制。

2. 在目标主题和市场中激活，然后保存

应用安装后，app embed 默认关闭。按下面顺序操作，并记录主题名称、市场和测试页面，方便将编辑器状态与店铺页面对上。

1. 在 Shopify 后台进入 Online Store，找到要修改的主题，点击 Edit theme；核对它是否就是当前访问页面所使用的主题。
2. 若要配置特定市场，在编辑器的 Market 菜单选择该市场。未选择市场时，修改应用于 Store default。
3. 打开侧栏的 App embeds，找到对应嵌入，将开关打开；展开它的设置，按应用说明补齐必要配置。
4. 点击 Save。仅在预览里打开开关，不能替代保存。
5. 重新打开该主题的预览，并访问同一市场、同一页面确认结果；需要验证已发布店铺时，再单独检查公开页面。

这套激活步骤和市场选择规则来自 Shopify 帮助中心。帮助中心同时说明：更换已发布主题后，需要在新主题重新激活相关应用。因此，先前主题里的启用截图不能证明新主题已经启用。

3. 开发者提供激活深链，明确保留保存步骤

应用可以在安装后提供一个按钮，把商家直接带到编辑器中的 embed 激活预览。下面是使用占位值的 URL 结构，需替换店铺域名、应用标识和 block handle，不能原样作为可用链接：

https://<shop>.myshopify.com/admin/themes/current/editor?context=apps&template=product&activateAppId={api_key}/app-embed

• context=apps 指定应用激活上下文；embed 使用 activateAppId，实体 app block 的添加参数是 addAppBlockId。
• api_key 是应用的 API key，也就是应用配置中的 client_id，并非 API secret 或访问令牌。官方已将旧的 extension uuid 参数标为废弃。
• handle 来自嵌入的 Liquid 文件名：blocks/app-embed.liquid 对应 app-embed，不是整个 extension 在 TOML 中的 handle。
• 官方为 template 列出 product、collection、article、blog，省略时默认 index。仍要核对 embed 自身的模板限制和打开后的目标主题；一个链接不能证明所有页面都已生效。

参数定义见 官方 app embed 深链说明。官方模板使用 /themes/current/editor；打开后仍需核对主题名称、预览效果并点击 Save。深链文档明确将它描述为保存前的预览流程，不应在应用里把“按钮已点击”当成店铺功能已经启用的完成凭据。

4. 按列表、页面输出和脚本三个层次定位故障

前两层的官方依据是：available_if 引用 boolean 类型的 app-data metafield，影响店面渲染和编辑器可见性；enabled_on 与 disabled_on 可以限制 embed 的模板，且不能同时使用。见 条件区块与 schema 定义。第三层是建议的浏览器排查方法，需根据现场证据确认原因。

应用开发者可在开发店的主题应用扩展中，用 blocks/embed-probe.liquid 单独验证注入路径。这个最小示例故意隐藏节点，可在 Elements 搜索其 ID；它只帮助检查该诊断 embed 的输出，不包含原应用的业务脚本，也不能证明聊天功能正常：

<div id="embed-probe-marker" hidden></div>
{% schema %}
{
  "name": "Embed probe",
  "target": "body",
  "settings": []
}
{% endschema %}

示例未在实际商店运行。开发者需按照 官方开发店预览流程启用这个诊断 embed，分别观察开关关闭、开启并保存后的页面输出；不要让商家把这段扩展代码直接粘贴进主题文件。

5. 查重复加载，并验收关闭和重新启用

出现两个气泡时，先比较组件节点、脚本 URL 和 Network 的 Initiator，区分同一脚本重复初始化、不同入口加载、旧手工代码等可能原因。Shopify 的去重承诺有具体边界：多个 app block 或 embed 通过 schema 引用同一个 JavaScript 或 stylesheet 文件时，该文件在一次页面加载中只引入一次。这不等于业务初始化只发生一次，也不能据此断定旧手工脚本会被去重。见 官方资产加载规则。

开发者还可以只读核对目标主题的 config/settings_data.json：embed 首次启用后才会写入记录，之后关闭仍保留记录，并将 disabled 设为 true。因此，“文件里有记录”不能单独证明当前启用。见 官方 embed 状态识别说明。

修复后，在同一主题、市场和页面测试关闭并保存、重新启用并保存、页面重载，以及桌面和手机上的显示与操作。关闭后若仍有组件，保留其加载来源，再请应用提供方核查；Shopify 帮助中心明确区分 直接写入主题代码的应用，不能把 embed 开关当成所有旧代码的清理按钮。悬浮组件也应检查是否遮挡内容，这是 官方扩展测试流程列出的验收项。涉及新增权限或改动范围时，先补齐 定制应用的需求、权限与发布 QA，再安排开发。