Config API

Config 结构体的完整配置选项参考。

结构体定义

Config 使用嵌套结构体组织配置，同时通过 Go 的字段提升保持向后兼容：

type Config struct {
    FileConfig       // 文件加载行为
    ValidationConfig // 键和值验证
    LimitsConfig     // 大小和数量限制
    JSONConfig       // JSON 解析选项
    YAMLConfig       // YAML 解析选项
    ParsingConfig    // 通用解析行为
    ComponentConfig  // 自定义组件和高级选项
}

两种访问方式：

// 旧方式（通过字段提升，仍然有效）
cfg.Filenames = []string{".env"}
cfg.MaxFileSize = 1024

// 新方式（推荐，更清晰）
cfg.FileConfig.Filenames = []string{".env"}
cfg.LimitsConfig.MaxFileSize = 1024

嵌套结构体

// FileConfig 控制文件加载行为
type FileConfig struct {
    Filenames         []string // 要加载的文件列表
    FailOnMissingFile bool     // 文件不存在时是否报错
    OverwriteExisting bool     // 是否覆盖已存在的环境变量
    AutoApply         bool     // 是否自动应用到 os.Environ
}

// ValidationConfig 控制键和值验证
type ValidationConfig struct {
    RequiredKeys   []string       // 必需的键名列表
    AllowedKeys    []string       // 允许的键名白名单
    ForbiddenKeys  []string       // 额外的禁止键列表
    KeyPattern     *regexp.Regexp // 键名匹配模式
    ValidateValues bool           // 是否验证值的安全性
    ValidateUTF8   bool           // 是否验证值为有效 UTF-8
}

// LimitsConfig 控制大小和数量限制
type LimitsConfig struct {
    MaxFileSize       int64 // 单文件最大字节数
    MaxVariables      int   // 每文件最大变量数
    MaxLineLength     int   // 单行最大长度
    MaxKeyLength      int   // 键名最大长度
    MaxValueLength    int   // 值最大长度
    MaxExpansionDepth int   // 变量展开最大深度
}

// JSONConfig 控制 JSON 解析行为
type JSONConfig struct {
    JSONNullAsEmpty    bool // null 转为空字符串
    JSONNumberAsString bool // 数字转为字符串
    JSONBoolAsString   bool // 布尔值转为字符串
    JSONMaxDepth       int  // 最大嵌套深度
}

// YAMLConfig 控制 YAML 解析行为
type YAMLConfig struct {
    YAMLNullAsEmpty    bool // null/~ 转为空字符串
    YAMLNumberAsString bool // 数字转为字符串
    YAMLBoolAsString   bool // 布尔值转为字符串
    YAMLMaxDepth       int  // 最大嵌套深度
}

// ParsingConfig 控制通用解析行为
type ParsingConfig struct {
    AllowExportPrefix bool // 允许 export KEY=value 语法
    AllowYamlSyntax   bool // 允许 YAML 风格值
    ExpandVariables   bool // 是否展开 ${VAR} 引用
}

// ComponentConfig 自定义组件和高级选项
type ComponentConfig struct {
    CustomValidator Validator        // 自定义键/值验证器
    CustomExpander  VariableExpander // 自定义变量展开器
    CustomAuditor   AuditLogger      // 自定义审计日志器
    FileSystem      FileSystem       // 自定义文件系统（用于测试）
    AuditHandler    AuditHandler     // 自定义审计处理器
    AuditEnabled    bool             // 启用审计日志
    Prefix          string           // 只处理带有此前缀的变量
}

配置字段

文件处理

这些字段控制文件加载行为。

Filenames []string

要加载的文件路径列表。默认 [".env"]。

cfg.Filenames = []string{".env", ".env.local"}

---

FailOnMissingFile bool

文件不存在时是否返回错误。默认 false（静默跳过）。

cfg.FailOnMissingFile = true  // 文件不存在时报错

---

OverwriteExisting bool

是否覆盖已存在的环境变量。默认 false。

cfg.OverwriteExisting = true  // 允许覆盖

---

AutoApply bool

加载后自动应用到系统环境（os.Environ）。默认 false。

cfg.AutoApply = true  // 加载后自动应用

注意

包级 Load() 函数会自动设置 AutoApply = true。使用 New() 创建 Loader 时需手动设置。

变量展开

ExpandVariables bool

启用 ${VAR} 语法变量展开。默认 true。

cfg.ExpandVariables = true

支持的展开语法：

语法	说明
${VAR}	引用变量
${VAR:-default}	变量不存在时使用默认值（变量存在即使为空也用原值）
${VAR:=default}	同 ${VAR:-default}（变量不存在时使用默认值，不写回存储）
${VAR:?error}	变量不存在或为空时报错

空字符串的处理

${VAR:-default} 与 ${VAR:=default} 仅在变量未设置时使用默认值；若变量被显式设为空字符串（VAR=），则使用空字符串原值。仅 ${VAR:?error} 会把空字符串视为错误。详见 变量展开。

安全限制

MaxFileSize int64

单文件最大字节数。默认 2MB，硬性上限 100MB。

cfg.MaxFileSize = 10 * 1024 * 1024 // 10 MB

配置	默认值	硬性上限
MaxFileSize	2MB (2097152)	100MB

---

MaxLineLength int

单行最大长度。默认 1024，硬性上限 64KB。

cfg.MaxLineLength = 2048

配置	默认值	硬性上限
MaxLineLength	1024	65536 (64KB)

---

MaxKeyLength int

键名最大长度。默认 64，硬性上限 1024。

cfg.MaxKeyLength = 128

配置	默认值	硬性上限
MaxKeyLength	64	1024

---

MaxValueLength int

值最大长度。默认 4096，硬性上限 1MB。

cfg.MaxValueLength = 8192

配置	默认值	硬性上限
MaxValueLength	4096	1048576 (1MB)

---

MaxVariables int

每文件最大变量数。默认 500，硬性上限 10000。

cfg.MaxVariables = 1000

配置	默认值	硬性上限
MaxVariables	500	10000

---

MaxExpansionDepth int

变量展开最大深度。默认 5，硬性上限 20。

cfg.MaxExpansionDepth = 10

配置	默认值	硬性上限
MaxExpansionDepth	5	20

键验证

KeyPattern *regexp.Regexp

自定义键名匹配模式。默认 nil（使用快速字节级验证）。

性能优化

nil 值启用快速字节级验证（约 10 倍性能提升）。默认验证规则：以字母开头，只包含字母、数字、下划线。

import "regexp"

// 自定义模式
cfg.KeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)

---

AllowedKeys []string

允许的键名白名单。为空时允许所有键（除禁止键外）。

cfg.AllowedKeys = []string{"APP_NAME", "APP_VERSION", "PORT"}

---

ForbiddenKeys []string

额外的禁止键列表（叠加内置禁止键）。

cfg.ForbiddenKeys = []string{"CUSTOM_DANGEROUS_VAR"}

内置禁止键

库内置禁止 PATH、LD_PRELOAD、LD_LIBRARY_PATH、DYLD_INSERT_LIBRARIES 等系统关键变量。详见 常量与错误。

---

RequiredKeys []string

必需的键名列表。调用 Validate() 时检查。

cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}

---

ValidateValues bool

验证值的安全性（控制字符、空字节等）。默认 true。

安全建议

建议始终保持启用，仅在特殊场景（如需要存储包含控制字符的值）时禁用。

cfg.ValidateValues = true  // 默认已启用

---

ValidateUTF8 bool

验证值是否为有效的 UTF-8 编码。默认 false。

cfg.ValidateUTF8 = true  // 启用 UTF-8 验证

解析选项

AllowExportPrefix bool

允许 export KEY=value 语法。默认 true。

cfg.AllowExportPrefix = false  // 禁止 export 前缀

---

AllowYamlSyntax bool

允许 YAML 风格语法（KEY: value）。默认 false。

cfg.AllowYamlSyntax = true

JSON 选项

JSONNullAsEmpty bool

JSON null 值转为空字符串。默认 true。

cfg.JSONNullAsEmpty = true

---

JSONNumberAsString bool

JSON 数字转为字符串。默认 true。

cfg.JSONNumberAsString = true

---

JSONBoolAsString bool

JSON 布尔值转为字符串。默认 true。

cfg.JSONBoolAsString = true

---

JSONMaxDepth int

JSON 最大嵌套深度。默认 10。

cfg.JSONMaxDepth = 20

YAML 选项

YAMLNullAsEmpty bool

YAML null/~ 值转为空字符串。默认 true。

cfg.YAMLNullAsEmpty = true

---

YAMLNumberAsString bool

YAML 数字转为字符串。默认 true。

cfg.YAMLNumberAsString = true

---

YAMLBoolAsString bool

YAML 布尔值转为字符串。默认 true。

cfg.YAMLBoolAsString = true

---

YAMLMaxDepth int

YAML 最大嵌套深度。默认 10。

cfg.YAMLMaxDepth = 15

审计

AuditEnabled bool

启用审计日志。默认 false。

cfg.AuditEnabled = true

---

AuditHandler AuditHandler

自定义审计处理器。

cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

详见

审计日志 获取完整审计配置说明。

高级选项

Prefix string

只处理带有此前缀的变量。默认 ""（处理所有变量）。

cfg.Prefix = "MYAPP_"  // 只加载 MYAPP_ 开头的变量

---

FileSystem FileSystem

自定义文件系统接口（用于测试）。

cfg.FileSystem = &MockFileSystem{}

---

CustomValidator Validator

自定义键/值验证器。覆盖内置验证器。

cfg.CustomValidator = &MyValidator{}

---

CustomExpander VariableExpander

自定义变量展开器。覆盖内置展开器。

cfg.CustomExpander = &MyExpander{}

---

CustomAuditor AuditLogger

自定义审计日志器。覆盖内置审计器。

cfg.CustomAuditor = &MyAuditLogger{}

---

工厂函数

DefaultConfig

func DefaultConfig() Config

返回安全的默认配置。

默认值：

字段	值
Filenames	[".env"]
FailOnMissingFile	false
OverwriteExisting	false
AutoApply	false
ExpandVariables	true
MaxFileSize	2MB
MaxLineLength	1024
MaxKeyLength	64
MaxValueLength	4096
MaxVariables	500
MaxExpansionDepth	5
ValidateValues	true
KeyPattern	nil (快速验证)
AllowExportPrefix	true
AllowYamlSyntax	false
JSONNullAsEmpty	true
JSONNumberAsString	true
JSONBoolAsString	true
JSONMaxDepth	10
YAMLNullAsEmpty	true
YAMLNumberAsString	true
YAMLBoolAsString	true
YAMLMaxDepth	10
ValidateUTF8	false
AuditEnabled	false
Prefix	""

---

DevelopmentConfig

func DevelopmentConfig() Config

返回开发环境配置（宽松限制）。

与默认配置的差异：

• OverwriteExisting: true
• AllowYamlSyntax: true
• MaxFileSize: 10MB

安全保障

ValidateValues 在所有预设配置中始终保持 true（与默认值一致），确保安全性不受环境影响。

cfg := env.DevelopmentConfig()
cfg.Filenames = []string{".env.development"}
loader, _ := env.New(cfg)

---

TestingConfig

func TestingConfig() Config

返回测试环境配置。

与默认配置的差异：

• OverwriteExisting: true
• MaxFileSize: 64KB
• MaxVariables: 50

func TestSomething(t *testing.T) {
    cfg := env.TestingConfig()
    cfg.Filenames = []string{".env.test"}
    loader, _ := env.New(cfg)
    defer loader.Close()
}

---

ProductionConfig

func ProductionConfig() Config

返回生产环境配置（严格验证 + 审计）。

与默认配置的差异：

• FailOnMissingFile: true
• AuditEnabled: true
• MaxFileSize: 64KB
• MaxVariables: 50

cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)
loader, _ := env.New(cfg)

---

预设详细对比

功能	Default	Development	Testing	Production
覆盖已存在变量	✗	✓	✓	✗
文件不存在时报错	✗	✗	✗	✓
审计日志	✗	✗	✗	✓
YAML 语法	✗	✓	✗	✗
文件大小限制	2MB	10MB	64KB	64KB
最大变量数	500	500	50	50
禁止键检查	✓	✓	✓	✓
值验证	✓	✓	✓	✓

选择建议

• 开发环境：使用 DevelopmentConfig()，宽松限制便于快速迭代
• 测试环境：使用 TestingConfig()，允许覆盖便于测试隔离
• 生产环境：使用 ProductionConfig()，启用审计和严格验证

---

方法

Validate

func (c *Config) Validate() error

验证配置有效性。检查所有限制值是否在有效范围内。

cfg := env.DefaultConfig()
cfg.MaxFileSize = 1000

if err := cfg.Validate(); err != nil {
    // 配置无效
}

验证规则：

• 所有限制值必须为正数
• 所有限制值不能超过硬性上限
• KeyPattern 如果非 nil，必须能匹配有效键名（如 TEST_KEY）、不能匹配空字符串、不能匹配数字开头的键名
• JSONMaxDepth 和 YAMLMaxDepth 必须在 1-100 之间

---

IsZero

func (c *Config) IsZero() bool

检查 Config 是否为未初始化的零值。用于判断是否应使用 DefaultConfig()。

返回：

• bool - 是否为零值配置

检测范围：

• 数值限制（MaxFileSize、MaxVariables 等）
• 布尔字段（ValidateValues、AutoApply 等）
• 指针/接口字段（KeyPattern、FileSystem 等）
• 切片字段（Filenames、RequiredKeys 等）

注意

部分初始化的 Config 可能不被检测为零值。建议始终从 DefaultConfig() 开始自定义配置：

// 推荐
cfg := env.DefaultConfig()
cfg.Filenames = []string{".env.production"}

// 不推荐（部分字段为零值）
var cfg env.Config
cfg.Filenames = []string{".env.production"}

---

使用示例

基本配置

cfg := env.DefaultConfig()
cfg.Filenames = []string{".env", ".env.local"}
cfg.OverwriteExisting = true

loader, err := env.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer loader.Close()

生产环境配置

cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "DB_PORT", "API_KEY"}
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

loader, err := env.New(cfg)
if err != nil {
    log.Fatal(err)
}
defer loader.Close()

if err := loader.LoadFiles(".env"); err != nil {
    log.Fatal(err)
}

if err := loader.Validate(); err != nil {
    log.Fatal("缺少必需配置：", err)
}

使用前缀过滤

cfg := env.DefaultConfig()
cfg.Prefix = "MYAPP_"  // 只加载 MYAPP_KEY1, MYAPP_KEY2 等
cfg.Filenames = []string{".env"}

loader, _ := env.New(cfg)
// loader 中只有 MYAPP_ 开头的变量

自定义验证

import "regexp"

cfg := env.DefaultConfig()
// 只允许大写字母开头
cfg.KeyPattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)
// 添加自定义禁止键
cfg.ForbiddenKeys = []string{"DEBUG", "TRACE"}

loader, _ := env.New(cfg)

---

相关文档

• Loader API - 加载器方法
• 常量与错误 - 限制常量与错误类型
• 审计日志 - 审计配置指南