Next.js部署到Vercel后环境变量怎么不生效？

东方炳錦提问于 2026-03-11 14:06:20 阅读 25

框架

我在本地开发时用 .env.local 存放API密钥，一切正常。但推到Vercel后，页面里读不到这些变量，控制台全是undefined。明明在Vercel项目设置里也加了同样的环境变量，命名完全一致，为啥还是不行？

我试过把变量名改成 NEXT_PUBLIC_ 开头，但有些敏感密钥不能暴露给前端啊，难道非得全加前缀？

React框架 Vercel部署

我来解答赞 3 收藏

反馈

2 条解答

W″羽墨 Lv1

遇到这种情况确实挺让人头疼的。首先，Next.js 的环境变量处理机制在不同环境下是有区别的，特别是在本地开发和部署到 Vercel 这两种情况下。

具体来说，Next.js 区分了客户端和服务器端的环境变量。如果你想要在服务器端使用的变量（比如 API 密钥），就不能加 NEXT_PUBLIC_ 前缀，因为加了这个前缀的变量会被暴露到客户端，这显然不适合存放敏感信息。

你提到已经在 Vercel 项目设置里添加了环境变量，并且命名是一致的，但仍然读不到。这里有几个可能的原因和解决办法：

1. 检查环境变量的大小写：Next.js 和 Vercel 对环境变量的名字是区分大小写的，确保你在代码中引用的变量名和在 Vercel 设置中的名字完全一致。

2. 重新部署项目：有时候 Vercel 并不会立即应用新的环境变量，尝试重新部署你的项目，看看是否能解决问题。

3. 确保在正确的阶段使用变量：在 Next.js 中，某些钩子或者生命周期方法是在构建时运行的，而某些是在运行时。如果你的代码在构建时就试图读取环境变量，而这些变量是在运行时才有的，就会出问题。确保你在运行时读取这些变量。

4. 检查 Next.js 配置：虽然你提到的是 Vercel 的设置，但有时候项目的 next.config.js 文件也可能影响环境变量的行为。确保这里没有覆盖或者错误地配置了环境变量。

5. 调试输出：在代码中加入一些调试信息，输出一下环境变量，看看到底有没有获取到正确的值。这样可以确定问题是出在哪里。

下面是一个简单的例子，展示如何在 Next.js 中正确使用环境变量：

// next.config.js

module.exports = {

  // 其他配置...

  env: {

    // 如果你需要在构建时注入环境变量，可以在这里定义

    // 注意：这里的变量会暴露在客户端，谨慎使用

  },

};



// pages/api/example.js

export default function handler(req, res) {

  // 这里是运行时，可以直接读取环境变量

  const apiKey = process.env.YOUR_API_KEY;

  if (!apiKey) {

    console.error('API key is not defined');

    return res.status(500).json({ error: 'API key is missing' });

  }

  // 使用 apiKey 进行后续操作...

}



// pages/index.js

import { useEffect } from 'react';



export default function Home() {

  useEffect(() => {

    // 在客户端，只能读取以 NEXT_PUBLIC_ 开头的环境变量

    // 如果你需要在这里使用敏感信息，考虑通过 API 请求从服务器端获取

  }, []);



  return Welcome to Next.js!
;

}

总结一下，确保环境变量的命名一致、重新部署项目、检查变量的使用时机，这些都是解决这个问题的关键步骤。希望这些建议对你有帮助。

2026-03-22 21:28

迷人的玉研 Lv1

这问题很常见，本质上是 Next.js 环境变量的作用域问题。

服务端变量和客户端变量是两码事。你在 Vercel 后台加的变量是生效的，但只有加 NEXT_PUBLIC_ 前缀的才会暴露给前端。

简单说：

如果你的变量用在客户端组件里，必须加 NEXT_PUBLIC_ 前缀，没得商量。敏感密钥不能放前端，这是铁律。

如果你的变量只用在后端（比如 API routes、getServerSideProps、getStaticProps 里的服务端代码），直接用 process.env.变量名，不需要前缀，Vercel 后台加的变量直接就能读到。

所以正确的做法是：敏感密钥不要在客户端代码里直接用，通过 API route 代理一下，在服务端请求第三方接口。

还有个坑：你在 Vercel 加完环境变量后，需要重新部署一次才生效，不是自动生效的。

改一下就行：敏感逻辑搬到 API routes 或者 getServerSideProps 里处理，客户端只管调接口。

2026-03-11 14:08