环境变量配置源

环境变量是一种常用的配置方式，特别适合容器化部署和 CI/CD 环境。

核心包支持

环境变量配置源包含在核心包中，无需额外安装：

dotnet add package Apq.Cfg

基本用法

读取系统环境变量

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddEnvironmentVariables(level: 1, prefix: "APP_")
    .Build();

带前缀过滤

// 只读取以 MYAPP_ 开头的环境变量
var cfg = new CfgBuilder()
    .AddEnvironmentVariables(level: 1, prefix: "MYAPP_")
    .Build();

// 环境变量 MYAPP_DATABASE__HOST 映射为 Database:Host
var host = cfg.Get("Database:Host");

.env 文件支持

Apq.Cfg.Env 包提供 .env 文件支持：

dotnet add package Apq.Cfg.Env

using Apq.Cfg;
using Apq.Cfg.Env;

var cfg = new CfgBuilder()
    .AddEnv(".env", level: 0, writeable: false)
    .AddEnv(".env.local", level: 1, writeable: false, optional: true)
    .Build();

.env 文件格式

# 这是注释
APP_NAME=MyApp
APP_DEBUG=true

# 数据库配置（使用 __ 表示嵌套）
DATABASE__HOST=localhost
DATABASE__PORT=5432
DATABASE__NAME=mydb

# 支持引号包裹的值
MESSAGE="Hello, World!"
MULTILINE="Line1\nLine2"

# 支持单引号（不处理转义）
RAW_VALUE='Hello\nWorld'

# 支持 export 前缀
export API_KEY=secret123

键路径映射

环境变量使用双下划线 __ 来表示配置层级：

环境变量	配置键
APP_NAME	APP_NAME
DATABASE__HOST	DATABASE:HOST
DATABASE__CONNECTION__STRING	DATABASE:CONNECTION:STRING

带前缀的映射

当使用 prefix 参数时，前缀会被移除：

环境变量	前缀	配置键
MYAPP_NAME	MYAPP_	NAME
MYAPP_DATABASE__HOST	MYAPP_	DATABASE:HOST

方法签名

AddEnvironmentVariables

public static CfgBuilder AddEnvironmentVariables(
    this CfgBuilder builder,
    int level,
    string? prefix = null)

AddEnv (.env 文件)

public static CfgBuilder AddEnv(
    this CfgBuilder builder,
    string path,
    int level,
    bool writeable = false,
    bool optional = true,
    bool reloadOnChange = true,
    bool isPrimaryWriter = false)

参数说明

参数	说明
level	配置层级，数值越大优先级越高
prefix	环境变量前缀过滤
path	.env 文件路径
writeable	是否可写
optional	文件不存在时是否忽略
reloadOnChange	文件变更时是否自动重载

典型用法

开发环境

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddJson("config.Development.json", level: 1, writeable: false, optional: true)
    .AddEnv(".env", level: 2, writeable: false, optional: true)
    .AddEnv(".env.local", level: 3, writeable: false, optional: true)
    .AddEnvironmentVariables(level: 4, prefix: "APP_")
    .Build();

Docker 部署

# Dockerfile
ENV APP_DATABASE__HOST=db
ENV APP_DATABASE__PORT=5432
ENV APP_REDIS__HOST=redis

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddEnvironmentVariables(level: 1, prefix: "APP_")
    .Build();

Kubernetes 部署

# ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_DATABASE__HOST: "postgres-service"
  APP_DATABASE__PORT: "5432"

# Deployment
spec:
  containers:
  - name: app
    envFrom:
    - configMapRef:
        name: app-config

.env 文件特性

特性	支持
注释（# 开头）	✅
双引号包裹的值	✅
单引号包裹的值	✅
export 前缀	✅
嵌套配置（__）	✅
文件变更自动重载	✅
可写配置源	✅
转义字符（双引号内）	✅

最佳实践

1. 敏感信息使用环境变量

// 不要在配置文件中存储敏感信息
// 使用环境变量传递
var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddEnvironmentVariables(level: 1, prefix: "APP_")
    .Build();

// 敏感信息通过环境变量注入
// APP_DATABASE__PASSWORD=secret

2. .env 文件不提交到版本控制

# .gitignore
.env
.env.local
.env.*.local

3. 提供 .env.example 模板

# .env.example
APP_NAME=MyApp
DATABASE__HOST=localhost
DATABASE__PORT=5432
DATABASE__PASSWORD=your-password-here

下一步

• Consul - Consul 配置中心
• Redis - Redis 配置源