Next.js部署到Netlify/Vercel后.env环境变量失效问题求助

问题详情 #

本地执行npm run dev时API相关功能完全正常，但部署到Netlify或Vercel平台后，API无法从.env文件中获取密钥。已尝试使用普通变量名（如YOUR_PUBLIC_KEY）和带NEXT_PUBLIC_前缀的变量名，问题仍未解决。

本地.env.local内容 #

YOUR_SERVICE_ID="abc"
YOUR_TEMPLATE_ID="def"
YOUR_PUBLIC_KEY="ghy"

NEXT_PUBLIC_YOUR_SERVICE_ID="abc"
NEXT_PUBLIC_YOUR_TEMPLATE_ID="def"
NEXT_PUBLIC_YOUR_PUBLIC_KEY="ghy"

Contact组件核心代码 #

import emailjs from "@emailjs/browser";
import React, { useRef } from "react";

const Contact = () => {
  const form = useRef();

  const sendEmail = (e) => {
    e.preventDefault();

    emailjs
      .sendForm(
        process.env.NEXT_PUBLIC_YOUR_SERVICE_ID,
        process.env.NEXT_PUBLIC_YOUR_TEMPLATE_ID,
        form.current,
        process.env.NEXT_PUBLIC_YOUR_PUBLIC_KEY
      )
      .then(
        (result) => {
          console.log(result.text);
        },
        (error) => {
          console.log(error.text);
        }
      );
    e.target.reset();
  };

  return (
    // 组件渲染内容
  )
}

export default Contact;

package.json关键配置 #

{
  "name": "portfolio-nextjs",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@emailjs/browser": "^3.10.0",
    "next": "13.2.4",
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

解决步骤 #

1. 在部署平台手动配置环境变量 #

本地.env.local文件默认不会被提交到Git（Next.js已将其加入.gitignore），因此部署平台无法读取该文件中的变量。需在平台控制台手动添加对应变量：

• Vercel：进入项目 → Settings → Environment Variables，添加变量名和对应值（无需加引号，直接填写abc这类内容）
• Netlify：进入项目 → Site settings → Environment variables，添加变量名和对应值

变量名必须与代码中使用的完全一致，比如代码里用NEXT_PUBLIC_YOUR_SERVICE_ID，平台配置里也要用相同名称。

2. 移除.env文件中变量值的引号 #

.env文件中的变量值不需要添加引号，Next.js会自动处理字符串内容。如果保留引号，实际读取到的变量值会包含引号，导致API调用失败。修改后的.env.local如下：

YOUR_SERVICE_ID=abc
YOUR_TEMPLATE_ID=def
YOUR_PUBLIC_KEY=ghy

NEXT_PUBLIC_YOUR_SERVICE_ID=abc
NEXT_PUBLIC_YOUR_TEMPLATE_ID=def
NEXT_PUBLIC_YOUR_PUBLIC_KEY=ghy

3. 确认Next.js环境变量规则 #

你使用的Next.js 13.2.4中，客户端组件（如Contact组件，因为它在浏览器中执行emailjs调用）必须使用NEXT_PUBLIC_前缀的变量才能被暴露到客户端。无前缀的普通变量仅能在服务端代码（如API路由）中使用，客户端无法读取。

4. 清除缓存并重新部署 #

添加完平台环境变量后，需触发全新部署以确保变量生效：

• Vercel：在Deployments页面点击"Redeploy"，勾选"Clear build cache"
• Netlify：在Deploys页面点击"Trigger deploy" → "Deploy site"，清除现有缓存

5. 验证变量注入情况 #

可在Contact组件中添加日志输出，验证变量是否被正确注入：

console.log("Service ID:", process.env.NEXT_PUBLIC_YOUR_SERVICE_ID);

部署后打开浏览器控制台，若输出undefined，说明变量未正确注入，需重新检查平台配置和变量名拼写。

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