OpenSkillIndex← back to search
claude-code

Claude-skill-registry env-switch

Safely switch between local and production environments with validation and step-by-step guidance. Use when user wants to "switch to local", "change to production", "separate environments", or "toggle between databases". Prevents accidental production data access.

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/env-switch" ~/.claude/skills/majiayu000-claude-skill-registry-env-switch && rm -rf "$T"
manifest: skills/data/env-switch/SKILL.md
source content

Environment Switcher

로컬 개발 환경과 프로덕션 환경 간 안전한 전환을 도와주는 Skill입니다.

🎯 자동 실행 트리거

다음 상황에서 자동으로 실행:

  • "로컬로 전환" / "Switch to local"
  • "프로덕션으로 전환" / "Switch to production"
  • "환경 분리" / "Separate environments"
  • "주석 처리 말고 자동으로" (지금까지 겪은 문제!)
  • "로컬/프로덕션 전환이 번거로워"

🔍 현재 환경 분석

1. 현재 .env 설정 확인

# 현재 환경 확인
grep -E "^(APP_ENV|APP_NAME|DB_CONNECTION|SESSION_DRIVER|CACHE_STORE)=" .env

환경 판별:

  • APP_ENV=local
    + 
    DB_CONNECTION=pgsql_local
    → 로컬 개발 환경 ✅
  • APP_ENV=production
    + 
    DB_CONNECTION=pgsql
    → 프로덕션 환경 ⚠️
  • 혼합 상태 → 잘못된 설정 ❌

📋 환경별 완벽한 설정

로컬 개발 환경 (.env)

Git에 커밋하지 않음 (.gitignore에 포함됨)

# Application
APP_NAME="YKP ERP (Local)"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

# Local PostgreSQL Database
DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_PORT_LOCAL=5432
DB_DATABASE_LOCAL=ykp_dashboard_local
DB_USERNAME_LOCAL=postgres
DB_PASSWORD_LOCAL=1234  # 본인 로컬 비밀번호

# File-based drivers (빠른 개발)
SESSION_DRIVER=file
SESSION_LIFETIME=120
CACHE_STORE=file
QUEUE_CONNECTION=sync

# Logging
LOG_CHANNEL=stack
LOG_LEVEL=debug

# Feature Flags (로컬 테스트)
FEATURE_EXCEL_INPUT=true
FEATURE_ADVANCED_REPORTS=true
FEATURE_UI_V2=false
FEATURE_SUPABASE_ENHANCED=false

프로덕션 환경 (Railway)

Railway 환경변수 사용 (.env 파일 무시됨!)

# Application
APP_NAME="YKP ERP"
APP_ENV=production
APP_DEBUG=false
APP_URL=${RAILWAY_PUBLIC_DOMAIN}

# Supabase PostgreSQL (Connection Pooler)
DB_CONNECTION=pgsql
DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com
DB_PORT=5432
DB_DATABASE=postgres
DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm
DB_PASSWORD=<Railway Secrets에 저장>
DB_SSLMODE=require

# Database drivers (분산 환경)
SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

# Logging (Railway stderr)
LOG_CHANNEL=stderr
LOG_LEVEL=error

# Feature Flags (프로덕션)
FEATURE_EXCEL_INPUT=true
FEATURE_ADVANCED_REPORTS=true
FEATURE_UI_V2=false
FEATURE_SUPABASE_ENHANCED=true

🔄 전환 절차

시나리오 1: 프로덕션 → 로컬 전환

사용자 요청: "로컬 개발 환경으로 돌아가고 싶어요"

안내 절차:

  1. 현재 상태 확인:

    grep -E "^(APP_ENV|DB_CONNECTION)=" .env

    → 

    APP_ENV=production
    감지 시 경고!

  2. 경고 메시지:

    🚨 프로덕션 설정 감지!

    현재 

    .env
    파일이 프로덕션 설정을 사용하고 있습니다. 로컬 개발용으로 전환하시겠습니까?

    ⚠️ 주의: 프로덕션은 Railway 환경변수로만 관리됩니다!

  3. 로컬 설정 템플릿 제공:

    ✅ 로컬 개발 환경 설정

    .env
    파일을 다음과 같이 수정하세요:

    APP_NAME="YKP ERP (Local)"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_DATABASE_LOCAL=ykp_dashboard_local
DB_USERNAME_LOCAL=postgres
DB_PASSWORD_LOCAL=1234

SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=sync

    또는 

    .env.example
    파일을 복사:

    cp .env.example .env
php artisan key:generate

  4. 후속 조치 안내:

    📋 다음 단계:

1. PostgreSQL 서버 시작:
   postgresql-17.6-2-windows-x64-binaries/bin/pg_ctl.exe -D postgresql-data start

2. 캐시 클리어:
   php artisan optimize:clear

3. 서버 재시작:
   php artisan serve

4. 테스트 로그인:
   http://127.0.0.1:8000
   계정: admin@ykp.com / password

시나리오 2: 로컬 → 프로덕션 배포 준비

사용자 요청: "Railway에 배포하려고 하는데, 프로덕션 설정 확인해줘"

안내 절차:

  1. 로컬 .env 상태 확인:

    ✅ 로컬 환경 감지

    현재 

    .env
    파일: 로컬 개발 설정 (정상) Git에 커밋되지 않음 (
    .gitignore
    로 보호됨)

  2. Railway 환경변수 체크리스트 제공:

    📋 Railway 배포 체크리스트

    Railway Dashboard → Your Service → Variables에 다음 설정:

    필수 환경변수:

    • APP_NAME="YKP ERP"
    • APP_ENV=production
    • APP_KEY=<php artisan key:generate --show 출력>
    • APP_DEBUG=false
    • APP_URL=${RAILWAY_PUBLIC_DOMAIN}

    Supabase DB (Railway Secrets에 저장):

    • DB_CONNECTION=pgsql
    • DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com
    • DB_PORT=5432
    • DB_DATABASE=postgres
    • DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm
    • DB_PASSWORD=<Supabase 비밀번호>
      🔒
    • DB_SSLMODE=require

    Session/Cache/Queue:

    • SESSION_DRIVER=database
    • CACHE_STORE=database
    • QUEUE_CONNECTION=database

    Logging:

    • LOG_CHANNEL=stderr
    • LOG_LEVEL=error

  3. 보안 경고:

    🔒 보안 주의사항

    ❌ 

    .env
    파일을 Git에 커밋하지 마세요! ✅ Railway 환경변수에서 관리 ✅ 
    DB_PASSWORD
    는 Railway Secrets에 저장 ✅ Supabase 백업 생성 후 배포

🚨 잘못된 설정 감지

혼합 설정 (가장 위험!)

증상: 

APP_ENV=local
인데 
DB_CONNECTION=pgsql
(Supabase)

경고 메시지:

🚨 위험: 환경 설정 불일치!

현재 설정:
- APP_ENV: local (로컬 개발 모드)
- DB_CONNECTION: pgsql (Supabase 프로덕션 DB!)

⚠️ 이 상태로 작업하면 프로덕션 데이터에 영향을 줄 수 있습니다!

즉시 수정:
APP_ENV=local → DB_CONNECTION=pgsql_local 사용해야 함!

.env 파일 수정:
DB_CONNECTION=pgsql_local
DB_DATABASE_LOCAL=ykp_dashboard_local

수정 후:
php artisan optimize:clear

💡 환경 분리 베스트 프랙티스

절대 규칙

  1. 로컬 개발:

    • ✅ 
      .env
      파일 사용 (Git ignored)
    • ✅ 
      APP_ENV=local
    • ✅ 
      DB_CONNECTION=pgsql_local
    • ✅ File-based drivers (session/cache/queue)

  2. 프로덕션 (Railway):

    • ✅ Railway 환경변수 사용
    • ✅ 
      .env
      파일 무시됨
    • ✅ 
      APP_ENV=production
    • ✅ 
      DB_CONNECTION=pgsql
      (Supabase)
    • ✅ Database drivers (분산 환경)

  3. 금지 사항:

    • ❌ 
      .env
      파일을 Git에 커밋
    • ❌ 주석 처리로 환경 전환
    • ❌ 
      .env.local
      사용 (Laravel 작동 안함!)
    • ❌ 프로덕션 DB를 로컬에서 직접 연결

왜 
.env.local
은 안되나?

문제 발견 과정 (지금까지 대화 기반):

시도 1: .env에 프로덕션 설정, .env.local에 로컬 설정
결과: ❌ Laravel이 .env.local 무시함

이유: Laravel은 APP_ENV=production일 때 .env.local을 로드하지 않음
→ 닭이 먼저냐 달걀이 먼저냐 문제!

올바른 해결책:

  • 로컬: 
    .env
    (Git ignored)
  • 프로덕션: Railway 환경변수 (파일 아님!)

📊 전환 완료 보고서

전환 완료 후 다음 형식으로 보고:

✅ 환경 전환 완료

이전 환경: production (Supabase)
새 환경: local (localhost PostgreSQL)

변경된 설정:
- APP_ENV: production → local
- DB_CONNECTION: pgsql → pgsql_local
- SESSION_DRIVER: database → file
- CACHE_STORE: database → file

✅ 캐시 클리어: 완료
✅ 환경 검증: 통과

📋 다음 단계:
1. 서버 재시작: php artisan serve
2. 로그인 테스트: http://127.0.0.1:8000
3. DB 연결 확인: admin@ykp.com / password

💡 프로덕션 배포 시:
- Railway 환경변수 사용 (`.env` 파일 무시)
- CLAUDE.md "Railway Production Environment" 섹션 참조

🎓 학습 내용 요약

이 Skill을 통해 배운 핵심:

  1. Laravel 환경 파일 우선순위:

    • .env
      > 
      .env.local
      (단, production 모드에서는 .env.local 무시!)
    • Railway 환경변수 > 
      .env
      파일

  2. 환경별 드라이버 전략:

    • 로컬: File-based (빠름, 독립적)
    • 프로덕션: Database-based (분산 환경)

  3. Git 관리 전략:

    • .env
      → Git ignored (로컬 비밀정보 포함)
    • .env.example
      → Git tracked (템플릿)
    • .env.production.example
      → Git tracked (가이드)
    • Railway 환경변수 → 플랫폼 관리

다음에 환경 전환 필요 시:

  1. 절대 주석 처리 금지!
  2. .env
    파일 전체 교체
  3. 캐시 클리어 (
    php artisan optimize:clear
    )
  4. 서버 재시작