Nuxt环境变量：运行时配置与环境区分管理
【免费下载链接】nuxt The Intuitive Vue Framework. 
项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt
环境变量基础配置
.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 {}
通过以上配置，Nuxt环境变量管理可实现开发效率与安全性的平衡，支持多环境无缝切换，满足不同部署场景需求。合理使用环境变量和运行时配置，可显著提升项目的可维护性和扩展性。
【免费下载链接】nuxt The Intuitive Vue Framework. 项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
