배포는 프로젝트를 공개 앱으로 전환합니다. 배포에 실패하거나 공개 URL이 Preview와 다르게 동작하면 순서대로 문제를 해결하세요. 이 페이지는 빌드 복구 가이드이자 배포 문제 해결 참조 문서입니다. 가장 간단한 질문부터 시작하세요. 앱이 Preview에서 작동하나요?Documentation Index
Fetch the complete documentation index at: https://docs.replit.com/llms.txt
Use this file to discover all available pages before exploring further.
달성할 내용
이 페이지가 끝나면 문제가 앱 자체, 배포 설정, 프로덕션 Secrets, 배포 유형, 포트 구성, 또는 네트워크/DNS 접근에 있는지 알 수 있습니다.Preview부터 시작
배포하기 전에 Project Editor에서 앱이 올바르게 실행되는지 확인하세요. Project Editor 상단에서 Run을 선택하고 Preview를 엽니다. Preview에서replit.dev URL로 앱이 표시되지 않으면, 배포 전에 앱을 수정하세요.
먼저 Agent에게 Preview를 진단하도록 요청하세요.
Preview가 작동하지 않으면 배포해도 수정되지 않습니다.
Preview는 작동하지만 배포가 실패하는 경우
Preview는 작동하지만 배포가 실패하면 배포별 설정을 확인하세요.로그 확인
Publishing 패널의 Logs 탭을 엽니다. 스택 추적, 누락된 패키지, 실패한 명령, 누락된 환경 변수, 또는 시작 오류를 찾습니다. 관련 오류를 Agent에 붙여넣으세요.실행 및 빌드 명령 확인
일반적인 실수로는 오타, 잘못된 플래그, 잘못된 진입 파일, 또는 로컬에서만 작동하는 명령 등이 있습니다. Publishing 패널에서 명령을 검토하세요. 앱에 빌드 명령과 시작 명령이 모두 필요한 경우 두 명령이 모두 올바른지 확인하세요.프로덕션 Secrets 확인
Project Editor에서 설정한 Secrets는 자동으로 배포된 앱에 전달되지 않습니다. Publishing 패널에서 모든 프로덕션 Secrets와 환경 변수를 추가하세요. 누락된 Secrets는 정의되지 않은 값에 대한 오류, 실패한 API 호출, 데이터베이스 연결 실패, 로그인 오류, 또는 결제 실패를 일으킬 수 있습니다. Secrets를 참조하세요.장기 실행 프로세스 동작 확인
배포된 앱은 프로그램이 계속 실행될 것을 기대합니다. 프로그램이 한 번 실행되고 종료되면 플랫폼이 자동으로 재시작합니다. 애플리케이션이 웹 서버와 같은 장기 실행 프로세스를 시작하는지 확인하세요.호스트 및 포트 구성 확인
웹 서버를 실행하는 경우, 배포는 서버가 사용하는 포트를 자동으로 감지할 수 있지만 서버는0.0.0.0에서 수신해야 합니다. localhost 또는 127.0.0.1에서만 수신하는 것은 배포된 앱에서 작동하지 않습니다.
.replit 구성에 포트를 지정한 경우, 자동 포트 감지가 비활성화됩니다. 프로모션 단계를 통과하려면 externalPort를 80으로 설정한 포트를 지정해야 합니다. 서버가 지정된 localPort에서 수신하는지 확인하세요.
Agent에게 신중하게 확인하도록 요청하세요.
헬스 체크 타이밍 확인
배포된 앱을 라이브로 표시하기 전에 Replit이 앱에 HTTP 요청을 보냅니다. 홈페이지가 응답하는 데 5초 이상 걸리면 헬스 체크가 시간 초과되어 마지막 단계에서 배포가 실패할 수 있습니다. 시작이 느리면 Agent에게 시작 작업을 줄이고, 비용이 많이 드는 작업을 사용자 액션 뒤로 이동하거나, 적절한 경우 데이터를 캐시하도록 요청하세요.배포는 성공했지만 공개 URL이 작동하지 않는 경우
Preview가 작동하고 배포가 성공했지만 공개 URL이 작동하지 않으면 Preview와 프로덕션 동작을 비교하세요. 확인 사항:- 프로덕션 Secrets와 환경 변수.
- 데이터베이스 연결 설정.
- 로그인 콜백 또는 리디렉션 URL.
- 결제 웹훅 또는 리디렉션 설정.
- API 허용 목록 또는 CORS 설정.
- 데이터베이스나 스토리지 서비스 대신 로컬에 기록된 파일.
- 모바일 레이아웃 및 브라우저 차이점.
Static 배포 문제
Static 배포는 HTML, CSS, JavaScript와 같은 정적 파일을 제공합니다. 앱에 서버 사이드 동작, API 라우트, 인증 콜백, 서버에서의 데이터베이스 호출, 또는 장기 실행 백엔드 로직이 포함되어 있으면 Static 배포에 적합하지 않을 수 있습니다. 대신 Publishing 패널에서 배포 유형을 Autoscale로 변경하세요. Static 배포 문제는 종종 잘못된 공개 디렉터리 지정이나 서버가 필요한 앱에 Static을 선택한 경우에 발생합니다.파일 및 크기 제한
Reserved VM 및 Autoscale 배포는 최대 8GB의 Replit 앱을 지원합니다. Static 배포는 최대 1GB를 지원합니다. 앱 크기를 줄이려면 불필요한 파일을 삭제하고, 생성된 출력 커밋을 피하거나, 대용량 자산에 외부 스토리지를 사용하세요. 업로드된 파일이나 생성된 데이터가 배포 후 사라지면 앱 파일 시스템 대신 데이터베이스나 스토리지 서비스에 저장하세요.replit.app 및 replit.dev URL 접근 문제
replit.app 또는 replit.dev 도메인에서 앱 접근에 문제가 있으면 웹 필터나 네트워크 제한이 원인일 수 있습니다.
Google DNS(8.8.8.8) 또는 Cloudflare DNS(1.1.1.1)와 같은 공개 DNS 리졸버를 사용해 보세요.
DNS 설정 변경
- Windows
- macOS
- Linux
- 제어판을 엽니다.
- 네트워크 및 공유 센터로 이동합니다.
- 왼쪽에서 어댑터 설정 변경을 선택합니다.
- 활성 네트워크 연결을 마우스 오른쪽 버튼으로 클릭하고 속성을 선택합니다.
- **인터넷 프로토콜 버전 4(TCP/IPv4)**를 선택하고 속성을 선택합니다.
- 다음 DNS 서버 주소 사용을 선택합니다.
- Google DNS의 경우
8.8.8.8, Cloudflare DNS의 경우1.1.1.1과 같은 공개 DNS 서버 IP 주소를 입력합니다. - 확인을 선택해서 변경 사항을 저장합니다.
DNS 캐시 지우기
DNS 설정을 변경한 후 새 구성을 적용하기 위해 DNS 캐시를 지우세요.- Windows: 명령 프롬프트에서
ipconfig /flushdns를 실행합니다. - macOS 및 Linux: 터미널에서
sudo systemctl restart NetworkManager를 실행합니다. 정확한 명령은 배포판에 따라 다를 수 있습니다.
지역 성능과 안정성을 향상시키기 위해 Replit Apps의
replit.dev URL은 클러스터 마이그레이션 중에 가끔 변경될 수 있습니다. 마이그레이션이 완료되면 명시적으로 위치 변경을 요청하지 않는 한 약 1년 동안 URL이 안정적으로 유지됩니다.Streamlit 애플리케이션 배포
Streamlit 애플리케이션은 Replit 배포에서 작동합니다. 시작하는 가장 쉬운 방법은 Streamlit 템플릿을 사용하는 것입니다. 또는 배포를 위한 실행 명령을 다음으로 설정하세요.main.py를 해당 파일명으로 교체하세요.
완료 기준
- Preview가 작동합니다.
- 배포가 완료됩니다.
- 공개 URL이 로드됩니다.
- 공개 URL에서 기본 앱 플로우가 작동합니다.
- 프로덕션 Secrets와 설정이 구성되어 있습니다.
- 로그에 숨겨진 시작 오류가 없습니다.