不同打包工具下的环境变量配置方式对比

本文作者为 360 奇舞团前端开发工程师 天明

前言

在现代的JavaScript应用程序开发中,环境变量的配置是至关重要的。不同的应用场景和部署环境可能需要不同的配置,例如开发、测试和生产环境。最常见的需求是根据不同的环境,配置如是否开启sourceMapAPI请求地址的切换、是否压缩代码等逻辑。本文主要介绍利用不同的工具:WebpackViteRollup打包项目的环境变量的配置方式。

process.env.NODE_ENV

process.env.NODE_ENV应该是我们最熟悉的环境变量了,我们知道在Node环境中process是一个全局变量,无需require引入。process.env属性返回一个包含用户环境信息的对象,当我们打印process.env时,发现它并没有NODE_ENV这一个属性。实际上process.env.NODE_ENV是在package.jsonscripts命令中注入的,可以通过以下方式进行设置:

go 复制代码
{
  "scripts": {
    "dev": "NODE_ENV=development webpack --config webpack.dev.config.js",
    "prod": "NODE_ENV=production webpack --config webpack.prod.config.js"
  }
}

当运行npm run devnpm run prod命令时,设置了NODE_ENV的不同值,项目中访问到的process.env.NODE_ENV值也会根据执行脚本的不同而分别取值:developmentproduction. 我们可以根据这个值的不同而分别进行不同的配置,这就是配置环境变量的基本逻辑.

Webpack项目环境变量配置方式
使用DefinePlugin插件

前面提到,在scripts命令中注入的NODE_ENV只能被Webpack的构建脚本访问,而被Webpack打包的源码中是无法访问到的,此时可以借助WebpackDefinePlugin插件,创建全局变量。

go 复制代码
const webpack = require('webpack');

module.exports = {
  //.....其他配置
  plugins: [
    new webpack.DefinePlugin({
      'process.env.API_URL': JSON.stringify('https://api.example.com'),
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    }),
  ],
};

在上面的示例中,我们定义了两个环境变量:API_URLNODE_ENV,并且使用JSON.stringify将值转换为字符串。这样就可以在代码中使用process.env.API_URLprocess.env.NODE_ENV来访问这两个环境变量的值了。

Windows平台配置的注意点

Windows平台下直接设置NODE_ENV =XXX是会报错的, 解决办法也很简单,可以使用cross-env这个npm包来进行配置,cross-env能够提供一个设置环境变量的scripts,这样我们就能够以unix方式设置环境变量,然后在windows上也能够兼容

  • 安装
go 复制代码
npm install cross-env --save
  • 使用
go 复制代码
"scripts": {
  "dev": "cross-env NODE_ENV=development webpack",
  "prod": "cross-env NODE_ENV=production webpack"
}

可以看到直接在NODE_ENV=XXX前面添加cross-env就可以了。

使用dotenv插件

假如我们项目的环境变量有很多,全部设置plugins中既不美观也不容易维护,此时将环境变量配置在.env文件中,然后使用dotenv插件来加载.env配置文件。

  • 安装
go 复制代码
npm install dotenv-webpack --save-dev
  • 创建环境变量文件 在项目根目录下创建一个.env文件,如果有多种不同的环境,可以针对不同的环境创建不同的配置文件,例如可以使用.env.development.env.test.env.production在文件来分别表示:开发、测试、生产环境的环境变量。在文件中配置每个环境对应的变量:
go 复制代码
// .env.development
API_URL=http://development.example.com
DEBUG=true
go 复制代码
// .env.test
API_URL=http://test.example.com
DEBUG=true
go 复制代码
// .env.production
API_URL=http://production.example.com
DEBUG=false
  • 加载.env配置 在webpack.config.js加载.env配置:
go 复制代码
require('dotenv').config({ path: path.resolve(__dirname, '.env.' + process.env.NODE_ENV) })
  • 设置scripts``scripts命令中设置NODE_ENV
go 复制代码
"scripts": {
  "dev": "cross-env NODE_ENV=development webpack",
  "dev": "cross-env NODE_ENV=test webpack",
  "prod": "cross-env NODE_ENV=production webpack"
}
Rollup项目环境变量配置方式

Rollup是一个现代化的JavaScript模块打包工具,专注于构建JavaScript库和组件。下面是Rollup中配置环境变量的几种常见方式:

使用rollup-plugin-replace

Rolluprollup-plugin-replace插件允许我们在打包过程中替换代码中的字符串。我们常用该插件来定义环境变量。

  • 安装:
go 复制代码
npm install rollup-plugin-replace --save-dev
  • rollup.config.js中配置
go 复制代码
const isProduction = process.env.NODE_ENV === 'production';
export default [
    {
         //.....其他配置
        plugins: [
            replace({
                'process.env.API_URL': JSON.stringify(isProduction ? 'https://prod.example.cn' : 'https://dev.example.cn')
                'process.env.NODE_ENV': JSON.stringify(isProduction? 'production' : 'development')

            })
        ]
    }
]

在上面的例子中,我们首先获取到当前组件库的环境变量,并根据它的值设置不同的API_URLNODE_ENV.

之所以在组件库中使用rollup-plugin-replace 替换 process.env.NODE_ENV 的原因是为了在打包时,将代码中的环境变量替换为实际的值,以便在不同的环境中正确地运行组件库。这样就避免了宿主工程中的环境变量process.env.NODE_ENV,对组件库环境变量的影响。

Rollup使用dotenv插件

Webpack类似,在Rollup中使用dotenv插件进行环境变量的配置,可以按照以下步骤进行:

  • 安装dotenvrollup-plugin-replace
go 复制代码
npm install dotenv rollup-plugin-replace --save-dev
  • 创建环境变量文件 与上面的Webpack创建环境变量文件类似,这里也可以创建多个环境配置文件.env.development.env.test.env.production

  • rollup.config.js加载.env配置

go 复制代码
import { config } from 'dotenv'
config({ path: ".env."+ process.env.NODE_ENV }).parsed
export default {
  // ...
  plugins: [
    replace({
      process.env.API_URL: JSON.stringify(process.env.API_URL),
      process.env.DEBUG: JSON.stringify(process.env.DEBUG),
    }),
    // ...
  ],
};

在上例中,我们首先通过dotenv.config()方法来加载.env文件中的环境变量。然后,使用@rollup/plugin-replace插件的replace方法,将环境变量注入到代码中。

  • package.json中设置scripts
go 复制代码
"scripts": {
    "build:dev": "cross-env NODE_ENV=development rollup -c",
    "build:prod": "cross-env NODE_ENV=production rollup -c",
    "build:test": "cross-env NODE_ENV=test rollup -c",
    "dev": "cross-env NODE_ENV=development rollup -c -w",
  }

执行对应的脚本命令后,在你的代码中,你可以通过process.env.XXX来访问已配置的环境变量.

Vite项目环境变量配置方式

与使用Webpack或是Rollup项目配置环境变量相比,Vite项目配置环境变量较为简单。

内建变量

Vite在一个特殊的import.meta.env对象上暴露环境变量

  • import.meta.env.MODE: 应用运行的模式。

  • import.meta.env.BASE_URL:部署应用时的基本 URL。他由base 配置项决定。

  • import.meta.env.PROD:应用是否运行在生产环境。

  • import.meta.env.DEV:应用是否运行在开发环境 (永远与 import.meta.env.PROD相反)。

  • import.meta.env.SSR:应用是否运行在 server 上。 这些变量可以直接在代码中访问

.env文件

同样在项目的根目录下,根据环境的不同创建不同的配置文件,不过文件的命名有些特殊性:

go 复制代码
.env                # 所有情况下都会加载
.env.local          # 所有情况下都会加载,但会被 git 忽略
.env.[mode]         # 只在指定模式下加载
.env.[mode].local   # 只在指定模式下加载,但会被 git 忽略

加载的环境变量也会通过 import.meta.env 以字符串形式暴露给客户端源码。

注意:为了防止意外地将一些环境变量泄漏到客户端,只有以VITE_为前缀的变量才会暴露给经过vite处理的代码。

模式

默认情况下,开发服务器 dev命令 运行在 development模式,而build命令则运行在production模式。这意味着当执行vite build 时,它会自动加载.env.production中可能存在的环境变量.在某些情况下,若想在vite build时运行不同的模式,你可以通过传递 --mode 选项标志来覆盖命令使用的默认模式。

go 复制代码
vite build --mode development

此时vite会使用.env.development文件下环境变量进行构建。

总结

通过对比发现虽然打包工具不同,但是配置环境变量的方式都大同小异,合理的使用环境变量,能够提高我们代码的灵活性、安全性、可维护性,并且将配置信息与代码分离是一种良好的开发实践,可以使应用程序更易于维护和管理。

参考:

https://cn.vitejs.dev/guide/env-and-mode.html

https://webpack.docschina.org/plugins/define-plugin/

https://cn.rollupjs.org/faqs/

  • END -

关于奇舞团

奇舞团是 360 集团最大的大前端团队,代表集团参与 W3C 和 ECMA 会员(TC39)工作。奇舞团非常重视人才培养,有工程师、讲师、翻译官、业务接口人、团队 Leader 等多种发展方向供员工选择,并辅以提供相应的技术力、专业力、通用力、领导力等培训课程。奇舞团以开放和求贤的心态欢迎各种优秀人才关注和加入奇舞团。