Next.js项目部署Vercel时@next/third-parties Google Analytics类型报错

问题原因 #

本地开发正常但Vercel部署失败，核心是process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS的类型为string | undefined，而GoogleAnalytics组件的gaId属性要求必须是string类型。另外可能是Vercel平台未正确配置对应的环境变量，导致构建时变量值为undefined。

解决方案 #

1. 确认Vercel环境变量配置 #

• 进入Vercel项目的「Settings」→「Environment Variables」页面
• 添加变量NEXT_PUBLIC_GOOGLE_ANALYTICS，值填写你的Google Analytics ID
• 注意变量名必须以NEXT_PUBLIC_开头，否则客户端代码无法读取该变量

2. 代码层面处理类型不匹配 #

方法一：非空断言（推荐，需确保变量已配置）

直接通过!断言变量不为undefined：

<GoogleAnalytics gaId={process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS!} />

方法二：条件渲染

仅当变量存在时才渲染组件，避免类型错误：

{process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS && (
  <GoogleAnalytics gaId={process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS} />
)}

方法三：添加类型声明（可选）

在项目根目录创建env.d.ts文件，明确环境变量的类型：

namespace NodeJS {
  interface ProcessEnv {
    NEXT_PUBLIC_GOOGLE_ANALYTICS: string;
  }
}

这样TypeScript会认定该变量始终为string类型，消除代码中的类型提示错误。

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