Next.js中用环境变量调用GTM ID提示标签未找到求助

问题场景 #

直接在代码中硬编码Google Tag Manager（GTM）ID时功能正常，但将ID放入.env.local文件，通过${process.env.NEXT_PUBLIC_GTM_ID}调用时，系统返回「Google Tag Not Found」错误。

相关代码片段 #

• _app.js：

<Script
  id="gtag-base"
  strategy="afterInteractive"
  dangerouslySetInnerHTML={{
    __html: `
      (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
      new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
      j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
      'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
      })(window,document,'script','dataLayer', '${process.env.NEXT_PUBLIC_GTM_ID}');
    `,
  }}
/>

• _document.js：

<noscript>
  <iframe
    src={`https://www.googletagmanager.com/ns.html?id=${process.env.NEXT_PUBLIC_GTM_ID}`}
    height="0"
    width="0"
    style={{ display: 'none', visibility: 'hidden' }}
  />
</noscript>

• .env.local：

NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX

排查与解决步骤 #

1. 确认环境变量加载逻辑 #

• 确保.env.local文件位于项目根目录，而非子文件夹中。
• 修改.env.local后必须重启Next.js开发服务器（停止当前npm run dev/yarn dev进程，重新启动）——Next.js仅在启动时读取环境变量，运行时修改不会生效。
• 在组件中添加日志验证变量是否加载：在_app.js的函数组件顶部添加console.log(process.env.NEXT_PUBLIC_GTM_ID)，打开浏览器控制台查看是否输出正确的GTM ID。

2. 检查模板字符串渲染结果 #

• 打开页面源码（右键→查看页面源代码），搜索gtm.js和ns.html，确认生成的URL是否为https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX和https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX。
• 若URL中ID为空或异常，说明环境变量未正确注入，需检查变量名拼写（必须以NEXT_PUBLIC_开头，否则客户端无法访问）。

3. 核对语法与兼容性 #

• 确保使用的Next.js版本支持next/script组件（需Next.js 11及以上版本）。
• 确认代码中模板字符串的变量插入语法无误，例如'${process.env.NEXT_PUBLIC_GTM_ID}'的单引号包裹是正确的，避免变量被解析为无效字符串。

4. 验证GTM ID有效性 #

确认.env.local中的GTM ID与硬编码的完全一致（无多余空格、大小写错误），避免复制粘贴时出现疏漏。

总结 #

最常见的问题是环境变量未正确加载（未重启服务器、文件位置错误），或变量名拼写错误（未加NEXT_PUBLIC_前缀）。按上述步骤逐一排查后，通常可解决「Google Tag Not Found」错误。

内容的提问来源于stack exchange，提问作者Carlos Henrique R. Pereira