저장과 빌드와 배포를 포장 배송 공개처럼 구분하기

코드를 저장했는데 사이트가 바뀌지 않거나, 배포 성공 알림을 받았는데 공개 주소에는 옛 화면이 남는 일이 있습니다. 저장, 빌드, 배포, 공개 확인을 한 단계로 생각하면 어디에서 멈췄는지 찾기 어렵습니다. 각 상태는 다음 단계의 재료일 뿐 결과를 자동으로 보장하지 않습니다.

온라인 쇼핑에 비유하면 저장은 주문 내용을 적는 일, 빌드는 물건을 포장하는 일, 배포는 배송하는 일, 공개 확인은 수령인이 실제 상자를 열어 주문한 물건인지 보는 일과 같습니다. 포장 완료와 배송 완료가 서로 다른 것처럼 빌드 성공과 공개 반영도 다릅니다.

저장은 작업 파일을 남기는 단계다

편집기에서 저장하면 로컬 컴퓨터의 파일이 바뀝니다. Git 커밋은 그 변경 묶음을 다시 찾을 수 있게 기록하지만 서버로 보내는 동작은 아닙니다. 원격 저장소에 push해도 배포 서비스가 연결돼 있지 않거나 빌드가 실패하면 공개 사이트는 바뀌지 않습니다.

먼저 어떤 파일이 바뀌었는지 Git diff로 봅니다. 생성 파일, 환경 설정, 잠금 파일이 예상 없이 포함됐는지 확인합니다. 비밀키와 개인 자료가 들어갔다면 커밋이나 push 전에 멈추고 노출 대응 절차를 따릅니다.

빌드는 서비스용 결과물을 만드는 단계다

빌드는 사람이 작업한 소스 파일을 브라우저나 서버가 제공할 결과물로 변환하는 과정입니다. Vite 공식 문서는 ‘vite build’가 기본적으로 index.html을 시작점으로 삼아 정적 호스팅에 제공할 번들을 만든다고 설명합니다. 번들은 여러 코드와 자원을 배포하기 좋은 형태로 묶은 결과물입니다.

npm run build

이 명령 이름은 프로젝트마다 다르며 package.json의 scripts를 먼저 읽어야 합니다. 빌드가 성공했다는 것은 정해진 변환 과정이 끝났다는 뜻입니다. 내용이 정확하고 모바일에서 잘 보이며 외부 링크가 살아 있다는 뜻까지 포함하지 않습니다.

미리보기는 공개 전 검수 환경이다

미리보기 배포는 실제 사용자 도메인과 분리된 주소에서 결과를 검토하는 환경입니다. Vercel은 Local, Preview, Production을 서로 다른 환경으로 설명합니다. 미리보기에서 팀이 확인한 뒤 프로덕션으로 내보내면 위험을 줄일 수 있습니다.

환경변수와 도메인, 데이터베이스가 미리보기와 공개 환경에서 다를 수 있습니다. 미리보기에서 결제를 실제로 승인하거나 운영 이메일을 보내지 않도록 테스트 키와 가짜 데이터를 씁니다. 반대로 공개에 필요한 설정이 미리보기에 없어서 생긴 오류도 구분해야 합니다.

배포는 결과물을 서비스에 올리는 단계다

배포는 빌드 결과를 호스팅 서비스에 전달하고 접근 가능한 주소를 만드는 과정입니다. Git 연결 방식에서는 특정 커밋 push가 새 배포를 시작할 수 있습니다. 하지만 빌드 실패, 권한 오류, 배포 대기, 도메인 연결 문제로 프로덕션 주소가 새 결과물을 가리키지 않을 수 있습니다.

배포 로그에서 대상 커밋, 환경, 상태, 생성 주소를 확인합니다. 이전 배포를 다시 실행하거나 프로덕션으로 승격하는 행동은 공개 상태를 바꿀 수 있으므로 대상과 영향을 모르면 실행하지 않습니다. 성공 아이콘 하나만 보고 사용자에게 공개됐다고 알리지 않습니다.

공개 확인은 실제 도메인에서 다시 시작한다

프로덕션은 실제 사용자가 접속하는 공개 환경입니다. 공개 확인에서는 배포 서비스의 임시 주소뿐 아니라 대표 도메인을 직접 엽니다. 캐시 때문에 예전 HTML과 새 JavaScript가 섞일 수 있어 문구 하나보다 번들 이름, 수정한 기능, 응답 상태를 함께 봅니다.

• 실제 공개 URL이 200 응답을 주는지 확인합니다.
• 페이지 제목과 대표 H1이 새 내용과 맞는지 봅니다.
• 모바일 너비에서 버튼과 코드가 가로로 넘치지 않는지 봅니다.
• 수정한 주요 기능을 안전한 입력으로 한 번 실행합니다.
• canonical과 robots, 구조화 데이터가 공개 사실과 맞는지 확인합니다.
• 사이트맵과 RSS가 새 주소와 실제 날짜를 포함하는지 봅니다.

검색엔진 알림 접수는 색인 완료가 아닙니다. 새 URL을 알렸다는 사실과 검색 결과에 실제로 노출됐다는 사실도 분리해 기록해야 합니다.

실패 상태는 마지막 성공 지점으로 돌아가 찾는다

로컬 화면은 정상인데 빌드가 실패하면 타입, 누락 파일, 프로덕션 설정을 봅니다. 빌드는 성공했지만 미리보기가 깨지면 경로와 환경변수, 배포 로그를 봅니다. 미리보기는 정상인데 공개 도메인이 옛 버전이면 프로덕션 승격, 도메인 연결, 캐시를 확인합니다.

한 번에 재배포와 DNS 변경과 캐시 삭제를 모두 하지 않습니다. 마지막으로 확인된 상태를 기록하고 다음 한 단계만 시험합니다. DNS는 도메인 이름을 서버 주소에 연결하는 체계이므로 잘못 바꾸면 사이트와 이메일에 함께 영향을 줄 수 있습니다.

오늘 바로 해볼 작은 실습

현재 프로젝트를 변경하지 않고 배포 흐름을 종이에 그립니다.

1. 저장되는 소스 폴더 이름을 적습니다.
2. package.json에서 build 명령 문자열을 읽습니다.
3. 빌드 결과 폴더가 어디인지 설정에서 확인합니다.
4. 로컬, 미리보기, 프로덕션 주소를 세 칸으로 나눕니다.
5. 각 칸에서 사용할 데이터와 비밀키 종류를 적되 실제 값은 쓰지 않습니다.
6. 공개 뒤 확인할 URL과 화면 행동을 한 개씩 정합니다.

뜻을 모르는 배포, 승격, 롤백, DNS 변경 명령은 실행하지 마세요. 운영 비밀키를 로컬 예시에 붙여 넣지 않고, 결제와 삭제 기능은 테스트 환경에서만 검증합니다. 저장됨, 빌드됨, 배포됨, 공개 확인됨을 따로 기록하는 습관이 있으면 문제가 생겨도 정확한 단계에서 멈춰 복구할 수 있습니다.