---
id: sm-environment-setup
name: "environment-setup"
url: https://skills.yangsir.net/skill/sm-environment-setup
author: supercent-io
domain: ai-ci-cd-deployment
tags: ["docker", "virtual-machines", "configuration-management", "infrastructure-as-code", "development-environment"]
install_count: 10500
rating: 4.50 (418 reviews)
github: https://github.com/supercent-io/skills-template
---

# environment-setup

> 该技能用于环境配置，包括新项目的初始环境设置、管理多个开发/测试/生产环境、促进团队协作及确保环境安全。

**Stats**: 10,500 installs · 4.5/5 (418 reviews)

## Before / After 对比

### 多环境部署效率

## Readme

# environment-setup

# Environment Configuration

## When to use this skill

- **New Projects**: Initial environment setup

- **Multiple Environments**: Separate dev, staging, production

- **Team Collaboration**: Share consistent environments

## Instructions

### Step 1: .env File Structure

**.env.example** (template):

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

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10

# Redis
REDIS_URL=redis://localhost:6379
REDIS_TTL=3600

# Authentication
JWT_ACCESS_SECRET=change-me-in-production-min-32-characters
JWT_REFRESH_SECRET=change-me-in-production-min-32-characters
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# External APIs
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxx
AWS_ACCESS_KEY_ID=AKIAXXXXXXXX
AWS_SECRET_ACCESS_KEY=xxxxxxxx
AWS_REGION=us-east-1
AWS_S3_BUCKET=myapp-uploads

# Monitoring
SENTRY_DSN=https://xxx@sentry.io/xxx
LOG_LEVEL=info

# Feature Flags
ENABLE_2FA=false
ENABLE_ANALYTICS=true

```

**.env.local** (per developer):

```
# Developer personal settings (add to .gitignore)
DATABASE_URL=postgresql://localhost:5432/myapp_dev
LOG_LEVEL=debug

```

**.env.production**:

```
NODE_ENV=production
PORT=8080
APP_URL=https://myapp.com

DATABASE_URL=${DATABASE_URL}  # Injected from environment variables
REDIS_URL=${REDIS_URL}

JWT_ACCESS_SECRET=${JWT_ACCESS_SECRET}
JWT_REFRESH_SECRET=${JWT_REFRESH_SECRET}

LOG_LEVEL=warn
ENABLE_2FA=true

```

### Step 2: Type-Safe Environment Variables (TypeScript)

**config/env.ts**:

```
import { z } from 'zod';
import dotenv from 'dotenv';

// Load .env file
dotenv.config();

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

  DATABASE_URL: z.string().url(),

  JWT_ACCESS_SECRET: z.string().min(32),
  JWT_REFRESH_SECRET: z.string().min(32),

  SMTP_HOST: z.string(),
  SMTP_PORT: z.coerce.number(),
  SMTP_USER: z.string().email(),
  SMTP_PASSWORD: z.string(),

  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),

  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
});

// Validate and export
export const env = envSchema.parse(process.env);

// Usage:
// import { env } from './config/env';
// console.log(env.DATABASE_URL); // Type-safe!

```

**Error Handling**:

```
try {
  const env = envSchema.parse(process.env);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error('❌ Invalid environment variables:');
    error.errors.forEach((err) => {
      console.error(`  - ${err.path.join('.')}: ${err.message}`);
    });
    process.exit(1);
  }
}

```

### Step 3: Per-Environment Config Files

**config/index.ts**:

```
interface Config {
  env: string;
  port: number;
  database: {
    url: string;
    pool: { min: number; max: number };
  };
  jwt: {
    accessSecret: string;
    refreshSecret: string;
    accessExpiry: string;
    refreshExpiry: string;
  };
  features: {
    enable2FA: boolean;
    enableAnalytics: boolean;
  };
}

const config: Config = {
  env: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT || '3000'),

  database: {
    url: process.env.DATABASE_URL!,
    pool: {
      min: parseInt(process.env.DATABASE_POOL_MIN || '2'),
      max: parseInt(process.env.DATABASE_POOL_MAX || '10'),
    },
  },

  jwt: {
    accessSecret: process.env.JWT_ACCESS_SECRET!,
    refreshSecret: process.env.JWT_REFRESH_SECRET!,
    accessExpiry: process.env.JWT_ACCESS_EXPIRY || '15m',
    refreshExpiry: process.env.JWT_REFRESH_EXPIRY || '7d',
  },

  features: {
    enable2FA: process.env.ENABLE_2FA === 'true',
    enableAnalytics: process.env.ENABLE_ANALYTICS !== 'false',
  },
};

// Validate required fields
const requiredEnvVars = [
  'DATABASE_URL',
  'JWT_ACCESS_SECRET',
  'JWT_REFRESH_SECRET',
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

export default config;

```

### Step 4: Environment-Specific Configuration Files

**config/environments/development.ts**:

```
export default {
  logging: {
    level: 'debug',
    prettyPrint: true,
  },
  cors: {
    origin: '*',
    credentials: true,
  },
  rateLimit: {
    enabled: false,
  },
};

```

**config/environments/production.ts**:

```
export default {
  logging: {
    level: 'warn',
    prettyPrint: false,
  },
  cors: {
    origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
    credentials: true,
  },
  rateLimit: {
    enabled: true,
    windowMs: 15 * 60 * 1000,
    max: 100,
  },
};

```

**config/index.ts** (unified):

```
import development from './environments/development';
import production from './environments/production';

const env = process.env.NODE_ENV || 'development';

const configs = {
  development,
  production,
  test: development,
};

export const environmentConfig = configs[env];

```

### Step 5: Docker Environment Variables

**docker-compose.yml**:

```
version: '3.8'

services:
  app:
    build: .
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp

  redis:
    image: redis:7-alpine

```

## Output format

```
project/
├── .env.example           # Template (commit)
├── .env                   # Local (gitignore)
├── .env.local             # Per developer (gitignore)
├── .env.production        # Production (gitignore or vault)
├── config/
│   ├── index.ts           # Main configuration
│   ├── env.ts             # Environment variable validation
│   └── environments/
│       ├── development.ts
│       ├── production.ts
│       └── test.ts
└── .gitignore

```

**.gitignore**:

```
.env
.env.local
.env.*.local
.env.production

```

## Constraints

### Required Rules (MUST)

- **Provide .env.example**: List of required environment variables

- **Validation**: Error when required environment variables are missing

- **.gitignore**: Never commit .env files

### Prohibited (MUST NOT)

- **Commit Secrets**: Never commit .env files

- **Hardcoding**: Do not hardcode environment-specific settings in code

## Best practices

- **12 Factor App**: Manage configuration via environment variables

- **Type Safety**: Runtime validation with Zod

- **Secrets Management**: Use AWS Secrets Manager, Vault

## References

- [dotenv](https://github.com/motdotla/dotenv)

- [Zod](https://zod.dev/)

- [12 Factor App - Config](https://12factor.net/config)

## Metadata

### Version

- **Current Version**: 1.0.0

- **Last Updated**: 2025-01-01

- **Compatible Platforms**: Claude, ChatGPT, Gemini

### Tags

`#environment` `#configuration` `#env-variables` `#dotenv` `#config-management` `#utilities`

## Examples

### Example 1: Basic usage

### Example 2: Advanced usage
Weekly Installs10.3KRepository[supercent-io/sk…template](https://github.com/supercent-io/skills-template)GitHub Stars58First SeenJan 24, 2026Security Audits[Gen Agent Trust HubPass](/supercent-io/skills-template/environment-setup/security/agent-trust-hub)[SocketPass](/supercent-io/skills-template/environment-setup/security/socket)[SnykPass](/supercent-io/skills-template/environment-setup/security/snyk)Installed oncodex10.2Kgemini-cli10.2Kopencode10.2Kgithub-copilot10.2Kcursor10.2Kamp10.2K

---
*Source: https://skills.yangsir.net/skill/sm-environment-setup*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-environment-setup/markdown*