Next.js 13独立构建下getServerSideProps无法获取环境变量

问题概况 #

从旧版Next.js迁移时遇到以下异常：

• 开发环境或执行next start时，getServerSideProps能正常读取环境变量SOME_VALUE
• 启用独立构建（next.config.js中设置output: "standalone"）后，getServerSideProps中process.env.SOME_VALUE变为undefined
• 改用getStaticProps曾临时解决问题，但动态路由（如[id].tsx）即使设置fallback: 'blocking'仍会出现同样错误

原因分析 #

独立构建模式下，Next.js会对产物做深度优化：默认仅将客户端代码引用的环境变量（如带NEXT_PUBLIC_前缀的变量）打包进独立产物。对于仅在服务端函数（getServerSideProps、getStaticProps）中使用的非NEXT_PUBLIC_变量，若未显式配置，构建时不会被注入到服务端代码中，导致运行时无法读取。

解决方案 #

1. 在next.config.js中显式声明环境变量

通过env字段将需要的环境变量映射到应用中，确保构建时将变量注入服务端代码：

// next.config.js
module.exports = {
  output: "standalone",
  env: {
    SOME_VALUE: process.env.SOME_VALUE,
  },
};

配置后，无论是getServerSideProps还是带fallback: 'blocking'的动态路由getStaticProps，都能正常读取process.env.SOME_VALUE。

2. 确保构建时环境变量已加载

• 若使用.env.local存储环境变量，需确保文件命名符合Next.js规范（如.env.local不会被Git追踪，Next.js默认自动加载根目录下的.env*文件）
• 在CI/CD环境中，需在执行next build前设置好对应环境变量，避免构建阶段变量缺失

3. 避免不必要的NEXT_PUBLIC_前缀

若变量仅在服务端使用，无需添加NEXT_PUBLIC_前缀（该前缀会将变量暴露给客户端，存在安全风险），通过上述next.config.js的env配置即可满足服务端函数的读取需求。

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