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

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

rsbuild Unleash the power of Rspack with the out-of-the-box build tool. 项目地址: https://gitcode.com/gh_mirrors/rs/rsbuild

前言

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

环境变量基础概念

环境变量是在构建时注入到代码中的变量或表达式，主要用于：

1. 区分运行环境（开发/生产）
2. 替换代码中的常量值
3. 实现不同环境的差异化配置

Rsbuild 通过两种主要方式处理环境变量：

• 默认注入的预定义变量
• 通过 .env 文件加载的自定义变量

默认环境变量详解

Rsbuild 默认注入以下环境变量，这些变量会在构建时被替换为实际值：

1. 运行环境判断变量

import.meta.env.MODE
对应构建时设置的 mode 配置值，常用于判断当前环境：

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

import.meta.env.DEV
布尔值，开发环境下为 true

import.meta.env.PROD
布尔值，生产环境下为 true

2. 资源路径相关变量

import.meta.env.BASE_URL
对应 server.base 配置，表示服务器基础路径：

// 假设 server.base 配置为 '/admin'
const logoUrl = `${import.meta.env.BASE_URL}/images/logo.png`; 
// 开发环境结果为 '/admin/images/logo.png'

import.meta.env.ASSET_PREFIX
静态资源前缀，开发环境对应 dev.assetPrefix，生产环境对应 output.assetPrefix：

const imageUrl = `${import.meta.env.ASSET_PREFIX}/assets/image.jpg`;

3. Node.js 环境变量

process.env.NODE_ENV
自动设置为 'development' 或 'production'，兼容 Node.js 生态：

if (process.env.NODE_ENV === 'development') {
  // 开发环境特有逻辑
}

.env 文件的使用

Rsbuild 支持通过项目根目录下的 .env 文件加载环境变量，这是管理环境特定配置的推荐方式。

文件加载规则

Rsbuild 会按以下顺序加载环境文件，后加载的文件会覆盖前者的同名变量：

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

其中 [mode] 对应构建模式，可通过 CLI 参数 --env-mode 指定。

实际应用示例

假设项目有以下配置：

# .env
API_BASE=https://api.example.com
PUBLIC_TITLE=My App

# .env.development
API_BASE=http://localhost:3000

在开发构建时：

• API_BASE 将使用 http://localhost:3000
• PUBLIC_TITLE 保持 My App

公共变量与安全实践

Rsbuild 采用安全优先的设计，只有以 PUBLIC_ 前缀开头的变量才会被注入到客户端代码中：

# .env
PUBLIC_API_KEY=abc123  # 会被注入到客户端
SECRET_TOKEN=xyz456    # 仅服务端可用

安全建议：

1. 永远不要在公共变量中存储敏感信息
2. 使用有意义的变量名前缀区分用途
3. 定期审查环境变量使用情况

高级配置技巧

自定义变量前缀

如需兼容其他框架的变量命名约定（如 Create React App 的 REACT_APP_），可配置：

// rsbuild.config.js
import { defineConfig, loadEnv } from '@rsbuild/core';

const { publicVars } = loadEnv({ prefixes: ['REACT_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});

类型声明支持

在 TypeScript 项目中，为环境变量添加类型声明：

// src/env.d.ts
interface ImportMetaEnv {
  readonly PUBLIC_API_KEY: string;
  readonly PUBLIC_TITLE: string;
}

declare namespace NodeJS {
  interface ProcessEnv {
    readonly PUBLIC_API_KEY: string;
    readonly NODE_ENV: 'development' | 'production';
  }
}

性能优化建议

1. 精确替换策略

避免整体替换 process.env 对象，这会导致：

• 未使用的变量被包含在打包结果中
• 增加代码体积影响性能

推荐做法：

// 好：精确替换特定变量
define: {
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.PUBLIC_API': JSON.stringify(process.env.PUBLIC_API),
}

// 避免：替换整个对象
define: {
  'process.env': JSON.stringify(process.env), // 不推荐
}

2. Tree Shaking 优化

利用环境变量实现条件编译，移除无用代码：

// 配置
define: {
  'import.meta.env.FEATURE_FLAG': JSON.stringify('A'),
}

// 代码
if (import.meta.env.FEATURE_FLAG === 'A') {
  // 只有FEATURE_FLAG=A时才会包含这部分代码
}

构建后，未使用的代码分支会被自动移除。

常见问题解答

Q：为什么我的环境变量在客户端代码中未生效？ A：请检查：

1. 变量名是否以 PUBLIC_ 开头
2. .env 文件是否放置在项目根目录
3. 是否在修改后重新启动开发服务器

Q：如何在HTML模板中使用环境变量？ A：可通过 process.env 语法：

<title><%= process.env.PUBLIC_TITLE %></title>

Q：不同环境如何管理不同的API地址？ A：推荐方案：

1. 基础配置写在 .env
2. 环境特定配置写在 .env.development/.env.production
3. 本地覆盖写在 .env.local

总结

Rsbuild 提供了灵活完善的环境变量管理方案，通过本文的介绍，开发者可以：

• 理解默认变量的用途
• 掌握 .env 文件的使用规范
• 实现安全的变量注入
• 应用高级优化技巧

合理使用环境变量能够显著提升项目的可维护性和跨环境一致性，是现代化前端工程实践的重要组成部分。

rsbuild Unleash the power of Rspack with the out-of-the-box build tool. 项目地址: https://gitcode.com/gh_mirrors/rs/rsbuild