dotenv 用法教程
什么是 dotenv？
dotenv 是一个零依赖的 Node.js 库，它能将 .env 文件中的环境变量加载到 process.env 中，让你可以在应用程序中使用这些变量。
为什么需要使用 dotenv？
- 安全性：避免在代码中硬编码敏感信息（如数据库密码、API密钥）
- 可配置性：不同环境（开发、测试、生产）使用不同的配置
- 一致性：团队成员使用相同的配置结构
- 可维护性：集中管理所有环境变量
安装
在 Node.js 项目中安装
npm install dotenv --save
或使用 yarn：
yarn add dotenv
基本用法
1. 创建 .env 文件
在项目根目录创建一个 .env 文件，格式如下：
# 数据库配置
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=password123
DB_NAME=my_database
# API配置
API_KEY=your_api_key_here
API_URL=https://api.example.com
# 应用配置
PORT=3000
NODE_ENV=development
2. 加载环境变量
在应用程序的入口文件顶部添加以下代码：
// 加载 dotenv
require('dotenv').config();
// 现在可以使用 process.env 访问环境变量
console.log(process.env.DB_HOST); // 输出: localhost
console.log(process.env.PORT); // 输出: 3000
3. 在 TypeScript 项目中使用
如果你使用 TypeScript，需要先安装类型定义：
npm install @types/dotenv --save-dev
然后在代码中导入：
import * as dotenv from 'dotenv';
dotenv.config();
// 使用环境变量
const port = process.env.PORT || 3000;
高级用法
1. 自定义 .env 文件路径
如果你需要从不同位置加载 .env 文件，可以指定路径：
require('dotenv').config({ path: './config/.env' });
2. 不同环境使用不同的 .env 文件
为不同环境创建不同的 .env 文件：
.env.development- 开发环境.env.test- 测试环境.env.production- 生产环境
然后根据当前环境加载相应的文件：
const envFile = `.env.${process.env.NODE_ENV || 'development'}`;
require('dotenv').config({ path: envFile });
3. 环境变量的优先级
环境变量的加载顺序（从高到低）：
- 系统环境变量
.env文件中定义的变量- 代码中设置的默认值
4. 类型安全的环境变量
为了在 TypeScript 中获得类型安全的环境变量，可以创建一个环境变量配置文件：
// src/config/env.ts
import * as dotenv from 'dotenv';
dotenv.config();
export const env = {
port: process.env.PORT || 3000,
db: {
host: process.env.DB_HOST || 'localhost',
user: process.env.DB_USER || 'root',
password: process.env.DB_PASSWORD || '',
database: process.env.DB_NAME || 'my_database'
},
api: {
key: process.env.API_KEY || '',
url: process.env.API_URL || 'https://api.example.com'
},
nodeEnv: process.env.NODE_ENV || 'development'
};
然后在其他文件中导入使用：
import { env } from './config/env';
console.log(env.port);
console.log(env.db.host);
最佳实践
- 不要将 .env 文件提交到版本控制：在
.gitignore文件中添加.env - 提供示例文件：创建一个
.env.example文件，包含所有必要的变量但不包含实际值 - 使用默认值：为环境变量提供合理的默认值，以提高应用程序的健壮性
- 验证环境变量：在应用启动时验证所有必要的环境变量是否存在
- 文档化：记录所有环境变量的用途和预期值
常见问题
Q: 环境变量没有被加载？
A: 检查以下几点：
.env文件是否在正确的位置- 文件格式是否正确（键值对，等号两边不要有空格）
- 是否在应用程序的最开始就调用了
dotenv.config() - 系统环境变量可能会覆盖
.env文件中的值
Q: 如何在前端项目中使用 dotenv？
A: 对于前端项目，你需要使用构建工具：
- 在 Create React App 中，使用
.env文件，变量名必须以REACT_APP_开头 - 在 Vite 中，使用
.env文件，变量名必须以VITE_开头 - 在 Webpack 中，可以使用
dotenv-webpack插件
示例项目结构
my-project/
├── src/
│ ├── config/
│ │ └── env.ts # 环境变量配置
│ └── index.ts # 应用入口
├── .env # 本地环境变量（不提交到版本控制）
├── .env.example # 环境变量示例（提交到版本控制）
├── .gitignore # Git 忽略文件
├── package.json # 项目配置
└── tsconfig.json # TypeScript 配置
总结
dotenv 是一个简单但强大的工具，它能帮助你管理应用程序的配置，提高安全性和可维护性。通过本教程，你应该已经掌握了如何在项目中使用 dotenv 来管理环境变量。
记住，正确使用环境变量是现代应用程序开发的重要实践之一，它能让你的代码更加安全、灵活和可维护。
