将Next.js从12升级到14时访问环境变量遇布尔字面量类型错误

排查方向及解决步骤 #

1. 检查.env文件格式 #

• 确保所有环境变量都是KEY=VALUE的标准格式，绝对不能出现true=xxx、false=xxx这种把布尔值当变量名的情况，也别留多余空格或未闭合的引号。
• 牢记Next.js 13+的规则：客户端要用的变量必须带NEXT_PUBLIC_前缀，非客户端变量别在客户端组件里直接引用。

2. 找代码里的非法赋值语句 #

这个错误本质是代码里出现了“把布尔值放在赋值号左边”的写法，比如process.env.NEXT_PUBLIC_XXX = true;这种完全错误的代码。

• 用全局搜索找项目里所有赋值语句，定位到左侧是布尔字面量的错误代码——不管是你自己写的还是依赖包里面的。

3. 排查依赖与SWC的兼容性 #

Next.js 14默认用SWC编译，有些旧依赖可能和它不兼容。试试临时禁用SWC换Babel：
在next.config.js里加这段配置：

module.exports = {
  swcMinify: false,
}

如果禁用后错误没了，那就是SWC兼容性问题，要么给依赖包升级到兼容Next.js 14的版本，要么给包维护者提issue。

4. 彻底清理缓存再试 #

除了你已经做的删node_modules、.next这些，再加两步：

• 清npm/yarn全局缓存：npm cache clean --force 或者 yarn cache clean
• 重新执行构建：npm run build，看能不能输出具体的错误文件和行号，方便定位。

5. 检查app目录和中间件的环境变量用法 #

• app目录的服务器组件可以直接用process.env拿变量，但客户端组件必须用带NEXT_PUBLIC_前缀的。
• 中间件里用环境变量也要确保格式正确，别写非法赋值。

如果以上都没用，建议建个空的Next.js 14项目，一点点迁移你的代码和依赖，逐步排查到底是哪个文件或依赖搞出来的问题。

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