Nuxt.js环境变量 #

一、环境变量概述 #

环境变量用于存储不同环境的配置信息，如 API 地址、密钥等。Nuxt.js 提供了完善的配置管理机制。

1.1 环境变量类型 #

类型 前缀 访问位置 说明
公共变量 NUXT_PUBLIC_ 客户端和服务端 可公开的配置
私有变量 NUXT_ 仅服务端 敏感信息

二、.env文件 #

2.1 创建.env文件 #

.env：

env 
NUXT_PUBLIC_API_BASE=https://api.example.com
NUXT_PUBLIC_SITE_NAME=My Website

NUXT_SECRET_KEY=your-secret-key
NUXT_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

2.2 环境文件 #

text 
.env                # 默认环境
.env.local          # 本地覆盖（不提交）
.env.development    # 开发环境
.env.production     # 生产环境
.env.staging        # 预发布环境

2.3 .gitignore #

gitignore 
.env.local
.env.*.local

三、runtimeConfig #

3.1 配置运行时配置 #

nuxt.config.ts：

typescript 
export default defineNuxtConfig({
  runtimeConfig: {
    secretKey: process.env.NUXT_SECRET_KEY,
    databaseUrl: process.env.NUXT_DATABASE_URL,
    
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api',
      siteName: process.env.NUXT_PUBLIC_SITE_NAME || 'My Site'
    }
  }
})

3.2 访问配置 #

服务端：

typescript 
export default defineEventHandler((event) => {
  const config = useRuntimeConfig()
  
  console.log(config.secretKey)
  console.log(config.databaseUrl)
})

客户端：

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

console.log(config.public.apiBase)
console.log(config.public.siteName)
</script>

3.3 类型定义 #

types/runtimeConfig.d.ts：

typescript 
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    secretKey: string
    databaseUrl: string
    public: {
      apiBase: string
      siteName: string
    }
  }
}

export {}

四、appConfig #

4.1 应用配置 #

app.config.ts：

typescript 
export default defineAppConfig({
  title: 'My App',
  theme: {
    primaryColor: '#3498db',
    darkMode: false
  },
  features: {
    analytics: true,
    notifications: true
  }
})

4.2 访问配置 #

vue 
<script setup lang="ts">
const appConfig = useAppConfig()

console.log(appConfig.title)
console.log(appConfig.theme.primaryColor)
</script>

4.3 运行时更新 #

vue 
<script setup lang="ts">
const appConfig = useAppConfig()

const updateTheme = () => {
  appConfig.theme.darkMode = !appConfig.theme.darkMode
}
</script>

五、配置优先级 #

5.1 优先级顺序 #

  1. 环境变量（最高优先级）
  2. .env 文件
  3. nuxt.config.ts 默认值
  4. 代码中的默认值（最低优先级）

5.2 配置覆盖 #

typescript 
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || 'http://localhost:3001/api'
    }
  }
})

六、敏感信息管理 #

6.1 服务端配置 #

typescript 
export default defineNuxtConfig({
  runtimeConfig: {
    jwtSecret: process.env.NUXT_JWT_SECRET,
    databaseUrl: process.env.NUXT_DATABASE_URL,
    redisUrl: process.env.NUXT_REDIS_URL,
    
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE
    }
  }
})

6.2 验证配置 #

server/middleware/config-check.ts：

typescript 
export default defineEventHandler((event) => {
  const config = useRuntimeConfig()
  
  if (!config.jwtSecret) {
    throw createError({
      statusCode: 500,
      message: 'JWT_SECRET is not configured'
    })
  }
})

6.3 加密配置 #

typescript 
import CryptoJS from 'crypto-js'

export default defineNuxtConfig({
  runtimeConfig: {
    encryptionKey: process.env.NUXT_ENCRYPTION_KEY,
    
    public: {
      encryptedConfig: process.env.NUXT_PUBLIC_ENCRYPTED_CONFIG
    }
  }
})

七、多环境配置 #

7.1 环境特定配置 #

nuxt.config.ts：

typescript 
const isDev = process.env.NODE_ENV === 'development'

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: isDev 
        ? 'http://localhost:3001/api' 
        : process.env.NUXT_PUBLIC_API_BASE
    }
  }
})

7.2 环境文件管理 #

text 
config/
├── .env.development
├── .env.staging
└── .env.production

部署时指定环境：

bash 
cp config/.env.production .env

八、CI/CD集成 #

8.1 GitHub Actions #

yaml 
env:
  NUXT_PUBLIC_API_BASE: ${{ secrets.API_BASE }}
  NUXT_SECRET_KEY: ${{ secrets.SECRET_KEY }}

steps:
  - name: Build
    run: npm run build

8.2 Vercel #

在 Vercel Dashboard 中设置环境变量。

8.3 Docker #

bash 
docker run \
  -e NUXT_PUBLIC_API_BASE=https://api.example.com \
  -e NUXT_SECRET_KEY=your-secret-key \
  my-nuxt-app

九、配置验证 #

9.1 Zod验证 #

server/utils/validateConfig.ts：

typescript 
import { z } from 'zod'

const configSchema = z.object({
  jwtSecret: z.string().min(32),
  databaseUrl: z.string().url(),
  public: z.object({
    apiBase: z.string().url()
  })
})

export const validateConfig = () => {
  const config = useRuntimeConfig()
  
  try {
    configSchema.parse(config)
  } catch (error) {
    console.error('Invalid configuration:', error)
    process.exit(1)
  }
}

9.2 启动验证 #

server/plugins/config.ts：

typescript 
export default defineNuxtPlugin(() => {
  if (import.meta.server) {
    validateConfig()
  }
})

十、最佳实践 #

10.1 命名规范 #

env 
NUXT_PUBLIC_API_BASE
NUXT_PUBLIC_SITE_NAME
NUXT_SECRET_KEY
NUXT_DATABASE_URL

10.2 默认值 #

typescript 
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api',
      siteName: process.env.NUXT_PUBLIC_SITE_NAME || 'My Site'
    }
  }
})

10.3 文档化 #

typescript 
export default defineNuxtConfig({
  runtimeConfig: {
    jwtSecret: {
      env: 'NUXT_JWT_SECRET',
      description: 'JWT signing secret (min 32 characters)',
      required: true
    }
  }
})

10.4 安全检查 #

typescript 
const checkSecurity = () => {
  const config = useRuntimeConfig()
  
  if (process.env.NODE_ENV === 'production') {
    if (config.jwtSecret === 'development-secret') {
      throw new Error('Using development secret in production!')
    }
  }
}

十一、完整示例 #

11.1 配置文件 #

nuxt.config.ts：

typescript 
export default defineNuxtConfig({
  runtimeConfig: {
    jwtSecret: process.env.NUXT_JWT_SECRET,
    databaseUrl: process.env.NUXT_DATABASE_URL,
    redisUrl: process.env.NUXT_REDIS_URL,
    smtp: {
      host: process.env.NUXT_SMTP_HOST,
      port: parseInt(process.env.NUXT_SMTP_PORT || '587'),
      user: process.env.NUXT_SMTP_USER,
      pass: process.env.NUXT_SMTP_PASS
    },
    
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api',
      siteName: process.env.NUXT_PUBLIC_SITE_NAME || 'My App',
      siteUrl: process.env.NUXT_PUBLIC_SITE_URL || 'http://localhost:3000',
      features: {
        analytics: process.env.NUXT_PUBLIC_FEATURES_ANALYTICS === 'true',
        notifications: process.env.NUXT_PUBLIC_FEATURES_NOTIFICATIONS === 'true'
      }
    }
  }
})

11.2 环境文件 #

.env.example：

env 
NUXT_PUBLIC_API_BASE=https://api.example.com
NUXT_PUBLIC_SITE_NAME=My App
NUXT_PUBLIC_SITE_URL=https://example.com
NUXT_PUBLIC_FEATURES_ANALYTICS=true
NUXT_PUBLIC_FEATURES_NOTIFICATIONS=true

NUXT_JWT_SECRET=your-secure-jwt-secret-min-32-characters
NUXT_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
NUXT_REDIS_URL=redis://localhost:6379
NUXT_SMTP_HOST=smtp.example.com
NUXT_SMTP_PORT=587
NUXT_SMTP_USER=noreply@example.com
NUXT_SMTP_PASS=your-smtp-password

十二、总结 #

本章介绍了 Nuxt.js 环境变量：

  • 环境变量类型和命名
  • .env 文件管理
  • runtimeConfig 配置
  • appConfig 应用配置
  • 敏感信息管理
  • 多环境配置
  • CI/CD 集成
  • 配置验证

合理管理环境变量是应用安全的基础，下一章我们将学习性能优化。

最后更新：2026-03-28