배포

내 컴퓨터에서는 되는데 배포하면 안 될 때 — 순서대로 확인하는 여섯 칸

오일기 · 한국이러닝인재개발원 원장 · 2026-09-23

추측하지 않습니다. 저장 → 올리기 → 배포 → 주소 → 설정 → 바깥 연결. 어느 칸에서 끊겼는지 사실로 바꾸면 대부분 10분 안에 끝납니다.

"로컬에서는 되는데 배포하면 안 돼요." 배포를 처음 해 본 사람이 반드시 한 번은 겪는 말입니다. 원인은 여러 가지지만 찾는 방법은 하나입니다. 추측하지 말고, 순서대로 어느 칸에서 끊겼는지 확인합니다.

먼저 용어 하나. localhost(내 컴퓨터에서만 열리는 주소)와 배포 주소(누구나 여는 ○○.vercel.app)는 다른 컴퓨터입니다. 내 노트북에 있는 것이 저절로 저쪽에 가지 않습니다. 사이에 여섯 칸이 있습니다.

여섯 칸

위에서부터 순서대로 봅니다. ①에서 끊겼는데 ⑤를 뒤지면 하루가 갑니다.

가장 흔한 순서대로

① 저장이 안 됐다. 고친 게 내 컴퓨터에만 있습니다. 가장 흔합니다. "GitHub에 올려줘"라고 했는데 실제로 커밋이 안 됐거나, 다른 폴더를 올렸거나. 창 제목의 폴더 이름부터 확인합니다.

② 올리기가 실패했다. rejected, not found 같은 메시지가 지나갔는데 못 봤습니다. GitHub 페이지에서 최신 파일이 안 보이면 여기입니다. 메시지를 통째로 복사해 Claude에게.

③ 배포가 실패했다. 사이트가 망가진 게 아니라 설정 한 칸의 문제인 경우가 대부분입니다. Vercel이 사이트 종류를 잘못 추측했으면 Settings → Build and Deployment → Framework Preset을 Other로 바꾸고 다시 배포. 실패한 배포를 눌러 로그를 복사하면 원인이 적혀 있습니다.

④ 옛 화면이 보인다. 브라우저가 기억한 화면입니다. 잠시 뒤 새로고침. 그래도 그대로면 ③으로 돌아갑니다.

⑤ 설정이 다르다. 내 컴퓨터의 .env 파일에 적어 둔 값(API 키 등)은 GitHub에 안 올라갑니다. 올리면 안 되니까요. 그래서 Vercel 설정 화면에 따로 넣어야 합니다. 한 페이지 홈페이지에는 해당 없고, 바깥 서비스를 붙인 뒤부터 나옵니다.

⑥ 바깥 서비스가 내 주소를 모른다. 코드에 localhost:3000 같은 주소가 남아 있거나, 로그인·DB 서비스에 내 배포 주소를 허용 목록으로 등록하지 않은 경우. 첫 서비스에서는 드물고, 로그인을 붙이는 단계에서 만납니다.

Claude에게 시킬 때

내 컴퓨터에서는 되는데 배포 주소에서는 안 돼.
아래 순서로 하나씩 확인하고, 각 단계가 확인됐는지 아닌지 알려줘.
1) 저장 안 된 변경이 있는지
2) GitHub 최신 커밋과 내 폴더가 같은지
3) Vercel 마지막 배포가 성공했는지 (실패면 로그)
4) 코드에 localhost 주소가 남아 있는지
5) .env 값 중 Vercel 설정에 없는 게 있는지
추측으로 고치지 말고, 확인된 것만 말해줘.

원칙

각 칸을 "아마 됐겠지"에서 "확인했다"로 바꾸는 것. 그게 전부입니다. 배포는 마법이 아니라 작업실 → 창고 → 매장 → 간판의 순서고, 어느 문이 안 열렸는지 보면 됩니다.

같이 읽기

• 에러 메시지로 AI와 디버깅하기 — 요약하지 말고 통째로빨간 글씨는 협박문이 아니라 "여기가 문제"라는 안내문입니다. 어디서 보이고, 뭘 가져가고, 어떻게 시키는지. 오류 설명 공식 네 칸.만들기 · 배포
• Git·GitHub이 뭔지 — '최종_진짜최종(2)'를 없애는 도구Git은 내 컴퓨터의 버전 기록기, GitHub은 그 기록을 올려 두는 인터넷 창고. 커밋·푸시·브랜치를 가게 비유로. 명령어는 Claude가 칩니다.배포
• API 키는 어디에 두나 — 파일·Git·Vercel 환경변수API 키 = 비밀번호. 홈페이지 파일·GitHub·채팅·캡처 어디에도 안 넣습니다. 그럼 어디에? .env와 배포 설정, 그리고 새었을 때 할 일.배포 · 데이터·보안