环境变量管理

环境变量的核心不是“怎么声明”，而是怎么分层、怎么隔离、怎么避免泄露。很多部署问题和本地能跑线上不能跑，本质上都和环境变量管理混乱有关。

如果你是在重装 / 新装系统后恢复整机环境，请先看 Windows 重装部署顺序指南。整机恢复时，环境变量不是最后补，而是要在安装 scoop、mise、语言运行时之前先定好的底层约束。这一页只讲变量管理本身，不重新定义整机顺序。

推荐管理原则

• 本地值、本地覆盖、生产值分开
• 把变量名文档化，而不是只靠口口相传
• 客户端可见变量和服务端私密变量严格区分
• 密钥永远不要写死进源码

.env 文件

项目根目录创建 .env：

DATABASE_URL=postgres://user:pass@localhost:5432/mydb
API_KEY=sk-xxxxxxxxxxxx
NODE_ENV=development
PORT=3000

务必将 .env 加入 .gitignore。

.env 文件优先级（常见约定）

.env.local          # 本地覆盖，不提交
.env.development    # 开发环境
.env.production     # 生产环境
.env                # 默认，所有环境

.env.example

提交一个示例文件供团队参考：

DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your-api-key-here

Node.js

dotenv

pnpm add dotenv

import "dotenv/config";
console.log(process.env.API_KEY);

Vite / Nuxt

Vite 和 Nuxt 原生支持 .env 文件：

# 客户端可见（Vite）
VITE_API_URL=https://api.example.com

# 客户端可见（Nuxt）
NUXT_PUBLIC_API_URL=https://api.example.com

# 仅服务端（Nuxt）
NUXT_API_SECRET=secret

// Vite
const apiUrl = import.meta.env.VITE_API_URL;

// Nuxt
const config = useRuntimeConfig();
config.public.apiUrl; // 客户端
config.apiSecret; // 仅服务端

Python

pip install python-dotenv

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('API_KEY')

Windows 环境变量

# 查看
$env:PATH
[Environment]::GetEnvironmentVariable("PATH", "User")

# 临时设置（当前会话）
$env:NODE_ENV = "production"

# 永久设置（用户级）
[Environment]::SetEnvironmentVariable("MY_VAR", "value", "User")

# 永久设置（系统级，需管理员）
[Environment]::SetEnvironmentVariable("MY_VAR", "value", "Machine")

# 删除
[Environment]::SetEnvironmentVariable("MY_VAR", $null, "User")

GUI 方式：设置 → 系统 → 关于 → 高级系统设置 → 环境变量

重装场景下优先确认的变量

如果你是在按 /setup 恢复一台 Windows 开发机，建议优先把这些变量先写好：

• WORKSPACE_ROOT
• CACHE_ROOT
• SCOOP
• SCOOP_GLOBAL
• MISE_DATA_DIR
• MISE_CONFIG_DIR
• UV_CACHE_DIR
• BUN_INSTALL

Linux / macOS

# 临时设置
export API_KEY=xxx

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export API_KEY=xxx' >> ~/.bashrc
source ~/.bashrc

# 查看
echo $API_KEY
env | grep API
printenv API_KEY

Docker

# docker-compose.yml
services:
  app:
    env_file:
      - .env
    environment:
      - NODE_ENV=production
      - EXTRA_VAR=value

# docker run
docker run --env-file .env -e NODE_ENV=production my-app

安全实践

• 永远不要将密钥提交到 Git
• 使用 .env.example 记录需要的变量名
• 生产环境使用平台的 Secrets 管理（Vercel、Cloudflare、GitHub Secrets）
• 定期轮换 API 密钥
• 使用 git-secrets 或 gitleaks 扫描泄露

# 安装 gitleaks
scoop install gitleaks

# 扫描仓库
gitleaks detect

参考链接

推荐检查清单

• 仓库里有 .env.example
• .env、.env.local 已被忽略
• 生产变量已在平台 Secret / Variables 中配置
• 客户端变量前缀符合框架约定
• 密钥轮换流程有记录

常见问题

本地能跑，部署后报缺少变量

最常见原因就是本地 .env 生效了，但云平台里没有配对应变量。

为什么变量在客户端暴露了

通常是用了错误前缀，或者把本该服务端读取的变量放进了公共运行时配置。

能不能把 .env 加密后提交

可以有更高级的方案，但对大多数项目来说，先把 .env.example、Secrets 平台和最小暴露原则做好，收益更直接。

• dotenv — Node.js
• python-dotenv — Python
• Vite 环境变量 — 文档
• gitleaks — 密钥泄露检测
• 本地运行与部署 — 结合当前项目实际开发和构建流程一起看