본문 바로가기

배포

업데이트됨

번역일: 2026년 8월 11일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정
2026년 8월 11일
번역 갱신
2026년 8월 11일

배포

소개

Laravel 애플리케이션을 프로덕션 환경에 배포할 준비가 됐다면, 애플리케이션이 최대한 효율적으로 동작하도록 몇 가지를 챙겨야 합니다. 이 문서에서는 Laravel 애플리케이션을 올바르게 배포하기 위한 핵심 체크포인트를 안내합니다.

서버 요구 사항

Laravel 프레임워크가 동작하려면 아래의 최소 PHP 버전과 확장 모듈이 서버에 설치되어 있어야 합니다.

  • PHP >= 8.3
  • Ctype PHP Extension
  • cURL PHP Extension
  • DOM PHP Extension
  • Fileinfo PHP Extension
  • Filter PHP Extension
  • Hash PHP Extension
  • Mbstring PHP Extension
  • OpenSSL PHP Extension
  • PCRE PHP Extension
  • PDO PHP Extension
  • Session PHP Extension
  • Tokenizer PHP Extension
  • XML PHP Extension

서버 설정

Nginx

Nginx가 설치된 서버에 배포한다면, 아래의 설정 파일을 출발점으로 사용할 수 있습니다. 실제 서버 환경에 맞게 일부 항목은 수정이 필요할 수 있습니다. 서버 관리가 부담스럽다면 Laravel Cloud와 같은 완전 관리형 플랫폼을 활용하는 것도 좋은 선택입니다.

아래 설정처럼, 웹 서버의 모든 요청은 반드시 애플리케이션의 public/index.php 파일로 전달되어야 합니다. index.php를 프로젝트 루트로 옮기거나 루트 디렉터리를 직접 서빙하면 .env 파일 등 민감한 설정 파일이 외부에 노출될 수 있으므로 절대 하지 마세요.

server { listen 80; listen [::]:80; server_name example.com; root /srv/example.com/public; add_header X-Frame-Options "SAMEORIGIN"; add_header X-Content-Type-Options "nosniff"; index index.php; charset utf-8; location / { try_files $uri $uri/ /index.php?$query_string; } location = /favicon.ico { access_log off; log_not_found off; } location = /robots.txt { access_log off; log_not_found off; } error_page 404 /index.php; location ~ ^/index\.php(/|$) { fastcgi_pass unix:/var/run/php/php8.3-fpm.sock; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include fastcgi_params; fastcgi_buffer_size 32k; fastcgi_buffers 8 32k; fastcgi_busy_buffers_size 64k; fastcgi_hide_header X-Powered-By; } location ~ /\.(?!well-known).* { deny all; } }

FrankenPHP

FrankenPHP를 사용해 Laravel 애플리케이션을 서빙하는 것도 가능합니다. FrankenPHP는 Go 언어로 작성된 현대적인 PHP 애플리케이션 서버입니다. 아래처럼 php-server 명령 하나로 간단하게 시작할 수 있습니다.

frankenphp php-server -r public/

Laravel Octane 연동, HTTP/3, 최신 압축 알고리즘 지원, 또는 Laravel 애플리케이션을 독립 실행형 바이너리로 패키징하는 등 더 강력한 기능을 활용하려면 FrankenPHP의 Laravel 공식 문서를 참고하세요.

디렉터리 권한

Laravel은 bootstrap/cache와 storage 디렉터리에 파일을 쓸 수 있어야 합니다. 웹 서버 프로세스를 실행하는 사용자(예: www-data)가 이 두 디렉터리에 쓰기 권한을 가지고 있는지 반드시 확인하세요.

최적화

프로덕션 배포 시에는 설정, 이벤트, 라우트, 뷰 등 다양한 파일을 캐싱해 두어야 합니다. Laravel은 이 모든 캐싱 작업을 한 번에 처리하는 편리한 Artisan 명령을 제공합니다. 배포 프로세스의 일부로 아래 명령을 실행하는 것을 권장합니다.

php artisan optimize

캐시를 모두 지우고 싶을 때는 optimize:clear 명령을 사용합니다. 이 명령은 optimize가 생성한 캐시 파일뿐만 아니라 기본 캐시 드라이버의 모든 키도 삭제합니다.

php artisan optimize:clear

아래에서는 optimize 명령이 내부적으로 실행하는 개별 최적화 명령들을 각각 설명합니다.

설정 캐싱

배포 시 config:cache 명령을 실행하면 모든 설정 파일을 하나의 캐시 파일로 합쳐줍니다. 이렇게 하면 프레임워크가 설정값을 읽을 때마다 파일 시스템에 접근하는 횟수를 크게 줄일 수 있습니다.

php artisan config:cache

WARNING

config:cache 명령을 실행한 후에는 env() 함수를 설정 파일 안에서만 호출해야 합니다. 설정이 캐싱되면 .env 파일은 더 이상 로드되지 않으며, 설정 파일 외부에서 env()로 .env 변수를 읽으려 하면 항상 null이 반환됩니다.

이벤트 캐싱

애플리케이션에서 자동 감지(auto-discover)되는 이벤트-리스너 매핑도 배포 시 캐싱해 두어야 합니다. event:cache 명령으로 처리할 수 있습니다.

php artisan event:cache

라우트 캐싱

라우트가 많은 대규모 애플리케이션이라면 배포 시 route:cache 명령을 반드시 실행하세요. 모든 라우트 등록을 하나의 메서드 호출로 묶어 캐시 파일에 저장하므로, 수백 개의 라우트를 등록할 때의 성능이 크게 향상됩니다.

php artisan route:cache

뷰 캐싱

배포 시 view:cache 명령을 실행하면 모든 Blade 뷰를 미리 컴파일해 둡니다. 요청이 들어올 때마다 즉석에서 컴파일하는 대신 이미 컴파일된 파일을 사용하므로, 뷰를 반환하는 모든 요청의 응답 속도가 빨라집니다.

php artisan view:cache

서비스 재시작

NOTE

Laravel Cloud에 배포하는 경우, 모든 서비스의 무중단 재시작이 자동으로 처리되므로 reload 명령을 별도로 실행할 필요가 없습니다.

새 버전을 배포한 후에는 큐 워커, Laravel Reverb, Laravel Octane처럼 상주(long-running)하는 서비스들이 새 코드를 사용하도록 재시작해야 합니다. Laravel은 이 서비스들을 종료시키는 reload Artisan 명령을 제공합니다.

php artisan reload

Laravel Cloud를 사용하지 않는다면, 재시작 가능한 프로세스가 종료됐을 때 자동으로 다시 시작해 주는 프로세스 모니터(예: Supervisor)를 직접 설정해야 합니다.

디버그 모드

config/app.php의 debug 옵션은 오류 발생 시 사용자에게 얼마나 많은 정보를 노출할지 결정합니다. 이 옵션은 기본적으로 .env 파일의 APP_DEBUG 환경 변수 값을 따릅니다.

WARNING

프로덕션 환경에서는 APP_DEBUG 값을 반드시 false로 설정해야 합니다. true로 설정된 상태로 운영하면 데이터베이스 접속 정보나 API 키 같은 민감한 설정값이 최종 사용자에게 그대로 노출될 위험이 있습니다.

헬스 라우트

Laravel은 애플리케이션 상태를 모니터링할 수 있는 헬스 체크 라우트를 기본으로 제공합니다. 프로덕션에서는 업타임 모니터, 로드 밸런서, 또는 Kubernetes 같은 오케스트레이션 시스템이 이 라우트를 통해 애플리케이션 상태를 확인할 수 있습니다.

기본 헬스 체크 라우트는 /up 경로로 서빙됩니다. 애플리케이션이 예외 없이 정상 부팅된 경우 HTTP 200 응답을, 그렇지 않으면 HTTP 500 응답을 반환합니다. 라우트 URI는 bootstrap/app.php에서 변경할 수 있습니다.

->withRouting(
web: __DIR__.'/../routes/web.php',
commands: __DIR__.'/../routes/console.php',
health: '/up', //
health: '/status', //
)

이 라우트에 HTTP 요청이 들어오면, Laravel은 Illuminate\Foundation\Events\DiagnosingHealth 이벤트를 발생시킵니다. 이 이벤트의 리스너를 등록하면 데이터베이스 연결 상태, 캐시 서버 응답 여부 등 애플리케이션에 맞는 추가 헬스 체크 로직을 실행할 수 있습니다. 문제가 감지되면 리스너 안에서 예외를 던지는 것만으로 500 응답을 유도할 수 있습니다.

Laravel Cloud 또는 Forge로 배포하기

Laravel Cloud

완전 관리형 오토스케일링 배포 플랫폼을 원한다면 Laravel Cloud를 확인해 보세요. Laravel Cloud는 컴퓨팅, 데이터베이스, 캐시, 오브젝트 스토리지를 모두 관리해 주는 Laravel 전용 배포 플랫폼입니다.

Laravel을 만든 팀이 직접 프레임워크와 완벽하게 맞물리도록 튜닝했기 때문에, 기존에 Laravel 개발하던 방식 그대로 코드를 작성하면서도 강력한 확장성을 누릴 수 있습니다.

Laravel Forge

서버를 직접 관리하고 싶지만 Nginx, MySQL, Redis 등 다양한 서비스를 일일이 설정하는 것이 부담스럽다면 Laravel Forge를 고려해 보세요. Forge는 VPS 서버 관리에 특화된 Laravel용 플랫폼입니다.

DigitalOcean, Linode, AWS 등 다양한 클라우드 인프라 공급자에 서버를 생성하고, Nginx, MySQL, Redis, Memcached, Beanstalk 같은 운영에 필요한 도구들을 자동으로 설치·관리해 줍니다.

이 문서는 Laravel 공식 문서(MIT)를 한국 개발자를 위해 번역·재구성한 것입니다.

번역일: 2026년 8월 11일