Nuxt 应用中两种设置环境变量的方式
在实际项目中，API 地址、密钥等配置信息通常通过环境变量管理。Nuxt 提供了两种主要的环境变量配置方式：.env 文件和 nuxt.config.ts 中的 runtimeConfig。合理使用这两种方式可以让项目在不同环境间灵活切换。
方式一：.env 文件
在项目根目录创建 .env 文件，通过键值对设置环境变量：
# .env
BASE_URL=http://localhost:3000
NUXT_PUBLIC_API_BASE=https://api.example.com
ini
Nuxt 会自动读取 .env 文件中的变量，并通过 process.env 暴露给应用。
方式二：nuxt.config.ts 中的 runtimeConfig
在 Nuxt 配置文件中通过 runtimeConfig 定义运行时配置：
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// 私有配置 - 仅在服务端可用
apiSecret: '123',
// 公共配置 - 同时暴露给客户端
public: {
apiBase: '/api',
baseUrl: '',
},
},
})
typescript
runtimeConfig 的环境变量可通过 .env 文件覆盖。覆盖规则为：
- 私有变量：使用
NUXT_前缀（如NUXT_API_SECRET） - 公共变量：使用
NUXT_PUBLIC_前缀（如NUXT_PUBLIC_API_BASE）
# .env - 覆盖 runtimeConfig 默认值
NUXT_API_SECRET=production_secret
NUXT_PUBLIC_API_BASE=https://api.production.com
ini
在组件中使用环境变量
根据配置方式的不同，读取环境变量的方法也不同。
读取 runtimeConfig
使用 useRuntimeConfig() 组合式函数获取配置：
<script setup>
const config = useRuntimeConfig()
// 读取公共配置
const apiBase = config.public.apiBase
// 在服务端可以读取私有配置
// const secret = config.apiSecret
</script>
vue
读取 .env 中的自定义变量
对于通过 .env 文件直接设置的变量（未在 runtimeConfig 中声明的），通过 process.env 读取：
<script setup>
const baseUrl = process.env.BASE_URL || 'http://localhost:3000'
console.log('Base URL:', baseUrl)
</script>
vue
建议始终为 process.env 的读取设置默认值，防止变量未定义导致运行时错误。
实战示例：优化 API 基础路径
以下是优化 Nuxt 项目中 API 基础路径的完整流程：
步骤 1：在 .env 中设置变量
# .env
NUXT_PUBLIC_API_BASE=http://localhost:3000
ini
步骤 2：在 nuxt.config.ts 中声明 runtimeConfig
export default defineNuxtConfig({
runtimeConfig: {
public: {
apiBase: '',
},
},
})
typescript
步骤 3：在组件中使用
<script setup>
const { apiBase } = useRuntimeConfig().public
const { data } = await useFetch(`${apiBase}/api/home`)
</script>
vue
步骤 4：修改完成后重启开发服务器
# 修改 .env 或 nuxt.config.ts 后需要重启
pnpm dev
bash
最佳实践
| 实践 | 说明 |
|---|---|
| 敏感信息用私有配置 | API 密钥、数据库连接串等放在 runtimeConfig 的私有层 |
| 公共配置用 public | API 地址、站点标题等客户端需要的变量放在 public 层 |
| 提供默认值 | 所有配置都应提供合理的默认值 |
| 环境区分 | 通过 .env.development、.env.production 区分不同环境 |
| 重启生效 | 修改 .env 后必须重启开发服务器 |
注意：
runtimeConfig是 Nuxt 推荐的环境变量管理方式，它在类型安全、服务端/客户端隔离等方面优于直接使用process.env。
↑