WordPress自定义主题添加Google Tag Manager预览失败求助

排查步骤 #

基础配置排查

• 确认代码中的GTM-XXXXXXX占位符已替换为你实际的GTM容器ID，填写错误会直接导致预览无法识别。
• 禁用所有浏览器扩展（广告拦截、隐私防护类扩展是GTM加载失败的高发原因）后重新测试预览。
• 打开浏览器控制台的「网络」面板，检查gtm.js资源是否加载成功，有没有404、跨域、被拦截的报错。
• 确认你的站点为公网可访问环境，本地/内网未穿透的站点无法被GTM预览服务连接。

和locomotivescroll.js、swup.js的关联验证

这两款库确实存在影响GTM预览的可能：

• swup的无刷新加载逻辑会修改默认的页面生命周期，GTM预览依赖初始页面加载的全局变量绑定，若swup未配置GTM兼容逻辑会导致连接中断
• locomotivescroll的DOM结构修改、全局事件劫持逻辑，可能会干扰GTM预览的心跳检测机制

验证方法：临时注释掉两个库的加载代码，再测试GTM预览是否正常，若恢复正常即可确认是库的兼容问题。

兼容修复方案

• 调整GTM脚本加载优先级，将add_action( 'wp_head', 'add_gtm_head', 10 );中的优先级从10改为1，让GTM脚本早于其他业务脚本加载，避免被后续初始化逻辑干扰。
• 给swup添加页面切换钩子，每次路由切换后主动推送事件到dataLayer，示例代码：

document.addEventListener('swup:pageView', () => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ event: 'gtm.pageRefresh' });
});

• 检查locomotivescroll初始化配置，关闭对页面内script标签的清理、拦截逻辑，避免GTM注入的脚本被意外移除。

内容的提问来源于stack exchange，提问作者CarlVarsh