hoangsonww/EnvGuard-Env-Validator
GitHub: hoangsonww/EnvGuard-Env-Validator
EnvGuard 是一个 NPM 包，用于验证 .env 文件中的环境变量是否符合预定义模式，防止配置错误和不安全默认值。
Stars: 10 | Forks: 10
# 🛡️ EnvGuard – 验证并保护您的环境变量
[](https://www.npmjs.com/package/env-guard) [](LICENSE) [](https://nodejs.org/) [](https://www.typescriptlang.org/) [](https://jestjs.io/)
**EnvGuard** 是一个 NPM 包，它根据定义好的模式验证您的环境变量，并强制要求与您的 `.env.example` 文件保持一致。在团队协作或部署到生产环境时，保护您的应用免受配置错误和不安全默认值的影响。
目前可在 NPM 上获取：[https://www.npmjs.com/package/@hoangsonw/env-guard](https://www.npmjs.com/package/@hoangsonw/env-guard)
## 目录
- [功能](#features)
- [安装说明](#installation)
- [用法](#usage)
- [基本用法](#basic-usage)
- [高级用法](#advanced-usage)
- [API 参考](#api-reference)
- [测试](#testing)
- [构建与发布](#building--publishing)
- [贡献指南](#contributing)
- [许可证](#license)
## 功能
- **模式验证：** 定义必需的环境变量和不安全的默认值。
- **.env 强制执行：** 将您实际的 `.env` 文件与提供的 `.env.example` 文件进行比较。
- **可配置行为：** 选择是发出警告还是抛出错误，并控制键匹配方式。
- **TypeScript 支持：** 完全使用 TypeScript 编写，具有完整的类型定义。
- **跨平台：** 可在 Node.js 中工作，并能无缝集成到您的部署工作流中。
## 安装说明
### 前置条件
- Node.js v14 或更高版本
- npm v6 或更高版本
### 通过 NPM 安装
```
npm install @hoangsonw/env-guard
```
### 通过 Yarn 安装
```
yarn add @hoangsonw/env-guard
```
## 用法
EnvGuard 基于模式验证您的环境变量。它从您的 `.env` 文件加载变量，并将其与参考的 `.env.example` 进行比较。
### 基本用法
为您的环境变量创建模式并进行验证：
```
import { validateEnv } from "@hoangsonw/env-guard";
const schema = {
DB_HOST: { required: true, insecureValues: ["localhost", "127.0.0.1"] },
DB_PASSWORD: { required: true, insecureValues: ["12345", "password"] },
DB_USER: { required: false },
};
validateEnv({
schema,
envFilePath: "./.env", // Defaults to "./.env"
exampleFilePath: "./.env.example", // Defaults to "./.env.example"
allowMissingExampleKeys: false, // Warn if keys mismatch
throwOnError: false, // Only warn; set to true to throw errors
});
```
### 高级用法
您可以通过更改选项来自定义 EnvGuard 的行为：
- **`allowMissingExampleKeys`**：当设置为 `false` 时，如果您的 `.env` 中存在额外的键或缺少相对于 `.env.example` 的键，它会发出警告。
- **`throwOnError`**：当设置为 `true` 时，函数将在验证失败时抛出错误，而不是仅记录警告。
示例：
```
import { validateEnv } from "@hoangsonw/env-guard";
const schema = {
API_KEY: { required: true },
DB_HOST: { required: true, insecureValues: ["localhost"] },
DB_PASSWORD: { required: true, insecureValues: ["password", "12345"] },
};
try {
validateEnv({
schema,
envFilePath: "./config/.env",
exampleFilePath: "./config/.env.example",
allowMissingExampleKeys: false,
throwOnError: true,
});
console.log("Environment variables validation passed!");
} catch (error) {
console.error("Environment validation failed:", error);
process.exit(1);
}
```
## API 参考
### `validateEnv(options: EnvGuardOptions): void` -> `验证环境变量(options: EnvGuardOptions): void`
**参数：**
- **`schema: EnvSchema`**
一个对象，定义每个环境变量的要求。
_示例：_
{
DB_HOST: { required: true, insecureValues: ["localhost"] },
API_KEY: { required: true }
}
- **`envFilePath?: string`**
您的 `.env` 文件的路径。默认值为 `"./.env"`。
- **`exampleFilePath?: string`**
您的 `.env.example` 文件的路径。默认值为 `"./.env.example"`。
- **`allowMissingExampleKeys?: boolean`**
如果设置为 `false`，EnvGuard 将对 `.env` 和 `.env.example` 之间多余的键或缺失的键发出警告。
- **`throwOnError?: boolean`**
如果为 `true`，验证失败时函数将抛出错误；否则，它将只记录警告。
**返回值：**
无；它执行验证，并根据配置记录警告/错误。
## 测试
EnvGuard 包含一个 Jest 测试套件。运行测试：
1. **安装依赖项：**
npm install
2. **运行测试：**
npm test
`__tests__` 目录中的测试文件演示了 EnvGuard 如何验证环境变量以及将 `.env` 与 `.env.example` 进行比较。
## 演示脚本
运行 `__tests__` 目录中的演示脚本以查看 EnvGuard 的实际效果：
1. **运行演示脚本（不带 `basedir` 选项）：**
npm run demoNoBasedir
2. **运行演示脚本（带 `basedir` 选项）：**
npm run demoWithBasedir
演示脚本将展示 EnvGuard 如何验证环境变量以及将 `.env` 与 `.env.example` 进行比较。请查看控制台输出以获取验证结果。
## 构建与发布
### 构建
编译 TypeScript 源代码：
```
npm run build
```
### 发布
1. **登录 npm：**
npm login
2. **发布包：**
npm publish --access public
## 许可证
本项目根据 [MIT 许可证](LICENSE) 授权。
## 最后说明
EnvGuard 确保您的环境变量配置正确且安全，减少团队协作和生产部署中的配置错误。通过模式验证和 `.env.example` 强制执行，它有助于维护项目的一致性和安全性。
祝您守护愉快！🛡️
标签：.env文件, GNU通用公共许可证, MITM代理, Node.js, NPM包, OSV-Scalibr, SMB, SOC Prime, TypeScript, 团队协作, 安全, 安全插件, 开发工具, 开源框架, 持续集成, 数据管道, 模式验证, 环境变量, 生产环境, 自定义脚本, 超时处理, 软件工程, 部署安全, 配置验证, 错误配置检测