NUXT环境变量服务端可用但客户端不生效问题求助

问题原因分析 #

你的问题核心是Nuxt的客户端runtimeConfig缓存、环境变量加载时机不匹配，或者开发/构建阶段的配置缓存导致环境变量未正确覆盖硬编码值。

具体解决方案 #

1. 确保环境变量在启动/构建时正确传入 #

• 开发模式下，必须在启动命令前传入环境变量，Nuxt启动时会一次性读取并注入客户端配置：

  NUXT_PUBLIC_API_URL=http://local-url.com/api npm run dev
  

• 或者将环境变量写入根目录的.env文件（Nuxt 3 自带支持，无需额外插件）：

  NUXT_PUBLIC_API_URL=http://local-url.com/api
  

  注意：修改.env文件后需要重启Nuxt服务，否则不会重新加载。

2. 清除Nuxt缓存 #

Nuxt会缓存构建产物和配置，旧的硬编码值可能被缓存导致环境变量不生效，执行以下操作：

• 运行清理命令：

  npx nuxi clean
  

• 或者手动删除项目根目录下的.nuxt、.output和node_modules/.cache目录，然后重新启动项目。

3. 规范客户端调用useRuntimeConfig()的方式 #

确保在组件的setup函数或<script setup>内调用useRuntimeConfig()，不要在组件外部提前执行，否则可能拿到未更新的缓存值：

<script setup>
// 正确写法：在组件setup上下文内调用
const config = useRuntimeConfig()
console.log(config.public.apiUrl)
</script>

4. 生产环境注意事项 #

如果是生产构建，环境变量必须在构建阶段传入，因为生产环境的客户端配置是静态注入到打包产物中的，运行时无法修改：

NUXT_PUBLIC_API_URL=https://prod-url.com/api npm run build

如果需要生产环境动态切换API地址，建议改用服务器端代理，在服务器端读取环境变量后转发请求，避免依赖客户端的public配置。

异常现象解释 #

偶尔刷新/新开标签页生效，是因为浏览器缓存了旧的客户端配置文件（比如nuxt.config.js生成的静态配置片段），或者Nuxt热更新时重新注入了新配置，但首次加载时缓存的旧配置优先加载，导致未生效。

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