RSBuild 环境变量加载机制解析与高级控制方案

环境变量管理的痛点分析

在现代前端工程化实践中，环境变量管理是一个常见但容易被忽视的重要环节。RSBuild 作为构建工具，提供了 loadEnv 方法来加载环境变量文件，但默认行为会直接修改 process.env 对象，这在某些场景下会带来不便：

1. 环境污染问题：当在非构建流程（如自定义 CLI 工具）中使用时，直接修改 process.env 会导致全局环境变量污染
2. 值恢复困难：现有的 cleanup 方法只能简单删除注入的变量，无法恢复原有的环境变量值
3. 隔离性不足：缺乏对加载环境的细粒度控制能力，难以实现环境隔离测试

解决方案设计演进

最初提出的 dryRun 方案虽然能解决基本问题，但经过深入讨论后，我们发现更优雅的解决方案是引入 processEnv 配置项。这种设计具有以下优势：

1. 灵活性：可以完全控制环境变量的注入目标
2. 兼容性：保持与现有 API 的完全兼容
3. 扩展性：为未来可能的复杂场景预留了扩展空间

processEnv 配置的三种典型使用场景

// 场景一：默认行为 - 使用真实环境变量
loadEnv({ processEnv: process.env });

// 场景二：隔离环境 - 基于当前环境的克隆
loadEnv({ processEnv: {...process.env}});

// 场景三：纯净环境 - 完全空环境
loadEnv({ processEnv: {} });

实现原理与技术细节

processEnv 选项的实现借鉴了 dotenv-expand 的设计理念，其核心工作原理是：

1. 优先级处理：仍然保持 .env 文件加载的优先级规则
2. 目标注入：将解析后的变量注入到指定的 processEnv 对象
3. 返回值设计：无论是否修改环境，都会返回 parsed 对象供程序使用

最佳实践建议

1. 构建流程：使用默认配置即可，直接修改 process.env
2. 测试环境：建议使用隔离环境模式，避免测试间相互影响
3. 工具开发：推荐使用空环境模式，确保工具行为的确定性

未来展望

processEnv 配置的引入为 RSBuild 的环境管理打开了更多可能性，未来可以考虑：

1. 多环境并行管理能力
2. 环境变量变更追踪
3. 与环境管理工具的深度集成

这种设计体现了 RSBuild 对工程化实践的深入思考，既解决了实际问题，又为开发者提供了充分的灵活性。