프로덕션 빌드 (Production Build)

프로덕션 빌드(Production Build)는 소스 코드를 실제 서비스 환경에서 제공할 산출물로 만드는 빌드 방식입니다. 어떤 변환과 최적화를 적용하는지는 사용하는 도구와 설정에 따라 달라집니다. 개발 중 코드를 즉시 확인하는 실행 방식과 구별되며, 산출물이 만들어졌다는 사실과 그 산출물이 배포되어 정상 동작한다는 사실을 따로 확인합니다.

서비스에 제공할 파일을 만드는 과정

Vite의 프로덕션 빌드 문서는 vite build가 기본적으로 프로젝트의 index.html을 진입점으로 삼아 정적 호스팅에 제공할 애플리케이션 번들을 만든다고 설명합니다. 소스 파일과 의존성을 처리해 브라우저가 읽을 파일을 만드는 단계입니다. 원본에서 모듈을 여러 파일로 나눴더라도 산출물의 구성은 빌드 설정에 따라 달라질 수 있습니다. 소스 폴더의 모습과 배포하는 폴더가 항상 일치하지 않는 이유입니다.

빌드 도구는 대상 환경에 맞춰 구문을 변환하고 자원의 경로를 조정합니다. Vite 문서는 build.target으로 대상 환경을 지정하는 방법을 설명하면서 구문 변환과 폴리필 제공을 구분합니다. 문법을 바꿔 만들었다고 모든 브라우저에 필요한 기능까지 자동으로 생기는 것은 아닙니다. 사용할 API와 지원 브라우저를 함께 확인해야 빌드 산출물이 기대한 환경에서 실행되는지 판단할 수 있습니다.

출력 파일이 만들어져도 외부 API나 데이터베이스가 그 안에 포함되는 것은 아닙니다. 웹 앱이 실행 중 별도 서버를 호출한다면 해당 서버와의 연결은 배포 환경에서도 필요합니다. 프런트엔드 산출물, 서버 실행 코드, 외부 서비스가 어떤 역할을 맡는지 나누면 빌드 완료 뒤에도 남아 있는 실행 조건을 파악할 수 있습니다.

개발 환경과 배포 환경의 차이

React의 앱 생성 안내는 프레임워크를 사용하는 구성과 빌드 도구로 직접 구성하는 방식을 구별합니다. 프로젝트가 어떤 구성을 택했는지에 따라 빌드 명령, 출력 형식, 필요한 서버가 달라집니다. 프로젝트 파일에 같은 이름의 build 스크립트가 있어도 실제로 호출하는 도구는 다를 수 있습니다. 명령 이름만으로 정적 파일만 생성하는지, 서버용 결과물도 만드는지 확정하지 않습니다.

개발 환경은 수정한 코드를 빠르게 확인하는 흐름을 지원하고, 프로덕션 빌드는 배포할 결과물을 만드는 흐름에 맞춥니다. 개발 서버에서 정상으로 보였던 기능도 배포 주소, 자원 경로, 연결 설정이 달라지면 실패할 수 있습니다. Vite의 base 설정은 앱을 도메인의 하위 경로에 배포할 때 자원 URL을 조정하는 사례입니다. 메인 페이지가 열려도 이미지나 나중에 읽는 코드 파일의 경로가 잘못되면 일부 기능만 실패할 수 있습니다.

빌드 결과를 비교할 때는 사용한 소스 버전과 의존성, 도구 설정을 함께 남깁니다. 같은 코드라도 다른 의존성이나 설정으로 처리하면 결과물이 달라질 수 있습니다. 빌드가 성공했다는 로그는 해당 명령이 끝났다는 증거이며, 실제 이용자가 만나는 기능의 성공 여부는 별도 실행으로 확인합니다.

빌드 성공과 서비스 반영의 경계

빌드는 산출물을 만드는 단계이고 배포는 그 산출물을 제공할 환경에 반영하는 단계입니다. 저장소에 코드를 올렸을 때 두 단계가 자동으로 이어지는 프로젝트도 있지만, 로컬에서 빌드한 것만으로 공개 사이트가 바뀌지는 않습니다. Vercel 같은 배포 서비스의 결과를 읽을 때도 어떤 커밋을 빌드했고 어느 주소에 반영됐는지 연결하면 오래된 배포를 새 결과로 착각하는 일을 줄일 수 있습니다.

Vite 문서는 새 배포 뒤 이전 자원이 삭제되면 이미 열린 페이지가 예전 코드 조각을 가져오다가 실패할 수 있다고 설명합니다. 빌드가 정상이어도 배포 파일의 유지 정책과 HTML 캐시가 맞지 않으면 오류가 생깁니다. 확인할 대상은 처음 여는 화면뿐 아니라 배포 전에 열어 둔 화면과 나중에 불러오는 기능도 포함합니다. 산출물 생성, 서버 반영, 실제 요청 결과를 나누어 기록하면 어느 단계에서 문제가 발생했는지 추적할 수 있습니다.