Next.js部署至本地服务器时环境变量未加载如何解决

问题根因 #

三个配置错误共同导致问题：

1. env.local 文件格式不符合 Next.js 解析规则：等号两侧加了空格、值额外包裹了单引号，dotenv 解析时会将空格、引号计入变量名/变量值，无法正确读取配置。
2. 环境变量前缀使用错误：_app.js 中的 MoralisProvider 属于客户端运行代码，读取的环境变量必须加 NEXT_PUBLIC_ 前缀才能被注入到客户端 bundle，之前加前缀报错是因为 env 文件格式错误导致变量值为 undefined，并非前缀本身有问题。
3. 环境变量仅在 Next.js 服务启动时加载，修改 env 文件后未重启服务、未清缓存也会导致配置不生效。如果看不到 env 加载提示，先确认 env.local 放在项目根目录（和 package.json 同层级），放错路径 Next.js 不会扫描该文件。

修复步骤 #

• 第一步：修正 env.local 配置
  确认文件位于项目根目录，替换内容为以下格式，等号两侧不要加空格，值不要包裹任何引号：

  NEXT_PUBLIC_MORALIS_SERVER_URL=https://8oyk5t00zoyz.usemoralis.com:2053/server
  NEXT_PUBLIC_MORALIS_APP_ID=l9iAGdkJCtFrMAlp8ot12XVtgbeXiwul9iKhgZD9
  

• 第二步：替换 _app.js 中的硬编码配置
  读取环境变量时需要用 JSX 表达式花括号包裹，不要直接写字符串形式的变量名，修改后代码：

  function MyApp({ Component, pageProps }) {
    return (
      <MoralisProvider
        serverUrl={process.env.NEXT_PUBLIC_MORALIS_SERVER_URL}
        appId={process.env.NEXT_PUBLIC_MORALIS_APP_ID}
      >
        <Component {...pageProps} />
      </MoralisProvider>
    )
  }
  export default MyApp
  

• 第三步：清缓存重启服务
  停掉当前运行的本地服务，删除项目下的 .next 缓存文件夹，重新执行启动命令（npm run dev / yarn dev / pnpm dev），启动时终端就会输出 env 加载成功的提示。

校验方法 #

如果仍有问题，可以在 next.config.js 顶部加临时日志，确认环境变量是否被正确读取：

// 临时校验代码，确认加载正常后可删除
console.log("Moralis 环境变量校验：", {
  serverUrl: process.env.NEXT_PUBLIC_MORALIS_SERVER_URL,
  appId: process.env.NEXT_PUBLIC_MORALIS_APP_ID
})

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
}
module.exports = nextConfig

重启服务后如果终端能打印出正确的 serverUrl 和 appId，说明 env 加载逻辑正常，排查代码中变量名拼写错误即可。

注意：只有服务端运行的代码（getServerSideProps、Next.js API Routes、服务端组件）可以读取不带 NEXT_PUBLIC_ 前缀的环境变量，所有浏览器端执行的代码必须使用带前缀的变量，否则会拿到 undefined。

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