使用Kamal部署Next.js时.env环境变量无法生效问题

1. 修正Next.js环境变量命名规则 #

如果你的页面是默认的客户端组件，Next.js要求客户端可访问的环境变量必须以NEXT_PUBLIC_为前缀。按以下方式调整：

• 本地.env文件中变量名改为：NEXT_PUBLIC_VALUE=你的值
• deploy.yml的secret配置更新为：

  env:
    secret:
      - NEXT_PUBLIC_VALUE
  

• 代码中变量引用改为：

  import React from 'react'
  
  function page() {
    const envVar = process.env.NEXT_PUBLIC_VALUE
  
    return (
      <div>
        <div>{envVar}</div>
        <div>End of ENV</div>
      </div>
    )
  }
  export default page
  

2. 重新执行Kamal环境变量推送与强制部署 #

按顺序执行以下命令，确保变量生效：

• kamal env push：将更新后的环境变量推送到服务器的加密存储
• kamal deploy --force-reboot：强制重启应用容器，避免因容器缓存导致变量不更新

3. 验证容器内的环境变量 #

登录服务器检查容器内是否存在目标变量：

• 执行kamal app exec进入应用容器
• 输入echo $NEXT_PUBLIC_VALUE，确认能输出正确的值
  如果容器内无此变量，检查deploy.yml的env配置是否存在缩进错误，确保变量名与.env文件完全一致。

4. 区分运行时与构建时变量注入 #

如果你的变量需要在Next.js构建阶段注入（比如用于静态页面生成），需将配置改为static类型：

env:
  static:
    - NEXT_PUBLIC_VALUE

之后执行kamal build重新构建镜像，再执行kamal deploy完成部署。

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