dotenv库(环境变量和模式)

前言

说明

node.js 原生支持 .env

前言

我们在vite构建的项目或者其他项目中常看到项目根目录有.env文件，或许还看到.env.development、.env.production、.env.test等文件，这些是什么文件？又有什么作用？又是如何根据项目需要创建自定义的文件？

说明

首先，这些文件都是一种常用的环境配置文件，用于存储应用程序的配置信息。这些文件通常包含键值对，每一行都是一个配置项，键和值之间使用等号（=）或冒号（:）进行分隔。

.env是默认的环境配置文件，其中包含通用的配置项。在开发和生产环境下都可以使用这个文件，但通常不应包含敏感信息。

例如，一个示例的.env文件可能如下所示：

DB_HOST=localhost
DB_PORT=3000
DB_USER=username
DB_PASS=password

env.development是用于开发环境的配置文件。你可以在其中包含开发环境特定的配置项，如调试标志、日志级别等。

.env.test 是用于测试环境的配置文件。你可以在其中指定在单元测试或集成测试期间所需的配置项，如测试数据库连接信息等。这个文件主要用于运行应用程序的测试套件。

.env.production是用于生产环境的配置文件。你可以在其中包含生产环境特定的配置项，如数据库连接信息、API密钥等。这个文件通常只包含生产环境中需要的配置项，而不包含开发环境特有的配置。

node.js 原生支持 .env

从 Node.js v20.6.0 开始，Node.js 支持使用 .env 文件来配置环境变量。配置文件应遵循 INI 文件格式，每一行都包含一个环境变量的键值对。通过这个新的特性，就无需再使用第三方模块来加载 .env 中的环境变量了。

要使用预定义的配置初始化 Node.js 应用，请使用以下 CLI 命令：

node --env-file=config.env index.js。

例如，当应用初始化时，可以使用 process.env.PASSWORD 访问以下环境变量：

PASSWORD=nodejs

除了环境变量，这个更改还允许在 .env 文件中直接定义 NODE_OPTIONS环境变量，无需将其包含在 package.json 中。

.env

.env 文件用于配置环境变量。环境变量是在运行应用程序时向操作系统或应用传递的值，用于控制应用的行为和设置。.env 文件通常包含敏感信息（如数据库连接字符串、API 密钥等），因此它们被排除在代码版本控制系统之外，以保护这些敏感数据。

.env 文件使用键值对的格式，每一行都是一个环境变量的定义。例如：

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=123456
API_KEY=abcdef123456

在 Node.js 中有一个 process全局变量，其中的env属性可以访问系统中的环境变量。

在应用中，Node.js 无法自行维护本地环境变量，需要借助第三方库（如dotenv，它是一个零依赖的模块）来加载.env文件，并将其中的环境变量注入到 process.env 对象中。通过这种方式，可以轻松地从程序中访问这些环境变量，而不需要显式地硬编码它们。

`dotenv`库

在应用程序中，可以使dotenv库来读取.env文件中的配置信息，并将其作为环境变量使用。这样，在应用程序中就可以方便地访问和使用这些配置项。

许多流程的Node.js框架和工具链都支持使用它来加载环境配置文件，如：

Vite
Uniapp
Express.js
Koa.js
Hapi.js
Sails.js
Nest.js
Next.js
Create React App
Gatsby
Vue CLI
AdonisJS

当使用dotenv库时，你可以按照以下步骤从零开始配置和使用它。

1. 安装`dotenv`库

首先，在你的Node.js项目中安装dotenv库。使用npm或者yarn可以很方便地进行安装。在终端中运行以下命令：

npm install dotenv

或：

yarn add dotenv

2. 创建`.env`文件

在你的项目根目录下创建一个名为.env的文件，这将是你存放环境变量配置的地方。

3. 定义环境变量

在.env文件中，使用键值对的格式定义你的环境变量。例如：

DB_HOST=localhost
DB_PORT=3306
DB_USER=username
DB_PASS=password

4. 在应用程序中使用`dotenv`

在你的应用中，尽早导入并配置dotenv。例如，在你的主文件中，通常是index.js或app.js中，添加以下代码：

require('dotenv').config();

或者在ES模块（例如：package.json的"type"字段设置为"module"）：

import 'dotenv/config'

5. 访问环境变量

一旦dotenv加载了.env文件中的环境变量，你可以通过process.env对象来访问它们。例如，如果你在.env文件中定义了DB_HOST变量，你可以在代码中直接使用它：

const dbHost = process.env.DB_HOST;
console.log(dbHost); // 输出：localhost

process.env对象默认包含了当前进程的环境变量。在启动Node.js应用程序时，操作系统会将一些默认的环境变量添加到process.env中，例如PATH、HOME等。

这些默认的环境变量是与操作系统相关的，并且可能会有所差异。根据不同的操作系统（如Windows、Linux或Mac），其默认的环境变量也会有所不同。

dotenv通过读取.env文件内容，并在解析后将键值对添加到process.env对象。

确保在应用程序中使用唯一的键名来定义环境变量。避免使用已经存在的或与系统环境变量冲突的键名。可以通过添加前缀或命名空间来避免冲突。例如，如果你的应用程序是一个命令行工具，可以使用YOUR_APPNAME_作为前缀：

YOUR_APPNAME_DB_HOST=localhost
YOUR_APPNAME_API_KEY=123456

通常环境变量的命名格式为使用下划线连接的大写字母单词，为了保证命名统一，应该遵循这个约定。

自定义解析环境变量文件

除了上面步骤4默认的解析环境变量方式，还可以使用自定义解析。

dotenv导出了一个parse方法用来解析环境变量，并返回一个包含解析后的包含键值对的对象。你可以自行读取.env文件内容，并将读取后的字符串传递到parse方法，便会得到一个环境变量对象。

例如在vite中，就将dotenv 库当作一个解析器。vite会读取以下四个环境变量文件的内容，用导入的parse函数将其解析并合并，再过滤不是VITE_前缀的属性，最后将这个对象赋值给import.meta.env对象。

const dotenv = require("dotenv");
const path = require("path");

// 获取 --mode 参数
const modeIndex = process.argv.indexOf("--mode");
const mode = modeIndex !== -1 ? process.argv[modeIndex + 1] : "development";

// 尝试按顺序加载环境文件：.env.mode.local, .env.mode, .env.local, .env
const envFiles = [`.env.${mode}.local`, `.env.${mode}`, ".env.local", ".env"];

/**
 * 如果同一个变量在多个文件中定义，会使用优先级最高的文件中的值
 * 每个文件都可以定义独特的变量，它们会被合并到最终的环境变量中
 */
envFiles.forEach((file) => {
  // 获取环境变量文件路径(根据当前工作目录)
  const envPath = path.resolve(process.cwd(), file);
  console.log(envPath);
  dotenv.config({
    path: envPath,
  });
});

module.exports = process.env;

上面代码中的mode 就是vite命令的选项，用来指定运行vite时的模式，默认情况下，开发服务器 (dev命令) 运行在development(开发) 模式，而build命令则运行在production(生产) 模式。

如果你想定义一个npm script用来在测试环境构建项目，并使用.env.test文件中定义的变量作为环境变量。可以复制build命令，并将命令名改为build:test ，同时在vite build后面添加--mode test。

另外，在用命令行创建的uniapp项目中，可以在各个开发或者构建命令的最后添加--mode <模式名称> 指定对应的环境变量文件，无论是使用vue2还是vue3。