Rspack 如何管理环境变量？

Rspack 的环境变量管理是前端开发中的重要功能，能够帮助开发者在不同环境下使用不同的配置。以下是 Rspack 环境变量管理的详细说明：

环境变量基本概念

环境变量是在构建时注入到代码中的变量，用于区分不同环境（开发、测试、生产）的配置。

环境变量定义方式

1. DefinePlugin

使用 DefinePlugin 定义环境变量：

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')
    })
  ]
}

2. .env 文件

使用 .env 文件管理环境变量：

bash
# .env.development
NODE_ENV=development
API_URL=http://localhost:3000
DEBUG=true

# .env.production
NODE_ENV=production
API_URL=https://api.example.com
DEBUG=false

3. 命令行参数

通过命令行传递环境变量：

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

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

# 使用 cross-env（跨平台）
npx cross-env NODE_ENV=production API_URL=https://api.example.com npx rspack build

环境变量加载

1. dotenv-webpack-plugin

使用 dotenv-webpack-plugin 加载 .env 文件：

javascript
const Dotenv = require('dotenv-webpack');

module.exports = {
  plugins: [
    new Dotenv({
      path: './.env.production',
      safe: true,
      systemvars: true,
      silent: true
    })
  ]
}

2. 自定义环境变量加载

javascript
const fs = require('fs');
const path = require('path');

function loadEnv(mode) {
  const envPath = path.resolve(__dirname, `.env.${mode}`);
  const envContent = fs.readFileSync(envPath, 'utf8');
  
  const envVars = {};
  envContent.split('\n').forEach(line => {
    const [key, value] = line.split('=');
    if (key && value) {
      envVars[key.trim()] = value.trim();
    }
  });
  
  return envVars;
}

const envVars = loadEnv(process.env.NODE_ENV || 'development');

module.exports = {
  plugins: [
    new DefinePlugin({
      'process.env': JSON.stringify(envVars)
    })
  ]
}

环境变量使用

1. 在代码中使用

javascript
// 使用环境变量
const apiUrl = process.env.API_URL;
const isDevelopment = process.env.NODE_ENV === 'development';
const version = process.env.VERSION;

console.log('API URL:', apiUrl);
console.log('Is Development:', isDevelopment);

2. TypeScript 类型定义

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

环境配置

1. 多环境配置

javascript
const { merge } = require('webpack-merge');

const commonConfig = require('./rspack.common.js');
const devConfig = require('./rspack.dev.js');
const prodConfig = require('./rspack.prod.js');

module.exports = (env) => {
  const mode = env.mode || 'development';
  
  if (mode === 'production') {
    return merge(commonConfig, prodConfig);
  }
  
  return merge(commonConfig, devConfig);
};

2. 环境特定配置

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

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

环境变量最佳实践

1. 敏感信息处理

javascript
// 不要在代码中硬编码敏感信息
// ❌ 错误
const API_KEY = 'your-secret-key';

// ✅ 正确
const API_KEY = process.env.API_KEY;

// 使用 .env.local 存储敏感信息（不提交到版本控制）
// .env.local
API_KEY=your-secret-key

2. 环境变量验证

javascript
// 验证必需的环境变量
const requiredEnvVars = ['API_URL', 'API_KEY'];

requiredEnvVars.forEach(envVar => {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
});

3. 默认值设置

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

环境变量与构建

1. 条件构建

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)
      })
    ]
  };
};

2. 环境特定插件

javascript
const isProduction = process.env.NODE_ENV === 'production';

const plugins = [
  new DefinePlugin({
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV)
  })
];

if (isProduction) {
  plugins.push(
    new TerserPlugin(),
    new CompressionPlugin()
  );
}

module.exports = {
  plugins
};

.env 文件管理

1. 文件命名约定

shell
.env                # 所有环境的默认值
.env.local          # 本地覆盖（不提交）
.env.development    # 开发环境
.env.test           # 测试环境
.env.production     # 生产环境

2. .gitignore 配置

shell
# 忽略所有 .env.local 文件
.env.local
.env.*.local

# 可以提交其他环境配置
.env.development
.env.test
.env.production

3. 环境变量优先级

1. 命令行参数
2. .env.local
3. .env.[mode].local
4. .env.[mode]
5. .env

环境变量与 CI/CD

1. GitHub Actions

yaml
name: Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm install
      - name: Build
        env:
          NODE_ENV: production
          API_URL: ${{ secrets.API_URL }}
        run: npm run build

2. Docker

dockerfile
# Dockerfile
FROM node:18-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

最佳实践

1. 安全性：

   • 不要在代码中硬编码敏感信息
   • 使用 .env.local 存储本地配置
   • 在 CI/CD 中使用 secrets

2. 可维护性：

   • 为不同环境创建独立的配置文件
   • 使用清晰的变量命名
   • 提供默认值

3. 类型安全：

   • 为 TypeScript 项目提供类型定义
   • 验证环境变量的有效性
   • 处理缺失的环境变量

4. 文档化：

   • 记录所有环境变量
   • 说明每个变量的用途
   • 提供示例配置

Rspack 的环境变量管理为开发者提供了灵活的配置方式，通过合理使用环境变量，可以轻松管理不同环境的配置，提升开发效率和代码质量。