Skip to main content

环境变量及 .env 文件配置

一、项目的环境​

项目开发中一般会经历「开发阶段」「测试阶段」「上线阶段」，各阶段对代码的要求是有区别的，因此分为以下环境：

  • 开发环境（开发阶段，本地开发版本，调试用）
  • 测试环境（测试阶段，上线前版本，测 bug 用）
  • 生产环境（上线阶段，正式对外发布的版本，一般会进行优化，关掉错误报告）

针对每一种环境需要编写一些不同的代码，并且保证这些代码运行在正确的环境中，因此需要进行正确的环境配置和管理。不同环境配置之间的关系如下：

可以看到，不同环境有公共配置项。

二、环境变量​

各个环境有各自的环境变量，可通过 .env 文件进行配置：

1、.env 配置文件​

ENV 配置文件用于进行不同环境下变量的配置：

  • ​​.env​​：全局默认配置文件，所有环境都会载入；
  • ​​.env.local​​：全局默认配置文件，所有环境都会载入，但会被 git 忽略；
  • ​​.env.development​​：只在开发环境载入的配置文件；
  • ​​.env.development.local​​：只在开发环境载入的配置文件，但会被 git 忽略；
  • ​​.env.test​​：只在测试环境载入的配置文件；
  • ​​.env.test.local​​：只在测试环境载入的配置文件，但会被 git 忽略；
  • ​​.env.production​​：只在生产环境载入的配置文件；
  • ​​.env.production.local​​：只在生产环境载入的配置文件，但会被 git 忽略。

除了以上常用环境，还可以新增自定义环境，例如：

  • .env.staging：预发布环境

2、环境变量的声明和使用​

不同构建工具对环境变量的定义和使用有所不同：

构建工具定义环境变量使用环境变量
ViteVITE_XXimport.meta.env.VITE_XX
Create React AppREACT_APP_XXprocess.env.REACT_APP_XX
Vue CLIVUE_APP_XXprocess.env.VUE_APP_XX

3、项目环境的切换​

可通过加 --mode xx 指定运行环境：

package.json
"scripts": {
  "start:test": "vite --mode test",
  "start:production": "vite --mode production",
},

运行对应的 .env 配置文件中，.local 的优先级更高。

三、环境变量的加载原理​

上述列举的构建工具均使用 dotenv 从环境目录中的 .env 文件加载自定义环境变量。dotenv 的源码如下：

lib/main.js
// https://github.com/motdotla/dotenv/blob/master/lib/main.js

const fs = require('fs')
const path = require('path')
const os = require('os')
const packageJson = require('../package.json')

const version = packageJson.version

const LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg

// Parser src into an Object
function parse (src) {
  const obj = {}

  // Convert buffer to string
  let lines = src.toString()

  // Convert line breaks to same format
  lines = lines.replace(/\r\n?/mg, '\n')

  let match
  while ((match = LINE.exec(lines)) != null) {
    const key = match[1]

    // Default undefined or null to empty string
    let value = (match[2] || '')

    // Remove whitespace
    value = value.trim()

    // Check if double quoted
    const maybeQuote = value[0]

    // Remove surrounding quotes
    value = value.replace(/^(['"`])([\s\S]*)\1$/mg, '$2')

    // Expand newlines if double quoted
    if (maybeQuote === '"') {
      value = value.replace(/\\n/g, '\n')
      value = value.replace(/\\r/g, '\r')
    }

    // Add to object
    obj[key] = value
  }

  return obj
}

function _log (message) {
  console.log(`[dotenv@${version}][DEBUG] ${message}`)
}

function _resolveHome (envPath) {
  return envPath[0] === '~' ? path.join(os.homedir(), envPath.slice(1)) : envPath
}

// Populates process.env from .env file
function config (options) {
  let dotenvPath = path.resolve(process.cwd(), '.env')
  let encoding = 'utf8'
  const debug = Boolean(options && options.debug)
  const override = Boolean(options && options.override)

  if (options) {
    if (options.path != null) {
      dotenvPath = _resolveHome(options.path)
    }
    if (options.encoding != null) {
      encoding = options.encoding
    }
  }

  try {
    // Specifying an encoding returns a string instead of a buffer
    const parsed = DotenvModule.parse(fs.readFileSync(dotenvPath, { encoding }))

    Object.keys(parsed).forEach(function (key) {
      if (!Object.prototype.hasOwnProperty.call(process.env, key)) {
        process.env[key] = parsed[key]
      } else {
        if (override === true) {
          process.env[key] = parsed[key]
        }

        if (debug) {
          if (override === true) {
            _log(`"${key}" is already defined in \`process.env\` and WAS overwritten`)
          } else {
            _log(`"${key}" is already defined in \`process.env\` and was NOT overwritten`)
          }
        }
      }
    })

    return { parsed }
  } catch (e) {
    if (debug) {
      _log(`Failed to load ${dotenvPath} ${e.message}`)
    }

    return { error: e }
  }
}

const DotenvModule = {
  config,
  parse
}

module.exports.config = DotenvModule.config
module.exports.parse = DotenvModule.parse
module.exports = DotenvModule

可以看到，dotenv 的原理是使用 fs.readFileSync 读取 .env 文件，并解析文件为键值对形式的对象，将最终结果对象遍历赋值到 process.env 上。