rsbuild 的环境变量怎么配置？哪些是必备的？

在现代前端工程化体系中，RSBuild作为高性能构建工具，其环境变量配置直接影响项目构建效果和部署稳定性。合理的环境变量设置不仅能实现开发/生产环境的无缝切换，更能保障敏感信息的安全管理。本文将深入解析RSBuild环境变量配置的核心要素，帮助开发者建立标准化的配置体系。

Node.js版本：建议使用16.x LTS或更高版本（当前最新稳定版为18.x）
包管理器：统一使用npm 9+或yarn 3+版本管理依赖
操作系统：Windows系统需启用WSL2环境，MacOS建议使用zsh终端

执行命令检查工具链完整性：
“`bash
npx rsbuild –version
“`
必须确保版本≥0.3.0，旧版本可通过以下命令升级：
“`bash
npm update rsbuild @rsbuild/core –save-dev
“`

NODE_ENV：开发环境标识
“`bash
开发环境
export NODE_ENV=development

生产环境
export NODE_ENV=production
“`
PUBLIC_PATH：静态资源基准路径
“`bash
export PUBLIC_PATH=https://cdn.yourdomain.com/
“`

API_SECRET：第三方服务认证密钥
“`bash
export API_SECRET=sk_xxxxxx
“`
BUILD_SIGN_KEY：构建产物签名密钥
“`bash
export BUILD_SIGN_KEY=your_private_key
“`

“`bash
开发环境构建
rsbuild build –env API_ENDPOINT=https://dev.api.com

生产环境构建
rsbuild build –env API_ENDPOINT=https://prod.api.com
“`

创建多环境配置文件：
“`
├── .env
├── .env.development
└── .env.production
“`
示例内容：
“`ini
.env.development
VITE_API_TIMEOUT=15000
SSO_REDIRECT_URI=http://localhost:3000
“`

Windows系统配置步骤：
1. 右键”此电脑”选择属性
2. 进入”高级系统设置” → 环境变量
3. 在用户变量区域新建变量

Linux/macOS配置方法：
“`bash
写入全局配置
echo ‘export BUILD_ANALYZE=true’ >> ~/.zshrc
source ~/.zshrc
“`

在rsbuild.config.js中添加验证逻辑：
“`javascript
if (!process.env.API_SECRET) {
throw new Error(‘Missing required environment variable: API_SECRET’);
}
“`

使用dotenv-vault进行加密管理
通过debug模块输出环境信息：
“`javascript
const debug = require(‘debug’)(‘env:check’);
debug(‘Current environment variables:’, process.env);
“`

禁止将.env文件加入版本控制
使用git-crypt或ansible-vault加密配置
通过Vault等专业密钥管理系统动态获取

推荐目录结构：
“`
config/
├── base.env
├── dev.env
├── stage.env
└── prod.env
“`
通过cross-env指定环境：
“`json
{
“scripts”: {
“build:prod”: “cross-env ENV=prod rsbuild build”
}
}
“`

使用define配置静态替换
“`javascript
// rsbuild.config.js
export default {
source: {
define: {
__VERSION__: JSON.stringify(process.env.npm_package_version)
}
}
}
“`
开启环境变量压缩优化：
“`javascript
export default {
performance: {
envVarOptimization: true
}
}
“`