For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/modules/config.md (or send Accept: text/markdown).

환경과 설정

워크스페이스 전체를 위한 단일 검증 스키마.

이 가이드에 대해 질문하기

구성을 한 번 변경하고 확인하세요.

실행 중인 웹 앱으로 시작하세요. 편집기에서 apps/web/.env.local를 엽니다. 존재하지 않는 경우 웹 튜토리얼을 사용하여 .env.example을 복사하십시오. 무해한 첫 번째 확인을 위해 EMAIL_PROVIDER=local를 찾아서 로컬에 두십시오. 이 설정은 실제 받은 편지함 대신 로컬 미리 보기로 제품 이메일을 보냅니다. KEY=value 라인을 터미널에 붙여넣지 마십시오.

활성화한 각 서비스에 대해 해당 공급자의 설정 가이드에 따라 명명된 값만 바꾸고 파일을 저장한 후 Ctrl + C를 사용하여 웹 서버를 중지하고 아래 명령을 사용하여 다시 시작하세요. 유효성 검사에서 누락된 키의 이름이 지정되면 이 파일을 다시 열고 해당 키를 공급자 가이드와 비교하세요. 데이터베이스 마이그레이션에 사용되는 값에 대해서만 루트 .env를 동기화된 상태로 유지하세요. 단독으로 복사하면 Next.js가 구성되지 않습니다.

corepack pnpm --filter @supastack/web dev

환경 예제부터 시작

루트 .env.example이 구성 목록입니다. 공유 검증은 packages/config에 있습니다. 선택한 앱 환경과 프로바이더 모드를 함께 검토하세요. 로컬 인터페이스는 프로덕션 자격 증명 전략이 아닙니다.

자격 증명 없는 참조 모드는 local/test 앱 설정과 fake/로컬 프로바이더를 요구합니다. 프로덕션 프로바이더를 선택하면 런타임 요구 사항이 바뀝니다.

시크릿을 API 뒤에 유지

인증 시크릿, 데이터베이스 자격 증명, 프로바이더 키, Stripe 시크릿, Trigger 자격 증명은 서버 전용입니다. NEXT_PUBLIC_ 또는 EXPO_PUBLIC_ 접두사를 붙이지 마세요. 설치 중에 표시하거나 오류 응답에 포함하지 마세요.

브라우저는 공개 구성과 허용된 모델 별칭을 받습니다. 워크스페이스 소유권, 권한 결정, 예산, 프로바이더 선택은 서버에서 강제된 상태로 유지됩니다.

사용하기 전에 변경 사항 검증

기존 config 패키지를 통해 구성을 검증하고 관련 결정적 테스트를 실행하세요. 실제 통합을 검증할 준비가 되면 별도의 옵트인 프로바이더 스모크 경로를 사용하세요.

corepack pnpm test
corepack pnpm check
corepack pnpm build

설치 및 설정

packages/config가 process.env를 파싱하는 유일한 곳입니다: zod 스키마가 타입화된 ServerConfig와 PublicConfig를 생성하고, 프로바이더 선택은 kinds로 표현됩니다 — providers.ai, providers.billing, providers.email, providers.jobs, providers.storage가 각각 명명된 어댑터와 필수 필드로 해석됩니다.

프로바이더를 활성화하면 해당 자격 증명이 필수가 됩니다: 소셜 로그인, s3 스토리지 kind, resend 이메일 kind를 켜면 누락된 변수 이름을 지목하며 시작이 실패합니다 — 나중의 런타임 놀람이 아니라.

STORAGE_PROVIDER=s3
STORAGE_BUCKET=kit
STORAGE_ENDPOINT=https://s3.example
STORAGE_PUBLIC_BASE_URL=https://cdn.example
# → config rejects the env if a required field is missing

구현 워크플로

설정은 서버 경계에서 parseServerConfig로 읽고 타입화된 값을 안쪽으로 전달하세요 — 기능 코드 안에서 process.env를 건드리지 마세요. 공개 설정은 별도의, 의도적으로 작은 객체로 클라이언트에 안전하게 직렬화됩니다.

프로덕트 전용 env는 소비 프로덕트 자체의 스키마에 속합니다. 한 프로덕트의 필요를 위해 키트 스키마를 부풀리지 마세요.

검증 및 문제 해결

스키마 변경 후 config 패키지 테스트를 실행하고, 누락된 필수 변수가 오류에서 스스로를 이름 지어 나타내는지 확인합니다. 로컬에서는 파싱되지만 프로덕션에서 안 되는 env는 보통 문서화되지 않은 필수 필드를 의미합니다.