TROUBLESHOOTING.md — 막혔을 때

🗣️ 강사 멘트: “막히면 손 드세요. 혼자 5분 이상 붙잡고 있지 마세요.”

철칙: 3분 규칙. 3분 안에 안 풀리면 아래 우회로로 갑니다. 오늘 목표는 완벽이 아니라 완성입니다.

🔴 최우선 대응표 (강사용)

신호	시점	대응
Copilot 활성화가 안 됨	모듈 02에서 5분 초과	백업 저장소 Fork (아래 A)
“요청 한도 초과”	언제든	모듈별 완성본 Gist 붙여넣기 (아래 B)
결제수단 없음	모듈 05	`xxx.netlify.app` 으로 마무리. 도메인은 집에서
도메인이 안 열림	모듈 05	정상. DNS 전파 대기 안내
github.dev 로딩 실패	언제든	모바일 핫스팟 / 옆자리와 화면 공유

A. Copilot 계정·활성화 문제

A-1. Copilot Chat 패널이 안 보여요

왼쪽 사이드바 맨 아래 말풍선 아이콘 클릭
그래도 없으면 브라우저 새로고침(F5)
그래도 없으면 → github.com/settings/copilot 에서 Free 플랜이 켜져 있는지 확인

A-2. Copilot Free 활성화가 안 돼요

GitHub 가입 직후에는 몇 분 지연될 수 있습니다.
이메일 인증을 마쳤는지 확인하세요. (가입 메일의 인증 링크)
5분 넘게 안 되면 → A-3 으로 바로 넘어가세요. 기다리지 마세요.

A-3. 🚨 우회로 — 백업 저장소 Fork

Copilot 없이도 오늘 목표(내 주소 갖고 가기)는 달성할 수 있습니다.

강사가 안내하는 백업 저장소 주소로 이동 https://github.com/(강사계정)/homepage-backup

📌 강사님: 행사 전에 이 주소를 채워 넣으세요.
오른쪽 위 Fork → Create fork
내 계정에 저장소가 복사됩니다
주소창의 github.com → github.dev 로 바꿔서 편집기 열기
index.html 을 열고, 텍스트만 직접 고칩니다
- 이름, 소개, 경력, 글 제목, 유튜브 ID
- 코드는 건드리지 않고 따옴표 안 글자만 바꾸면 됩니다
저장 → DEPLOY.md 1단계로

B. 채팅 한도 소진 (“요청 한도 초과”)

Copilot Free 채팅은 월 50회입니다. 다음 달 1일에 초기화됩니다.

B-1. 먼저 확인

github.com/settings/copilot 에서 남은 횟수 확인

B-2. 🚨 우회로 — 모듈별 완성본 붙여넣기

강사가 준비한 Gist 에서 필요한 조각을 복사해 붙여넣습니다. Copilot 없이 손으로 붙이면 됩니다.

필요한 것	Gist 주소
P1 뼈대 전체 (index.html)	`(강사님: 여기에 Gist 주소)`
P2 소개 섹션	`(주소)`
P3 경력 아코디언	`(주소)`
P4 커뮤니티	`(주소)`
P5 기록 카드	`(주소)`
P6 음악	`(주소)`
P7 연락 + 푸터	`(주소)`

📌 강사님 준비: 행사 전에 P1~P7을 직접 실행해 결과물을 Gist 7개로 올려두세요. 이게 오늘의 가장 확실한 보험입니다. 최소 P1은 반드시 준비하세요.

B-3. 한도를 아끼는 습관

❌ “고마워요!”, “네”, “다시 해주세요” → 전부 1회씩 소진
❌ 같은 요청을 조금 바꿔 반복 → 2~3회 순삭
✅ PROMPTS.md 의 프롬프트만 쓰기
✅ 인라인 제안(회색 글씨 → Tab) 은 채팅 횟수에 안 들어갑니다

C. 화면·저장 문제

C-1. github.dev 가 안 열려요 / 하얀 화면

새로고침 (F5)
시크릿 창에서 다시 시도
현장 Wi-Fi 문제일 수 있음 → 휴대폰 핫스팟으로 전환
그래도 안 되면 → 옆 사람 화면을 같이 보며 따라오세요. 나중에 집에서 완성 가능합니다.

C-2. 저장이 안 돼요 / 변경사항이 안 보여요

github.dev 는 저장(Ctrl+S)만으로는 GitHub에 올라가지 않습니다.

왼쪽 사이드바 소스 제어 아이콘 (가지 모양, 숫자 배지가 붙어 있음)
메시지 칸에 아무 글자나 입력 (예: 수정)
Commit & Push 버튼 클릭

✅ 이걸 해야 Netlify에도 반영됩니다.

C-3. 미리보기가 안 보여요

index.html 파일에서 우클릭 → Open Preview
없으면 그냥 배포 후 실제 주소에서 확인하세요. (더 정확합니다)

D. 결과물이 이상할 때

D-1. 화면이 통째로 깨졌어요

되돌리기가 가장 빠릅니다.

편집기에서 Ctrl+Z 를 여러 번 (아직 커밋 안 했다면)
이미 커밋했다면 → GitHub 저장소 → index.html → 오른쪽 위 History → 잘 되던 시점 → ... → Revert

D-2. 프로필 사진이 안 보여요

파일 이름이 정확히 profile.jpg 인가? (Profile.JPG ❌ — 대소문자 구분합니다)
저장소 맨 위 폴더(루트) 에 있는가?
커밋 & 푸시를 했는가?
그래도 안 되면 → 오늘은 그냥 두세요. 이니셜 원형이 대신 나옵니다.

D-3. 메뉴를 눌러도 안 움직여요

PROMPTS.md P14 사용:

index.html 에서 상단 메뉴 (음악) 링크를 눌러도 해당 섹션으로 이동하지 않아.
href 앵커와 section id가 맞는지 확인하고 고쳐줘. 고친 부분만 알려줘.

D-4. 휴대폰에서 글자가 개미만 해요

<head> 에 viewport 태그가 빠진 것입니다. 아래 한 줄을 <head> 안에 직접 붙여넣으세요.

<meta name="viewport" content="width=device-width, initial-scale=1.0">

D-5. 음악이 안 나와요

Suno 곡인 경우

곡 ID를 넣었는지 확인하세요. 공유 주소(suno.com/s/...)를 브라우저에서 열면 suno.com/song/곡ID?sh=... 로 바뀝니다. 이 곡 ID를 씁니다.
커버는 cdn2.suno.ai/image_large_곡ID.jpeg, 음원은 cdn1.suno.ai/곡ID.mp3 입니다. 두 주소의 형식이 다르니 헷갈리지 마세요.
곡이 비공개면 재생되지 않습니다. Suno에서 공개로 바꾸세요.
아이폰 사파리는 화면을 한 번도 누르지 않은 상태에서는 재생을 막습니다. 카드를 직접 눌러서 재생하면 정상입니다.

유튜브 곡인 경우

영상 ID만 넣었는지 확인 (https://... 전체 주소 ❌)
- https://www.youtube.com/watch?v= dQw4w9WgXcQ ← 굵은 부분만
일부 영상은 소유자가 외부 재생을 막아둡니다. 다른 곡으로 바꾸세요.

E. 배포 · 도메인 문제

E-1. Netlify 저장소 목록에 내 저장소가 없어요

Configure the Netlify app on GitHub 클릭 → 저장소 선택(또는 All repositories) → Save

E-2. 배포는 됐는데 하얀 화면이에요

파일 이름이 정확히 index.html 인가? (Index.html, index.htm ❌)
저장소 루트에 있는가? (하위 폴더에 있으면 Publish directory에 폴더명 입력)

E-3. 도메인이 안 열려요

대부분 정상입니다. DNS 전파에 수 분~하루가 걸립니다.

하루가 지나도 안 되면 확인할 것:

확인	흔한 실수
CNAME 값	끝에 점(`.`) 또는 `https://` 를 붙임
CNAME 호스트	`www` 대신 `www.내도메인.com` 전체를 입력
A 레코드 호스트	`@` 대신 빈칸 또는 도메인 전체
Netlify	`Verify DNS configuration` 을 안 눌렀음

확인 도구: dnschecker.org

E-4. “안전하지 않음” 경고가 떠요

HTTPS 인증서가 아직 발급 중입니다. DNS 전파 후 자동으로 발급됩니다. Netlify → Domain management → HTTPS → Verify DNS configuration 을 한 번 눌러주세요.

🏁 최후의 수단 — 오늘 이것만은

시간이 다 되어도, Copilot이 안 되어도, 도메인을 못 사도 — 아래 3개 중 하나는 반드시 들고 가세요.

✅ xxx.netlify.app 주소 (도메인 없이도 진짜 홈페이지)
✅ Fork한 백업 저장소에 내 이름·소개만 바꾼 상태
✅ 완성한 content.md (집에서 10분이면 끝낼 수 있는 상태)

🗣️ 강사 멘트: “오늘 못 끝내도 괜찮습니다. content.md 만 채워두면 집에서 30분이면 완성됩니다. 필요하면 커뮤니티에 물어보세요.”