环境变量管理 #

什么是环境变量？ #

环境变量是在运行时传递给应用程序的配置值，常用于：

text

┌─────────────────────────────────────────────────────┐
│                   环境变量用途                       │
├─────────────────────────────────────────────────────┤
│ • API 密钥和令牌                                    │
│ • 数据库连接字符串                                  │
│ • 第三方服务配置                                    │
│ • 环境区分（开发/测试/生产）                        │
│ • 功能开关                                          │
└─────────────────────────────────────────────────────┘

配置方式 #

方式一：控制台配置 #

text

Site settings → Build & deploy → Environment

步骤：

进入站点设置
找到 Build & deploy → Environment
点击 “Add a variable”
输入 Key 和 Value
点击 Save

方式二：netlify.toml 配置 #

toml

[build.environment]
  NODE_VERSION = "18"
  NPM_VERSION = "9"
  MY_API_KEY = "your-api-key"

方式三：CLI 配置 #

bash

# 设置环境变量
netlify env:set API_KEY "your-api-key"

# 导入 .env 文件
netlify env:import .env

# 列出所有环境变量
netlify env:list

环境变量优先级 #

text

优先级从高到低：

1. 控制台设置
      ↓
2. netlify.toml 中的 context 特定配置
      ↓
3. netlify.toml 中的 [build.environment]
      ↓
4. Netlify 默认值

多环境管理 #

按部署上下文配置 #

toml

# 全局环境变量
[build.environment]
  NODE_VERSION = "18"

# 生产环境
[context.production.environment]
  API_URL = "https://api.example.com"
  NODE_ENV = "production"

# 预览环境（Deploy Preview）
[context.deploy-preview.environment]
  API_URL = "https://staging-api.example.com"
  NODE_ENV = "preview"

# 分支部署
[context.branch-deploy.environment]
  API_URL = "https://dev-api.example.com"
  NODE_ENV = "development"

# 特定分支
[context.staging.environment]
  API_URL = "https://staging-api.example.com"
  NODE_ENV = "staging"

部署上下文类型 #

上下文	说明
production	主分支部署
deploy-preview	PR 预览部署
branch-deploy	其他分支部署
staging	名为 staging 的分支

敏感信息处理 #

安全原则 #

text

┌─────────────────────────────────────────────────────┐
│              敏感信息处理最佳实践                    │
├─────────────────────────────────────────────────────┤
│ ✅ 使用控制台设置敏感变量                           │
│ ✅ 不要将密钥提交到 Git                            │
│ ✅ 使用 .env 文件并在 .gitignore 中忽略            │
│ ✅ 定期轮换密钥                                    │
│ ❌ 不要在 netlify.toml 中写密钥                    │
│ ❌ 不要在前端代码中暴露服务端密钥                  │
└─────────────────────────────────────────────────────┘

.env 文件示例 #

bash

# .env.local（添加到 .gitignore）
API_KEY=sk_live_xxxxx
DATABASE_URL=postgres://user:pass@host:5432/db
STRIPE_SECRET_KEY=sk_live_xxxxx

导入到 Netlify #

bash

netlify env:import .env.local

前端环境变量 #

React (CRA) #

bash

# 必须以 REACT_APP_ 开头
REACT_APP_API_URL=https://api.example.com
REACT_APP_API_KEY=your-key

使用：

javascript

const apiUrl = process.env.REACT_APP_API_URL;
const apiKey = process.env.REACT_APP_API_KEY;

Vite #

bash

# 必须以 VITE_ 开头
VITE_API_URL=https://api.example.com
VITE_API_KEY=your-key

使用：

javascript

const apiUrl = import.meta.env.VITE_API_URL;
const apiKey = import.meta.env.VITE_API_KEY;

Next.js #

bash

# 客户端变量（以 NEXT_PUBLIC_ 开头）
NEXT_PUBLIC_API_URL=https://api.example.com

# 服务端变量（仅服务端可访问）
DATABASE_URL=postgres://...

使用：

javascript

// 客户端
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// 服务端（API Routes, getServerSideProps）
const dbUrl = process.env.DATABASE_URL;

Vue #

bash

# 必须以 VUE_APP_ 开头
VUE_APP_API_URL=https://api.example.com

使用：

javascript

const apiUrl = process.env.VUE_APP_API_URL;

Serverless Functions 环境变量 #

访问环境变量 #

javascript

// netlify/functions/api.js
exports.handler = async (event, context) => {
  const apiKey = process.env.API_KEY;
  const dbUrl = process.env.DATABASE_URL;
  
  return {
    statusCode: 200,
    body: JSON.stringify({
      message: 'OK',
      hasKey: !!apiKey
    })
  }
}

函数专用变量 #

toml

[functions]
  directory = "netlify/functions"

[functions."my-function"]
  [functions."my-function".environment]
    FUNCTION_SPECIFIC_VAR = "value"

变量替换 #

构建时替换 #

Netlify 在构建时会替换以下内置变量：

变量	说明
`NETLIFY`	始终为 `true`
`NETLIFY_DEV`	本地开发时为 `true`
`SITE_NAME`	站点名称
`SITE_ID`	站点 ID
`DEPLOY_ID`	部署 ID
`DEPLOY_URL`	部署 URL
`DEPLOY_PRIME_URL`	主 URL
`CONTEXT`	部署上下文
`BRANCH`	分支名称
`COMMIT_REF`	提交 SHA
`REPOSITORY_URL`	仓库 URL

使用示例 #

javascript

const deployUrl = process.env.DEPLOY_URL;
const branch = process.env.BRANCH;
const context = process.env.CONTEXT;

console.log(`Deployed from ${branch} to ${deployUrl}`);

本地开发 #

.env 文件 #

bash

# .env.development
API_URL=http://localhost:3000/api
NODE_ENV=development

netlify dev #

bash

netlify dev

自动加载：

.env
.env.local
.env.development
Netlify 控制台中的环境变量

链接站点 #

bash

netlify link

链接后，netlify dev 会从远程站点拉取环境变量。

环境变量管理 CLI #

查看变量 #

bash

netlify env:list

设置变量 #

bash

netlify env:set VARIABLE_NAME "value"

获取变量值 #

bash

netlify env:get VARIABLE_NAME

删除变量 #

bash

netlify env:unset VARIABLE_NAME

导入变量 #

bash

netlify env:import .env

导出变量 #

bash

netlify env:export > .env

常见问题 #

Q: 变量修改后需要重新部署吗？ #

是的，环境变量在构建时注入，修改后需要触发重新部署。

Q: 如何在前端隐藏 API 密钥？ #

前端代码会暴露给用户，无法真正隐藏。解决方案：

使用 Serverless Functions 作为代理
使用后端服务
限制 API 密钥的使用范围和域名

Q: 如何区分开发和生产环境？ #

javascript

const isProduction = process.env.CONTEXT === 'production';
const isPreview = process.env.CONTEXT === 'deploy-preview';
const isDev = process.env.NETLIFY_DEV === 'true';

Q: 环境变量长度有限制吗？ #

单个变量值最大 10KB，总变量大小最大 100KB。

最佳实践 #

1. 命名规范 #

bash

# 好的命名
API_URL=https://api.example.com
DATABASE_URL=postgres://...
STRIPE_SECRET_KEY=sk_live_xxx

# 不好的命名
url=https://api.example.com
key=xxx

2. 分组管理 #

bash

# API 相关
API_BASE_URL=https://api.example.com
API_KEY=xxx
API_TIMEOUT=30000

# 数据库相关
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb

3. 使用 .env.example #

bash

# .env.example（提交到 Git）
API_URL=
API_KEY=
DATABASE_URL=

4. 环境隔离 #

toml

[context.production.environment]
  API_URL = "https://api.example.com"

[context.deploy-preview.environment]
  API_URL = "https://staging-api.example.com"

下一步 #

掌握了环境变量配置后，继续学习构建钩子了解如何自动化触发部署！