mcpField
E
env-setup-wizard

env-setup-wizard

github.com/onewave-ai开发393293 次安装1 周前更新
代码仓库

关于 env-setup-wizard

env-setup-wizard 是用于整理项目环境变量配置的 Skill，涵盖类型安全访问、启动时校验和变量文档，并提供通用项目及 Next.js 的配置模式。

主要功能

  1. 01按环境整理 .env 文件
  2. 02生成纳入版本管理的 .env.example
  3. 03使用 Zod 校验变量
  4. 04区分服务端与客户端变量
  5. 05记录密钥处理实践

适用场景

  1. 01为新项目设置环境配置
  2. 02为必需变量添加启动检查
  3. 03配置 Next.js 服务端和客户端变量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/onewave-ai/claude-skills --skill env-setup-wizard

安装后在 Claude Code 中输入/env-setup-wizard确认已加载。

详细介绍

环境配置向导

说明

设置环境配置时：

  1. 识别项目所需的变量
  2. 创建结构清晰的 .env 文件
  3. 为环境变量设置类型安全的访问方式
  4. 在启动时添加验证
  5. 记录所有变量

文件结构

project/
├── .env                  # Local development (git-ignored)
├── .env.example          # Template (committed to git)
├── .env.local            # Local overrides (git-ignored)
├── .env.development      # Development defaults
├── .env.production       # Production defaults
└── src/
    └── lib/
        └── env.ts        # Type-safe env access

.env.example 模板

# ===================
# Application
# ===================
NODE_ENV=development
APP_URL=http://localhost:3000
PORT=3000

# ===================
# Database
# ===================
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# ===================
# Authentication
# ===================
# Generate with: openssl rand -base64 32
JWT_SECRET=
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000

# ===================
# Third-party APIs
# ===================
# Get from: https://stripe.com/dashboard
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

# Get from: https://resend.com
RESEND_API_KEY=

# ===================
# Storage
# ===================
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1
S3_BUCKET_NAME=

类型安全的环境配置（Zod）

// src/lib/env.ts
import { z } from 'zod';

const envSchema = z.object({
  // App
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  APP_URL: z.string().url(),
  PORT: z.coerce.number().default(3000),

  // Database
  DATABASE_URL: z.string().min(1),

  // Auth
  JWT_SECRET: z.string().min(32),
  NEXTAUTH_SECRET: z.string().min(32),
  NEXTAUTH_URL: z.string().url(),

  // APIs (optional in dev)
  STRIPE_SECRET_KEY: z.string().optional(),
  RESEND_API_KEY: z.string().optional(),
});

// Validate on import
const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('Invalid environment variables:');
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const env = parsed.data;

// Type export for use elsewhere
export type Env = z.infer<typeof envSchema>;

Next.js 特定配置

// src/lib/env.ts for Next.js
import { z } from 'zod';

// Server-side variables
const serverSchema = z.object({
  DATABASE_URL: z.string(),
  JWT_SECRET: z.string(),
});

// Client-side variables (must start with NEXT_PUBLIC_)
const clientSchema = z.object({
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_STRIPE_KEY: z.string(),
});

export const serverEnv = serverSchema.parse(process.env);
export const clientEnv = clientSchema.parse({
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  NEXT_PUBLIC_STRIPE_KEY: process.env.NEXT_PUBLIC_STRIPE_KEY,
});

T3 Env（推荐用于 Next.js）

// src/env.mjs
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    NODE_ENV: z.enum(["development", "test", "production"]),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  },
});

.gitignore

# Environment files
.env
.env.local
.env.*.local

# Keep example
!.env.example

安全最佳实践

  1. 切勿将密钥提交到 git
  2. 为不同环境使用不同的值
  3. 定期轮换密钥
  4. 在生产环境中使用密钥管理器（Vault、AWS Secrets Manager）
  5. 在启动时进行验证，以便快速失败
  6. 为客户端变量添加前缀（NEXT_PUBLIC_、VITE_、REACT_APP_）

评论

支持 Markdown