내 컴퓨터에서는 되는데 배포하면 안 된다면? 무엇부터 확인해야 할까요?

바이브코딩으로 만든 앱을 내 컴퓨터에서 확인했습니다. 로그인도 되고, 저장 버튼도 작동하고, 이메일도 잘 옵니다. 그런데 배포한 주소를 열었더니 같은 기능이 안 됩니다.

localhost에서는 되는데
배포한 사이트에서는 안 돼요.

이때 바로 코드를 고치기 시작하기 쉽습니다. AI에게 오류를 설명하면 CORS, 데이터베이스 권한, 서버 설정처럼 여러 가능성을 한꺼번에 제시하기도 해요.

하지만 가장 먼저 확인할 것은 더 단순합니다.

내 컴퓨터에서 확인한 코드와 지금 서비스에 배포한 코드가 정말 같은가요?

로컬에서 잘 된다는 사실은 현재 내 컴퓨터에 있는 상태가 잘 작동한다는 뜻일 뿐입니다. 잘 작동한 상태를 커밋하고, GitHub에 올리고, 배포까지 마쳤다는 뜻은 아니에요.

따라서 배포 문제는 가능한 원인을 마구 떠올리기보다 코드가 이동하는 경로를 순서대로 따라가며 확인하는 편이 빠릅니다.

내 컴퓨터의 코드
→ 커밋
→ GitHub에 push
→ 배포 서비스가 최신 커밋으로 빌드
→ 완성한 배포를 실제 도메인에 연결
→ 배포 환경의 설정으로 실행

앞 단계가 확인되지 않았다면 뒤 단계부터 조사할 이유가 없습니다. 하나씩 살펴볼게요.

1. 내 컴퓨터에서 잘 된 변경이 코드에 남아 있나요?

먼저 내가 localhost에서 어떤 상태를 확인했는지 알아야 합니다.

AI와 기능을 수정한 뒤 브라우저에서 잘 작동하는 것까지 확인했더라도 변경 내용이 아직 내 컴퓨터에만 있을 수 있어요. Git은 파일을 수정했다고 자동으로 수정 내용을 배포용 기록에 넣지 않습니다.

이걸 확인하려고 터미널 명령어를 외울 필요는 없습니다. 작업 중인 AI에게 이렇게 요청하세요.

내 컴퓨터에는 있지만 아직 커밋하지 않은 변경이 있는지 확인해줘.
이번에 만든 기능과 관련된 파일이 빠지지 않았는지도 쉽게 설명해줘.
지금은 아무것도 수정하거나 커밋하지 마.

AI가 수정한 파일이나 새 파일이 남아 있다고 알려준다면 아직 커밋하지 않은 변경이 있다는 뜻입니다.

localhost가 보는 것
→ 내 폴더의 현재 파일 전체

배포 서비스가 보는 것
→ 보통 GitHub에 올라간 커밋

이 둘은 다를 수 있어요. 예를 들어 로그인 오류를 고친 파일이 내 컴퓨터에만 남아 있다면 localhost는 고친 코드를 사용하지만 배포 서비스는 아직 이전 코드를 사용합니다.

새로 만든 파일을 Git이 추적하지 않는 경우도 확인해야 합니다. AI가 만든 API 파일을 커밋에 포함하지 않았다면 로컬에는 경로가 있고 배포본에는 경로가 없을 수 있어요.

반대로 내 컴퓨터에서 임시로 바꾼 내용까지 전부 올리면 안 됩니다. AI에게 이번 기능에 필요한 변경과 관계없는 변경을 나눠서 설명해달라고 하세요. 확인하기 전에는 모든 파일을 한꺼번에 커밋해달라고 하지 않는 편이 안전합니다.

2. 변경 내용을 커밋했나요?

커밋은 특정 시점의 코드를 하나의 기록으로 묶는 일입니다. 배포 서비스는 대개 이 기록을 기준으로 어떤 버전을 만들지 결정해요.

AI에게 최근 커밋이 무엇인지 확인해달라고 하면 커밋을 구분하는 짧은 문자와 설명을 알려줍니다.

a1b2c3d 로그인 오류 수정

여기서 중요한 것은 “커밋을 하나 만들었는가”만이 아닙니다. 내 컴퓨터에서 잘 된 변경을 최근 커밋에 포함했는가를 확인해야 해요.

파일 수정
→ localhost에서 확인
→ 필요한 변경을 선택
→ 커밋

커밋한 뒤에 다시 파일을 수정했다면 localhost는 커밋보다 더 새로운 상태를 보여줍니다. 따라서 AI에게 최근 커밋 뒤에 다시 바꾼 파일이 있는지도 함께 확인해달라고 해야 해요.

Git과 GitHub의 역할이 아직 낯설다면 Git과 GitHub를 꼭 써야 하는 이유를 먼저 읽어도 좋습니다. commit과 push의 차이는 내 코드가 GitHub를 오가는 기본 흐름에서 더 자세히 설명했습니다.

3. 커밋을 GitHub에 push했나요?

커밋은 처음에는 내 컴퓨터에만 만들어집니다. 커밋까지 했더라도 push하지 않았다면 GitHub에는 올라가지 않았어요.

commit
→ 내 컴퓨터의 Git 기록에 저장

push
→ 커밋을 GitHub 같은 원격 저장소로 전송

배포 서비스가 GitHub와 연결되어 있다면 내 컴퓨터를 직접 읽지 않습니다. GitHub에 도착한 커밋을 보고 배포를 시작해요.

이 비교도 AI에게 맡길 수 있습니다.

내 컴퓨터의 최신 커밋이 GitHub에도 올라갔는지 확인해줘.
두 곳의 커밋이 다르면 무엇이 빠졌는지 설명만 해줘.
아직 push하거나 코드를 바꾸지는 마.

AI는 다음 두 곳의 최신 커밋을 비교합니다.

내 컴퓨터의 최신 커밋
↕ 비교
GitHub 저장소의 최신 커밋

커밋 메시지만 같다고 판단하기보다 커밋을 구분하는 문자까지 비교하는 편이 확실합니다.

또 하나 확인할 것은 브랜치입니다. 브랜치는 여러 버전의 작업을 나눠두는 공간이에요. 내 컴퓨터에서는 새 기능을 만드는 공간에서 작업했는데 배포 서비스는 main이라는 운영 공간만 보고 있을 수 있어요.

내 변경이 어느 브랜치에 있고 배포 서비스는 어느 브랜치를 보고 있는지도 AI에게 함께 확인해달라고 하세요.

내 변경: feature/login-fix
실제 배포 기준: main

이 상태에서 기능 브랜치에 push만 해서는 실제 서비스가 바뀌지 않을 수 있습니다. 배포용 브랜치에 변경이 합쳐졌는지도 확인해야 해요.

4. 배포 서비스가 최신 커밋을 실제로 배포했나요?

GitHub에 최신 커밋이 있다고 해서 배포까지 성공했다는 뜻은 아닙니다.

보통 push 뒤에는 다음 과정이 이어집니다.

GitHub에 새 커밋 도착
→ 배포 서비스가 감지
→ 의존성 설치
→ 프로젝트 빌드
→ 성공한 결과를 배포

중간에 빌드가 실패하면 이전 버전은 계속 열리지만 새 버전은 반영되지 않을 수 있어요. 사이트 주소가 정상적으로 열린다는 이유만으로 최신 배포가 성공했다고 생각하면 안 됩니다.

AI에게 배포 상태를 확인해달라고 하거나, 배포 서비스의 프로젝트 화면에서 다음 내용을 확인하세요.

• 최신 배포가 성공 상태인가요?
• 배포 서비스가 보여주는 커밋이 GitHub의 최신 커밋과 같은가요?
• 배포 서비스가 가져온 브랜치가 내가 의도한 브랜치인가요?
• 실패했다면 빌드 로그의 첫 번째 오류는 무엇인가요? 빨간 메시지가 낯설다면 Warning과 Error를 확인하는 기본 방법을 먼저 읽어보세요.

핵심은 세 곳을 한 줄로 맞추는 것입니다.

로컬 최신 커밋
= GitHub 최신 커밋
= 배포 서비스가 사용한 커밋

셋 중 하나라도 다르면 아직 앱 기능을 디버깅할 단계가 아닙니다. 먼저 같은 코드를 보고 있는 상태부터 만들어야 해요.

5. 내가 연 주소가 최신 배포를 가리키나요?

배포 서비스는 커밋마다 미리보기 주소를 만들고, 실제 도메인에는 운영 배포만 연결하기도 합니다.

기능 브랜치의 미리보기에서는 새 기능이 보이는데 실제 도메인에서는 이전 화면이 보인다면 코드 문제가 아니라 서로 다른 배포를 열어보고 있는 것일 수 있어요.

미리보기 주소
→ 기능 브랜치의 새 배포

실제 도메인
→ main 브랜치의 운영 배포

배포 화면에서 실제 도메인이 어느 배포를 가리키는지 확인하세요. 브라우저 캐시 때문에 예전 화면이 남아 있는 것처럼 보일 수도 있으므로 새로고침하거나 시크릿 창에서 확인하는 것도 도움이 됩니다. 다만 캐시를 지우는 것보다 먼저 배포 커밋이 맞는지 확인하는 편이 우선입니다.

여기까지 확인했다면 이제 이렇게 말할 수 있습니다.

로컬과 배포가 같은 코드다.
같은 코드로 빌드도 성공했다.
실제 주소도 최신 배포를 보고 있다.
하지만 동작은 다르다.

이제부터는 코드가 아니라 실행 환경의 차이를 확인할 차례입니다.

6. 배포 환경변수가 빠지거나 다르지 않나요?

로컬에서는 .env 파일에 데이터베이스 주소, API 키, 사이트 주소 같은 값을 넣습니다. 하지만 .env는 보안을 위해 보통 GitHub에 올리지 않아요.

로컬 코드
→ 내 컴퓨터의 .env 사용

배포한 코드
→ 배포 서비스에 등록한 환경변수 사용

코드는 같아도 환경변수가 다르면 전혀 다른 곳에 연결되거나 기능이 멈출 수 있습니다.

예를 들면 다음과 같습니다.

• 이메일 API 키가 배포 환경에는 없다.
• 변수 이름의 철자나 대소문자가 다르다.
• 테스트용 키와 운영용 키가 뒤바뀌었다.
• SITE_URL이 아직 http://localhost:3000이다.
• 환경변수를 Preview에만 넣고 Production에는 넣지 않았다.
• 값을 추가했지만 새 환경변수를 읽을 배포를 다시 만들지 않았다.

환경변수는 값 자체를 공개하지 말고 이름, 적용 환경, 마지막 변경 시점을 비교하세요. 비밀키를 채팅이나 화면 캡처에 그대로 노출하면 안 됩니다.

또 많은 서비스가 새 환경변수를 반영하려면 다시 배포해야 합니다. 값을 등록했다고 해서 현재 서비스가 바로 새 값을 사용하는 것은 아니에요.

환경변수의 역할은 API 키와 .env에서, 개발과 운영에 서로 다른 데이터베이스 값을 두는 이유는 개발·운영 데이터베이스를 나눠야 하는 이유에서 더 자세히 설명했습니다.

정리

내 컴퓨터에서 잘 작동한 기능이 배포한 사이트에서 안 된다면 복잡한 원인부터 찾지 마세요.

내 컴퓨터에 변경이 남아 있는가?
→ 필요한 변경을 커밋했는가?
→ 최신 커밋을 GitHub에 올렸는가?
→ 배포 서비스가 최신 커밋을 사용했는가?
→ 실제 주소가 최신 배포를 보여주는가?
→ 배포 환경변수가 빠지거나 다르지 않은가?

AI에게 이 순서대로 확인해달라고 요청하면 됩니다. 각 단계를 추측으로 넘기지 않고 확인한 사실로 바꾸면, 막연했던 배포 오류를 훨씬 빠르게 좁힐 수 있어요.

처음 배포하는 과정 자체가 낯설다면 localhost와 배포의 차이와 바이브코딩 가이드 13장의 배포 실습을 함께 참고하세요.

배포 오류는 프로젝트마다 코드와 환경변수가 달라 녹화된 예제와 똑같이 해결되지 않는 경우가 많습니다. 뚝딱의 오프라인 바이브코딩 강의에서는 수강생의 실제 배포 화면, GitHub 상태와 로그를 함께 확인해 원인을 좁힙니다.