环境变量管理 #

环境变量概述 #

环境变量用于存储配置信息和敏感数据：

text

┌─────────────────────────────────────────┐
│        环境变量使用场景                  │
├─────────────────────────────────────────┤
│  API 密钥     →  第三方服务认证          │
│  数据库连接   →  数据库访问凭证          │
│  功能开关     →  控制功能启用/禁用        │
│  环境标识     →  区分开发/生产环境        │
└─────────────────────────────────────────┘

环境类型 #

Vercel 支持三种环境：

环境	说明	用途
Production	生产环境	正式部署
Preview	预览环境	PR 预览
Development	开发环境	本地开发

text

┌─────────────────────────────────────────┐
│                                         │
│   Production ←──────── Preview          │
│       ↑                    ↑            │
│       │                    │            │
│   main 分支            PR 分支          │
│                                         │
│   Development ←────── 本地开发          │
│                                         │
└─────────────────────────────────────────┘

添加环境变量 #

通过 Dashboard #

text

Project Settings → Environment Variables

text

┌─────────────────────────────────────────┐
│  Add Environment Variable               │
├─────────────────────────────────────────┤
│  Key                                    │
│  ┌─────────────────────────────────┐    │
│  │ DATABASE_URL                    │    │
│  └─────────────────────────────────┘    │
│                                         │
│  Value                                  │
│  ┌─────────────────────────────────┐    │
│  │ postgresql://user:pass@host/db  │    │
│  └─────────────────────────────────┘    │
│                                         │
│  Environment                            │
│  ☑ Production  ☑ Preview  ☑ Development │
│                                         │
│  [Add]                                  │
└─────────────────────────────────────────┘

通过 CLI #

bash

vercel env add DATABASE_URL

text

? What's the value of DATABASE_URL? postgresql://...
? Add DATABASE_URL to which Environments?
  ☑ Production
  ☑ Preview
  ☑ Development

批量导入 #

bash

vercel env pull .env.local

从 .env 文件导入：

bash

vercel env add < .env

在代码中使用 #

Next.js #

javascript

const dbUrl = process.env.DATABASE_URL
const apiKey = process.env.NEXT_PUBLIC_API_KEY

命名规则：

前缀	用途	可见性
无前缀	服务端变量	仅服务端
`NEXT_PUBLIC_`	客户端变量	服务端 + 客户端

示例：

javascript

const secretKey = process.env.SECRET_KEY
const publicApiUrl = process.env.NEXT_PUBLIC_API_URL

Vite #

javascript

const apiKey = import.meta.env.VITE_API_KEY

命名规则：

前缀	用途
`VITE_`	客户端变量

Nuxt.js #

javascript

const config = useRuntimeConfig()
const apiKey = config.apiKey

nuxt.config.ts：

typescript

export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: process.env.NUXT_API_KEY,
    public: {
      apiUrl: process.env.NUXT_PUBLIC_API_URL
    }
  }
})

本地开发 #

创建 .env 文件 #

bash

touch .env.local

.env 文件格式 #

bash

DATABASE_URL=postgresql://user:pass@host/db
API_KEY=your-api-key-here
NEXT_PUBLIC_API_URL=https://api.example.com

拉取远程环境变量 #

bash

vercel env pull .env.local

text

Downloading `Development` Environment Variables for Project my-project
✓ Downloaded .env.local

.env 文件优先级 #

text

.env.local        # 本地覆盖（优先级最高）
.env.development  # 开发环境
.env              # 默认值

敏感信息处理 #

安全最佳实践 #

text

┌─────────────────────────────────────────┐
│        安全最佳实践                      │
├─────────────────────────────────────────┤
│  ✓ 使用环境变量存储敏感信息              │
│  ✓ 不要将 .env 文件提交到 Git           │
│  ✓ 使用不同的密钥区分环境               │
│  ✓ 定期轮换密钥                         │
│  ✓ 限制密钥权限                         │
└─────────────────────────────────────────┘

.gitignore 配置 #

gitignore

.env
.env.local
.env.*.local

加密环境变量 #

对于高度敏感的数据，使用加密存储：

bash

vercel env add ENCRYPTED_SECRET --encrypted

环境变量管理 #

查看环境变量 #

bash

vercel env ls

text

Environment Variables:
  DATABASE_URL        Production, Preview, Development
  API_KEY             Production
  NEXT_PUBLIC_API_URL Production, Preview, Development

修改环境变量 #

bash

vercel env rm DATABASE_URL production
vercel env add DATABASE_URL

删除环境变量 #

bash

vercel env rm DATABASE_URL

text

? Remove DATABASE_URL in Production? [y/N] y
? Remove DATABASE_URL in Preview? [y/N] y
? Remove DATABASE_URL in Development? [y/N] y

多环境配置 #

不同环境不同值 #

bash

vercel env add API_URL production
vercel env add API_URL preview
vercel env add API_URL development

text

Production:  API_URL = https://api.production.com
Preview:     API_URL = https://api.staging.com
Development: API_URL = http://localhost:3001

环境变量继承 #

text

Development (基础值)
    │
    ├── Preview (继承 Development，可覆盖)
    │
    └── Production (独立配置)

系统环境变量 #

Vercel 自动注入以下系统变量：

变量	说明
`VERCEL`	是否在 Vercel 环境
`VERCEL_ENV`	当前环境
`VERCEL_URL`	部署 URL
`VERCEL_REGION`	部署区域
`VERCEL_GIT_PROVIDER`	Git 提供商
`VERCEL_GIT_REPO_SLUG`	仓库名称
`VERCEL_GIT_COMMIT_SHA`	提交 SHA
`VERCEL_GIT_COMMIT_MESSAGE`	提交信息

使用示例：

javascript

if (process.env.VERCEL === '1') {
  console.log('Running on Vercel')
}

const deployUrl = process.env.VERCEL_URL
const commitSha = process.env.VERCEL_GIT_COMMIT_SHA

构建时环境变量 #

在构建中使用 #

json

{
  "buildCommand": "NEXT_PUBLIC_BUILD_ID=$VERCEL_GIT_COMMIT_SHA next build"
}

Next.js 构建时变量 #

javascript

const nextConfig = {
  env: {
    BUILD_TIME: new Date().toISOString(),
    GIT_COMMIT_SHA: process.env.VERCEL_GIT_COMMIT_SHA,
  },
}

文件系统环境变量 #

加载文件作为变量 #

bash

vercel env add PRIVATE_KEY_FILE

然后粘贴文件内容作为值。

在代码中使用 #

javascript

const privateKey = process.env.PRIVATE_KEY_FILE

团队环境变量 #

团队级别变量 #

text

Team Settings → Environment Variables

团队变量对所有项目可见：

text

┌─────────────────────────────────────────┐
│  Team Environment Variables             │
├─────────────────────────────────────────┤
│  TEAM_API_KEY                           │
│  SHARED_SECRET                          │
└─────────────────────────────────────────┘

项目变量优先级 #

text

项目环境变量 > 团队环境变量 > 系统环境变量

常见问题 #

变量未生效 #

text

检查项：
├── 环境变量名称是否正确
├── 是否添加到正确的环境
├── 是否需要重新部署
├── 是否有正确的命名前缀
└── 是否在正确的位置访问

客户端访问服务端变量 #

javascript

const secret = process.env.SECRET_KEY
console.log(secret)

问题： 客户端无法访问无前缀变量

解决： 使用 NEXT_PUBLIC_ 前缀或通过 API 传递

变量值包含特殊字符 #

bash

SPECIAL_VALUE="value with spaces"
JSON_CONFIG='{"key": "value"}'

下一步 #

掌握环境变量后，接下来学习 CI/CD 集成实现自动化部署流程！