Nuxt环境变量：运行时配置与环境区分管理

2026-02-05 05:48:48作者：韦蓉瑛

环境变量基础配置

.env文件定义

在Nuxt项目根目录创建.env文件存储环境变量，格式为KEY=VALUE，支持多行定义。系统自动加载.env文件，无需额外配置。

# .env
API_BASE_URL=https://api.example.com
DEBUG_MODE=true

环境变量分类

Nuxt将环境变量分为两类：

私有变量：仅服务器端可访问，以NUXT_为前缀
公共变量：客户端和服务器端均可访问，以NUXT_PUBLIC_为前缀

# 私有变量（仅服务器端）
NUXT_API_KEY=secret-key-123

# 公共变量（客户端可访问）
NUXT_PUBLIC_APP_VERSION=1.0.0

运行时配置

nuxt.config.ts配置

在nuxt.config.ts中通过runtimeConfig选项定义运行时配置，支持服务器端和客户端配置分离：

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 服务器端配置（私有）
    apiKey: '', // 会被.env中的NUXT_API_KEY覆盖
    
    // 客户端配置（公共）
    public: {
      apiBase: '', // 会被.env中的NUXT_PUBLIC_API_BASE覆盖
      appName: 'My Nuxt App'
    }
  }
})

使用useRuntimeConfig访问

通过useRuntimeConfig组合式API在组件和组合式函数中访问配置：

<!-- 页面组件中使用 -->
<script setup lang="ts">
const config = useRuntimeConfig()

// 服务器端可访问私有配置
if (process.server) {
  console.log('API Key:', config.apiKey)
}

// 客户端和服务器端均可访问公共配置
console.log('API Base URL:', config.public.apiBase)
console.log('App Name:', config.public.appName)
</script>

环境区分策略

多环境文件

创建不同环境的.env文件，命名格式为.env.<environment>：

.env            # 基础环境变量，所有环境共享
.env.development # 开发环境
.env.production  # 生产环境
.env.test        # 测试环境

示例.env.development：

# .env.development
NUXT_API_KEY=dev-secret-key
NUXT_PUBLIC_API_BASE=http://localhost:3001/api

启动命令指定环境

通过--dotenv参数指定环境文件，或使用NODE_ENV环境变量：

# 使用开发环境
nuxi dev --dotenv .env.development

# 使用生产环境
NODE_ENV=production nuxi build
nuxi preview --dotenv .env.production

环境判断逻辑

在代码中通过process.env.NODE_ENV判断当前环境：

// 插件或组合式函数中
if (process.env.NODE_ENV === 'development') {
  console.log('开发环境模式')
} else if (process.env.NODE_ENV === 'production') {
  console.log('生产环境模式')
}

实际应用示例

API请求封装

创建api客户端，使用环境变量配置基础URL：

// composables/useApi.ts
export const useApi = () => {
  const config = useRuntimeConfig()
  
  return $fetch.create({
    baseURL: config.public.apiBase,
    headers: {
      'Content-Type': 'application/json',
      ...(process.server && {
        'X-API-Key': config.apiKey
      })
    }
  })
}

在组件中使用：

<script setup lang="ts">
const api = useApi()

const fetchData = async () => {
  try {
    const data = await api('/users')
    console.log('Data:', data)
  } catch (error) {
    console.error('API Error:', error)
  }
}

fetchData()
</script>

条件渲染

根据环境变量在客户端进行条件渲染：

<template>
  <div>
    <h1>{{ config.public.appName }}</h1>
    
    <!-- 仅开发环境显示调试面板 -->
    <DebugPanel v-if="config.public.debugMode" />
    
    <!-- 显示版本信息 -->
    <p>Version: {{ config.public.appVersion }}</p>
  </div>
</template>

<script setup lang="ts">
const config = useRuntimeConfig()
</script>

部署注意事项

服务器环境变量

部署时可通过服务器环境变量覆盖.env文件配置，优先级：服务器环境变量 > .env文件 > nuxt.config.ts默认值。

例如在Netlify中设置环境变量：

在Netlify控制台的"Build & Deploy" > "Environment"中添加
变量名保持与本地.env一致，如NUXT_API_KEY、NUXT_PUBLIC_API_BASE

Docker部署示例

Dockerfile中设置环境变量：

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

# 设置环境变量
ENV NODE_ENV=production
ENV NUXT_API_KEY=${API_KEY}
ENV NUXT_PUBLIC_API_BASE=${API_BASE}

EXPOSE 3000

CMD ["npm", "start"]

启动容器时传入环境变量：

docker run -e API_KEY=prod-key -e API_BASE=https://api.prod.com -p 3000:3000 my-nuxt-app

最佳实践

安全存储敏感信息

敏感信息如API密钥、数据库密码等必须使用私有变量（NUXT_前缀）
避免在客户端代码中直接使用敏感信息
生产环境中不要提交.env文件到代码仓库

版本控制策略

在.gitignore中排除.env文件，但可提交.env.example作为模板：

# .gitignore
.env
.env.local
.env.*.local

# 可提交的模板文件
!.env.example

.env.example示例：

# .env.example
NUXT_API_KEY=your_api_key_here
NUXT_PUBLIC_API_BASE=https://api.example.com

类型安全配置

为运行时配置添加TypeScript类型定义，在types/nuxt.d.ts中扩展：

// types/nuxt.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiKey: string
    public: {
      apiBase: string
      appName: string
      appVersion: string
    }
  }
}

export {}