5月27日 16:54

Rspack 环境变量怎么配置和管理？

Rspack 的环境变量管理是前端工程化中的核心能力，用于区分开发、测试、生产等不同环境的配置。本文从 Rspack 原生插件、Rsbuild 集成、.env 文件、多环境配置、TypeScript 类型安全到 CI/CD 实践，系统讲解环境变量的完整管理方案。

环境变量的作用

环境变量在构建时注入到代码中，被 Rspack 直接替换为字面量值。这意味着代码中引用 process.env.NODE_ENV 的地方，打包后会被替换为 "production" 或 "development" 字符串，而非运行时读取。这一机制既能实现条件编译，也能配合 tree shaking 移除死代码。

Rspack 原生插件配置

DefinePlugin

Rspack 内置 DefinePlugin，用法与 webpack 一致，用于将代码中的标识符替换为给定值：

javascript
const { DefinePlugin } = require('@rspack/core');

module.exports = {
  plugins: [
    new DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.API_URL': JSON.stringify('https://api.example.com'),
      'process.env.VERSION': JSON.stringify('1.0.0')
    })
  ]
};

值的格式要求：所有值必须用 JSON.stringify() 包裹，因为插件做的是文本替换，不包裹会变成未定义的变量引用。

EnvironmentPlugin

EnvironmentPlugin 是 DefinePlugin 针对 process.env 的语法糖，直接读取系统环境变量：

javascript
const { EnvironmentPlugin } = require('@rspack/core');

module.exports = {
  plugins: [
    new EnvironmentPlugin({
      NODE_ENV: 'development',  // 默认值，process.env 中没有时使用
      DEBUG: false,             // 默认值
      API_KEY: undefined        // undefined 表示必须提供，否则构建报错
    })
  ]
};

与 DefinePlugin 的区别：EnvironmentPlugin 自动从 process.env 读取值并应用 JSON.stringify，无需手动处理。用 undefined 作默认值时，变量缺失会报错；用 null 作默认值则变量缺失时静默跳过。

Rsbuild 中的环境变量

Rsbuild 基于 Rspack 封装，提供了更简洁的环境变量管理方式。

默认注入的变量

Rsbuild 自动注入以下变量，无需手动配置：

javascript
// import.meta.env 中可用
import.meta.env.MODE      // 构建模式：'production' | 'development' | 'none'
import.meta.env.DEV       // 是否为开发模式
import.meta.env.PROD      // 是否为生产模式
import.meta.env.SSR       // 是否为 SSR 模式
import.meta.env.BASE_URL  // 基础 URL
import.meta.env.ASSET_PREFIX // 资源前缀

// process.env 中可用
process.env.NODE_ENV      // 自动设为 'development' 或 'production'
process.env.BASE_URL
process.env.ASSET_PREFIX

source.define 自定义变量

通过 source.define 配置项注入自定义变量，这是 Rsbuild 推荐的方式：

javascript
export default {
  source: {
    define: {
      'process.env.CUSTOM_VAR': JSON.stringify('value'),
      'import.meta.env.LANGUAGE': JSON.stringify('zh-CN'),
    },
  },
};

关闭 NODE_ENV 自动注入

如果需要自定义 process.env.NODE_ENV 的行为，通过 Rspack 的 optimization.nodeEnv 控制：

javascript
export default {
  tools: {
    rspack: {
      optimization: { nodeEnv: false },
    },
  },
};

手动加载环境变量

使用 Rsbuild 的 JavaScript API（非 CLI）时，需要手动调用 loadEnv：

javascript
import { loadEnv, mergeRsbuildConfig } from '@rsbuild/core';

const { parsed, publicVars } = loadEnv();
const mergedConfig = mergeRsbuildConfig(
  {
    source: {
      define: publicVars,
    },
  },
  userConfig,
);

.env 文件管理

文件加载规则

Rsbuild CLI 自动使用 dotenv 加载项目根目录的 .env 文件，加载优先级从高到低：

.env.[mode].local — 特定环境的本地覆盖（不提交到 Git）
.env.local — 本地覆盖（不提交到 Git）
.env.[mode] — 特定环境的共享配置
.env — 所有环境的默认值

以 PUBLIC_ 为前缀的变量会暴露到客户端代码中，其他变量仅在 Node 侧可用。可以通过 --no-env 选项禁用自动加载。

文件命名示例

bash
# .env — 通用默认值
PUBLIC_APP_TITLE=MyApp

# .env.development — 开发环境
PUBLIC_API_URL=http://localhost:3000
DEBUG=true

# .env.production — 生产环境
PUBLIC_API_URL=https://api.example.com
DEBUG=false

# .env.local — 本地覆盖（加入 .gitignore）
API_KEY=your-secret-key

.gitignore 配置

gitignore
.env.local
.env.*.local

提交 .env.development 和 .env.production 方便团队共享，而 .local 后缀的文件仅用于本地敏感配置。

命令行传递环境变量

直接通过命令行设置环境变量：

bash
# Unix/Linux/macOS
NODE_ENV=production API_URL=https://api.example.com npx rspack build

# Windows（cmd）
set NODE_ENV=production&& set API_URL=https://api.example.com&& npx rspack build

# 跨平台方案
npx cross-env NODE_ENV=production npx rspack build

Rsbuild CLI 还支持 --env 参数传递：

bash
npx rsbuild build --env production

环境变量与 Tree Shaking

环境变量的文本替换特性可以标记死代码，帮助 Rspack 在构建时移除不需要的分支：

javascript
// 源码
if (import.meta.env.DEV) {
  console.log('debug info');
}

// 生产构建后，整个 if 分支被移除

利用这一机制，可以通过自定义变量实现条件编译：

javascript
export default {
  source: {
    define: {
      'import.meta.env.LANGUAGE': JSON.stringify('zh-CN'),
    },
  },
};

// 代码中
if (import.meta.env.LANGUAGE === 'zh-CN') {
  // 仅中文版包含的代码
}

TypeScript 类型定义

为环境变量添加类型声明，避免拼写错误和类型不安全：

typescript
// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: 'development' | 'production' | 'test';
    API_URL: string;
    VERSION: string;
    DEBUG: string;
  }
}

// 或为 import.meta.env 添加类型（Rsbuild 项目）
interface ImportMetaEnv {
  readonly MODE: string;
  readonly DEV: boolean;
  readonly PROD: boolean;
  readonly CUSTOM_VAR: string;
}

多环境配置方案

方案一：配置文件拆分

将通用配置和各环境配置拆分为独立文件，通过函数导出按环境合并：

javascript
// rspack.config.js
module.exports = (env) => {
  const mode = env.mode || 'development';
  const envConfig = require(`./rspack.${mode}.js`);
  return { ...commonConfig, ...envConfig };
};

javascript
// rspack.development.js
module.exports = {
  mode: 'development',
  devtool: 'eval-cheap-module-source-map',
  devServer: { hot: true, port: 3000 }
};

// rspack.production.js
module.exports = {
  mode: 'production',
  devtool: 'source-map',
  optimization: { minimize: true }
};

方案二：条件配置

在同一配置文件中根据环境变量条件切换：

javascript
module.exports = (env) => {
  const isProduction = env.mode === 'production';

  return {
    mode: isProduction ? 'production' : 'development',
    plugins: [
      new DefinePlugin({
        'process.env.NODE_ENV': JSON.stringify(env.mode),
        'process.env.IS_PRODUCTION': JSON.stringify(isProduction)
      }),
      ...isProduction ? [
        new TerserPlugin(),
        new CompressionPlugin()
      ] : []
    ]
  };
};

环境变量的安全实践

敏感信息处理

javascript
// 错误：硬编码密钥
const API_KEY = 'sk-xxxxx';

// 正确：从环境变量读取
const API_KEY = process.env.API_KEY;

敏感信息存放在 .env.local 或 CI/CD 的 secrets 中，不提交到版本控制。

必需变量验证

javascript
const requiredVars = ['API_URL', 'API_KEY'];
requiredVars.forEach(key => {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
});

默认值设置

javascript
const apiUrl = process.env.API_URL || 'http://localhost:3000';
const timeout = parseInt(process.env.TIMEOUT || '5000', 10);
const debug = process.env.DEBUG === 'true';

CI/CD 中的环境变量

GitHub Actions

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - run: npm run build
        env:
          NODE_ENV: production
          API_URL: ${{ secrets.API_URL }}

Docker

dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
ARG NODE_ENV=production
ARG API_URL
ENV NODE_ENV=$NODE_ENV
ENV API_URL=$API_URL
RUN npm run build

Rspack 性能分析

从 Rspack 1.4 开始，通过 RSPACK_PROFILE 环境变量开启构建性能追踪：

bash
RSPACK_PROFILE=true npx rspack build

Rspack 的环境变量管理覆盖了从开发调试到生产部署的完整链路：DefinePlugin 和 EnvironmentPlugin 提供底层注入能力，Rsbuild 的 source.define 和自动 .env 加载简化日常使用，import.meta.env 系列变量开箱即用，配合 TypeScript 类型声明和条件编译可以构建类型安全、产物精简的前端项目。

标签：Rspack