佐德信封

用于装入和验证环境变量的 TypeScript 库 佐德语Name,为环境配置提供强而安全的类型验证.

安装

bun add @arthur-lobo/zod-env zod
# or
npm install @arthur-lobo/zod-env zod

zod 是一个对等依赖,所以它必须安装在库旁.

说明

ZodEnv 允许您定义 Zod schemas 来验证环境变量,确保它们的值格式正确,并在必要时提供默认值. 它支持同步操作和同步操作,并允许您定义如何 .env 必须装入.

基本用途

同步类 : ZodEnv

import { z } from 'zod';
import { ZodEnv } from '@arthur-lobo/zod-env';

const schema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string(),
  DEBUG: z.coerce.boolean().default(false),
});

const env = new ZodEnv({
  schema,
  getEnv: () => process.env, // or any function that returns an object with the variables like `import.meta.env` when using vite to build your frontend
});

// Access validated values
console.log(env.get('PORT')); // 3000 (or the value of process.env.PORT if defined)
console.log(env.get('DATABASE_URL')); // validated string

同步类 : AsyncZodEnv

import { z } from 'zod';
import { AsyncZodEnv } from '@arthur-lobo/zod-env';

const schema = z.object({
  API_KEY: z.string(),
  TIMEOUT: z.coerce.number().default(5000),
});

const env = new AsyncZodEnv({
  schema,
  getEnv: async () => {
    await someAsyncOperation();
    return process.env;
  },
});

// Access validated values asynchronously
const apiKey = await env.get('API_KEY');
const timeout = await env.get('TIMEOUT');

正在装入.env 文件

您可以自动加载 .env 使用 Node.js 的文件 loadEnv 函数 :

import { loadEnvFile } from 'node:process';

const env = new ZodEnv({
  schema: z.object({
    SECRET_KEY: z.string(),
  }),
  loadEnv: loadEnvFile, // Loads the .env file
  getEnv: () => process.env,
});

console.log(env.get('SECRET_KEY')); // Validated value from .env

对于同步操作:

const env = new AsyncZodEnv({
  schema: z.object({
    SECRET_KEY: z.string(),
  }),
  loadEnv: async () => loadEnvFile(), // Loads .env asynchronously
  getEnv: async () => process.env,
});

Schema 实例

import { z } from 'zod';

// Basic schema with default values
const basicSchema = z.object({
  PORT: z.coerce.number().default(3000),
  HOST: z.string().default('localhost'),
  DEBUG: z.coerce.boolean().default(false),
});

// Schema with custom validations
const advancedSchema = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32, 'JWT secret must be at least 32 characters'),
  MAX_CONNECTIONS: z.coerce.number().min(1).max(100),
  ALLOWED_ORIGINS: z.string().transform(str => str.split(',')).pipe(z.array(z.string().url())),
});

福利

• 强类型验证:使用Zod来确保环境变量的格式是正确的.
• 默认值: Zod schema中默认值的原生支持.
• 灵活性: 任何环境变量源的工程(process.env,导入.meta.env,自定义文件等).
• .env 支持: 与 .env 通过Node.js的文件 loadEnvFile。 。 。 .
• 自动同步/同步:根据需要选择同步操作或同步操作.
• 类型脚本:完全输入,提供自动完成和类型检查.