DefinePlugin定义环境变量

DefinePlugin定义环境变量

DefinePlugin是Webpack内置的一个插件，用于在编译阶段创建全局常量。这些常量可以在代码中被直接引用，Webpack会在编译时将其替换为实际值。这个功能特别适合用来定义环境变量，区分开发环境和生产环境。

const webpack = require('webpack');

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

基本用法

DefinePlugin接收一个对象作为参数，对象的键是要定义的常量名称，值可以是：

• 字符串（需要用JSON.stringify转换）
• 布尔值
• 数字
• 表达式

new webpack.DefinePlugin({
  PRODUCTION: JSON.stringify(true),
  VERSION: JSON.stringify('1.0.0'),
  MAX_ITEMS: 10,
  API_URL: JSON.stringify('https://api.example.com')
})

环境变量注入

最常见的用法是注入环境变量。结合cross-env等工具，可以在不同环境中设置不同值：

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env': {
        NODE_ENV: JSON.stringify(process.env.NODE_ENV),
        API_KEY: JSON.stringify(process.env.API_KEY)
      }
    })
  ]
}

与TypeScript配合使用

在TypeScript项目中，需要声明这些全局变量以避免类型错误：

// global.d.ts
declare const PRODUCTION: boolean;
declare const VERSION: string;
declare const MAX_ITEMS: number;
declare const API_URL: string;

高级用法

DefinePlugin支持更复杂的表达式替换：

new webpack.DefinePlugin({
  'typeof window': JSON.stringify('object'),
  'process.browser': true,
  'IS_SERVER': false
})

性能优化

Webpack在压缩代码时会对这些常量进行优化，比如：

if (PRODUCTION) {
  console.log('Production mode');
}
// 会被编译为：
if (true) {
  console.log('Production mode');
}
// 进一步优化后可能完全移除这段代码

安全注意事项

直接注入未处理的用户输入可能导致安全问题：

// 危险！可能引发XSS攻击
new webpack.DefinePlugin({
  USER_INPUT: JSON.stringify(userInput) // 应该先进行转义
})

多环境配置示例

一个完整的多环境配置示例：

// webpack.config.js
const webpack = require('webpack');
const dotenv = require('dotenv');

dotenv.config();

const envVars = {
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.API_URL': JSON.stringify(process.env.API_URL),
  'process.env.DEBUG': JSON.stringify(process.env.DEBUG),
  'APP_VERSION': JSON.stringify(require('./package.json').version)
};

module.exports = {
  plugins: [new webpack.DefinePlugin(envVars)]
};

与ESLint集成

为了避免ESLint报错未定义变量，需要配置：

// .eslintrc.json
{
  "globals": {
    "PRODUCTION": "readonly",
    "VERSION": "readonly"
  }
}

常见问题解决

1. 变量未定义错误：确保在TypeScript或ESLint中正确声明了全局变量
2. 值不正确：确保使用JSON.stringify处理字符串值
3. 环境变量未加载：检查是否在webpack配置前正确加载了dotenv等环境变量工具

实际应用场景

1. 功能开关控制：

if (FEATURE_FLAG_NEW_DESIGN) {
  renderNewDesign();
} else {
  renderLegacyDesign();
}

2. 多环境API端点配置：

const apiClient = new ApiClient({
  baseURL: API_URL,
  timeout: API_TIMEOUT
});

3. 构建信息注入：

console.log(`App version ${VERSION}, built at ${BUILD_TIME}`);

与其他插件配合

DefinePlugin常与以下插件一起使用：

• EnvironmentPlugin：简化环境变量注入
• DotenvWebpack：从.env文件加载环境变量
• BannerPlugin：在文件头部添加构建信息

const { EnvironmentPlugin } = require('webpack');

module.exports = {
  plugins: [
    new EnvironmentPlugin(['NODE_ENV', 'DEBUG']),
    new webpack.DefinePlugin({
      'process.env.APP_CONFIG': JSON.stringify(loadAppConfig())
    })
  ]
}

动态值计算

DefinePlugin的值可以是动态计算的：

new webpack.DefinePlugin({
  'BUILD_TIME': JSON.stringify(new Date().toISOString()),
  'GIT_HASH': JSON.stringify(require('child_process')
    .execSync('git rev-parse HEAD')
    .toString().trim())
})

测试环境特殊处理

在测试环境中可能需要特殊配置：

const isTest = process.env.NODE_ENV === 'test';

new webpack.DefinePlugin({
  'process.env.MOCK_API': isTest,
  'process.env.TEST_USER_ID': JSON.stringify('test-user-123')
})

浏览器与Node.js差异处理

处理同构应用时的环境差异：

new webpack.DefinePlugin({
  'process.browser': JSON.stringify(true),
  'process.server': JSON.stringify(false),
  'globalThis': JSON.stringify('window') // 或 'global' for Node.js
})

生产环境优化

利用DefinePlugin进行生产环境特定优化：

new webpack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify('production'),
  '__REACT_DEVTOOLS_GLOBAL_HOOK__': '({ isDisabled: true })',
  'DEBUG': false
})