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/web/troubleshooting.md (or send Accept: text/markdown).

문제 해결

실제로 실패한 경계에서 설정 문제를 진단하세요.

이 가이드에 대해 질문하기

설치 및 설정

어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.

1. 첫 번째 유용한 오류 줄과 이를 생성한 명령을 복사합니다. 비밀 값을 붙여넣지 마세요.

2. 저장소 루트에서 웹 유형 오류의 경우 corepack pnpm --filter @supastack/web typecheck를 실행하고, 자동화된 제품군의 경우 corepack pnpm test를 실행합니다.

3. 브라우저 문제의 경우 corepack pnpm --filter @supastack/web dev로 웹을 시작하고 http://localhost:3000.에서 재현합니다. 예상: 설정을 변경하기 전에 오류가 설정, 코드, 데이터베이스, 공급자 또는 브라우저에 있는지 알 수 있습니다.

구성을 바꾸기 전에 실패한 명령과 첫 번째 관련 오류를 읽으세요. 실패가 의존성 설치, 컴파일, 환경 검증, 데이터베이스 액세스, 프로바이더 디스패치, 브라우저 동작 중 어디인지 판단하세요.

corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm test

복사 명령

설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.

corepack pnpm --filter @supastack/web typecheck
corepack pnpm test

첫 실행 오류 해독

첫 실행은 몇 가지 방식으로만 실패합니다. 첫 번째 빨간 오류 줄을 표의 행과 맞춰 보세요 — 이후 오류는 대개 첫 번째의 결과이므로 다른 어떤 것보다 맨 위 것을 먼저 고치세요.

증상	가능한 원인	첫 번째 해결책
node, corepack 또는 pnpm이 인식되지 않음 / command not found	도구가 설치되지 않았거나 설치가 끝나기 전에 터미널이 열려 있음	설치(또는 터미널 재실행) 후 node --version을 다시 시도
package.json을 찾을 수 없음 / ENOENT package.json	터미널이 잘못된 폴더에 있음	package.json이 들어 있는 저장소 루트로 cd한 후 다시 시도
EADDRINUSE / 포트 3000이 이미 사용 중	다른 개발 서버가 아직 포트를 점유 중	그 서버의 터미널을 찾아 Ctrl + C를 누른 후 다시 시작
localhost:5432에 대한 ECONNREFUSED 또는 데이터베이스 연결 오류	Postgres가 실행 중이지 않음	docker compose up -d postgres를 실행하고 healthy가 될 때까지 기다린 후 다시 시도
누락된 키를 지목하는 env 검증 오류	apps/web/.env.local이 없거나 필수 값이 비어 있음	.env.example에서 지목된 키를 복사해 값을 넣고 저장한 뒤 서버 재시작
corepack enable 후에도 corepack 또는 pnpm이 없음	PATH에 pnpm shim이 없음	corepack pnpm ...을 직접 사용 — shim이 전혀 필요 없습니다. Windows에서는 corepack.cmd 사용
PowerShell이 .ps1 스크립트를 실행할 수 없음 / 차단됨	PowerShell의 스크립트 정책이 shim을 차단	.cmd 형식 사용 — corepack.cmd pnpm install — 정책 변경 불필요

구현 워크플로

누락된 API 액세스에는 서버가 실행 중이고 구성된 오리진이 클라이언트와 일치하는지 확인하세요. 사용 불가능한 AI 선택에는 AI_MODEL_POLICY와 활성화된 카탈로그 행을 검사하세요. 큐 상태가 불확실한 작업에는 다른 제출 대신 저장된 복구 플로를 사용하세요.

브라우저 레이아웃 문제에는 계산된 스타일을 검사하고 정확한 뷰포트를 재현하세요. 제품 크롬 토큰은 app-theme.css(catalog.ts의 팩)에 있고, 마케팅 브랜드 잠금은 theme.css에 있습니다. 컴포넌트 오버라이드가 여전히 명시도로 이길 수 있습니다. 토큰 선언만이 아니라 렌더링된 반경을 확인하세요.

검증 및 문제 해결

페이지가 :3001에 있으면 웹 앱용으로 :3000을 엽니다. :3001은 별도의 apps/docs 서버에 속합니다. 테스트에서 데이터베이스 액세스를 요청하는 경우 격리된 개발 데이터베이스를 사용하고 두 .env 위치를 모두 확인하세요. 동일한 오류가 계속되면 도움을 요청할 때 명령과 삭제된 첫 번째 오류 줄을 포함하세요. 액세스 확인을 비활성화하거나 로그에 비밀을 인쇄하지 마십시오.

인가를 비활성화하거나, 시크릿을 로깅하거나, 건너뛴 인프라 검사를 성공으로 취급해 실패한 검증을 해결하지 마세요. 작은 재현과 관련된 비민감 구성을 캡처하세요. 수정 후 실패한 검사를 다시 실행한 다음 영향받은 회귀 테스트를 실행하세요.