Rsbuild 环境变量使用指南：从基础到高级实践

前言

在现代前端工程化开发中，环境变量的管理是一个至关重要的环节。Rsbuild 作为一款优秀的构建工具，提供了完善的环境变量支持机制。本文将全面介绍 Rsbuild 中环境变量的使用方法，帮助开发者更好地利用环境变量来管理不同构建环境下的配置差异。

环境变量基础概念

环境变量是在程序运行时设置的一些键值对，它们可以用来：

1. 区分开发和生产环境
2. 配置不同环境的 API 地址
3. 控制功能开关
4. 传递构建时的配置参数

Rsbuild 通过两种主要方式向代码中注入环境变量：

1. 默认提供的环境变量
2. 通过 .env 文件定义的环境变量

默认环境变量详解

Rsbuild 默认提供了一系列环境变量，这些变量可以通过两种方式访问：

1. import.meta.env 对象

这是现代 JavaScript 模块的标准方式，包含以下常用变量：

• MODE：当前构建模式（development/production）
• DEV：是否为开发模式（布尔值）
• PROD：是否为生产模式（布尔值）
• BASE_URL：服务端基础路径
• ASSET_PREFIX：静态资源前缀

使用示例：

if (import.meta.env.DEV) {
  console.log('开发环境特有逻辑');
}

2. process.env 对象

这是 Node.js 传统的环境变量访问方式，包含：

• NODE_ENV：环境标识（development/production）
• BASE_URL：同 import.meta.env.BASE_URL
• ASSET_PREFIX：同 import.meta.env.ASSET_PREFIX

使用示例：

if (process.env.NODE_ENV === 'production') {
  // 生产环境特有逻辑
}

环境变量文件(.env)管理

Rsbuild 支持通过 .env 文件来管理环境变量，这是现代前端项目的标准做法。

文件类型与加载顺序

Rsbuild 支持多种环境文件，按优先级从低到高：

1. .env - 基础环境变量
2. .env.local - 本地覆盖（应加入.gitignore）
3. .env.[mode] - 模式特定变量
4. .env.[mode].local - 模式本地覆盖

其中 [mode] 通常为 development 或 production。

环境变量作用域

默认情况下，只有以 PUBLIC_ 开头的变量会被注入到客户端代码中，这是为了避免敏感信息泄露。

例如：

PUBLIC_API_URL=https://api.example.com
DB_PASSWORD=secret

在客户端代码中：

console.log(import.meta.env.PUBLIC_API_URL); // 可用
console.log(import.meta.env.DB_PASSWORD); // undefined

自定义配置

可以通过配置调整环境变量的行为：

1. 修改前缀：

loadEnv({ prefixes: ['REACT_APP_'] })

2. 指定环境文件目录：

rsbuild build --env-dir config

3. 指定环境模式：

rsbuild build --env-mode staging

高级用法：使用 define 配置

source.define 是 Rsbuild 提供的更灵活的环境变量注入方式。

基本用法

export default {
  source: {
    define: {
      'process.env.VERSION': JSON.stringify('1.0.0')
    }
  }
}

注意事项

1. 必须使用 JSON.stringify 包裹值
2. 只能替换完整的标识符
3. 避免替换整个 process.env 对象

Tree Shaking 优化

define 可以用于标记死代码，帮助构建工具进行优化：

define: {
  'import.meta.env.FEATURE_FLAG': JSON.stringify(false)
}

构建后，相关代码分支会被移除。

TypeScript 类型支持

为了让 TypeScript 识别自定义环境变量，需要添加类型声明：

对于 import.meta.env

// env.d.ts
interface ImportMetaEnv {
  readonly PUBLIC_API_URL: string;
}

对于 process.env

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    readonly PUBLIC_API_URL: string;
  }
}

最佳实践建议

1. 敏感信息永远不要以 PUBLIC_ 开头
2. 生产环境变量应该通过 CI/CD 系统注入
3. 使用 .env.local 管理本地开发配置
4. 为所有自定义环境变量添加类型声明
5. 合理利用环境变量实现功能开关

总结

Rsbuild 提供了完善的环境变量管理方案，从默认变量到自定义配置，从基础使用到高级优化，开发者可以根据项目需求灵活选择。正确使用环境变量可以大大提高项目的可维护性和跨环境一致性。