본문 바로가기

배포

업데이트됨

번역일: 2026년 10월 31일

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

원문 수정
2026년 10월 28일
번역 갱신
2026년 10월 31일

배포

소개

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와 같은 완전 관리형 Laravel 플랫폼을 사용해 보세요.

아래 설정처럼, 웹 서버가 모든 요청을 애플리케이션의 public/index.php 파일로 전달하도록 반드시 설정해야 합니다. index.php 파일을 프로젝트 루트로 옮기려고 해서는 안 됩니다. 프로젝트 루트에서 애플리케이션을 서비스하면 많은 민감한 설정 파일이 인터넷에 그대로 노출됩니다.

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 ~ \.php$ { return 404; } location ~ /\.(?!well-known).* { deny all; } }

FrankenPHP

FrankenPHP로도 Laravel 애플리케이션을 서비스할 수 있습니다. FrankenPHP는 Go로 작성된 현대적인 PHP 애플리케이션 서버입니다. FrankenPHP로 Laravel PHP 애플리케이션을 서비스하려면 php-server 명령을 실행하기만 하면 됩니다.

frankenphp php-server -r public/

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

디렉터리 권한

Laravel은 bootstrap/cache와 storage 디렉터리에 파일을 써야 하므로, 웹 서버 프로세스의 소유자가 이 디렉터리들에 대한 쓰기 권한을 가지고 있는지 확인해야 합니다.

최적화

애플리케이션을 프로덕션 환경에 배포할 때는 설정, 이벤트, 라우트, 뷰를 비롯한 여러 파일을 캐싱해 두는 것이 좋습니다. Laravel은 이 파일들을 한 번에 캐싱해 주는 optimize Artisan 명령을 제공합니다. 이 명령은 보통 배포 과정의 일부로 실행합니다.

php artisan optimize

optimize:clear 명령을 사용하면 optimize 명령이 생성한 모든 캐시 파일은 물론, 기본 캐시 드라이버에 저장된 모든 키도 함께 삭제할 수 있습니다.

php artisan optimize:clear

이어지는 내용에서는 optimize 명령이 내부적으로 실행하는 개별 최적화 명령들을 하나씩 살펴보겠습니다.

설정 캐싱

애플리케이션을 프로덕션 환경에 배포할 때는 배포 과정에서 config:cache Artisan 명령을 반드시 실행해야 합니다.

php artisan config:cache

이 명령은 Laravel의 모든 설정 파일을 하나의 캐시 파일로 합쳐 줍니다. 덕분에 설정 값을 불러올 때 프레임워크가 파일 시스템에 접근하는 횟수가 크게 줄어듭니다.

WARNING

배포 과정에서 config:cache 명령을 실행한다면, env 함수를 반드시 설정 파일 내부에서만 호출해야 합니다. 설정이 캐싱되고 나면 .env 파일은 더 이상 로드되지 않으며, .env 변수를 가져오려는 env 함수 호출은 모두 null을 반환하게 됩니다.

이벤트 캐싱

애플리케이션에서 자동 탐색(auto-discovery)된 이벤트와 리스너의 매핑 정보도 배포 과정에서 캐싱해 두는 것이 좋습니다. 배포 시 event:cache Artisan 명령을 실행하면 됩니다.

php artisan event:cache

라우트 캐싱

라우트가 많은 대규모 애플리케이션을 만들고 있다면, 배포 과정에서 route:cache Artisan 명령을 실행해야 합니다.

php artisan route:cache

이 명령은 모든 라우트 등록을 캐시 파일 안의 단일 메서드 호출로 줄여 줍니다. 수백 개의 라우트를 등록할 때 라우트 등록 성능이 향상됩니다.

뷰 캐싱

애플리케이션을 프로덕션 환경에 배포할 때는 배포 과정에서 view:cache Artisan 명령을 실행해야 합니다.

php artisan view:cache

이 명령은 모든 Blade 뷰를 미리 컴파일해 둡니다. 따라서 요청이 들어올 때마다 뷰를 즉석에서 컴파일하지 않아도 되어, 뷰를 반환하는 모든 요청의 성능이 향상됩니다.

서비스 리로드

NOTE

Laravel Cloud에 배포하는 경우 모든 서비스의 정상적인(graceful) 리로드가 자동으로 처리되므로 reload 명령을 사용할 필요가 없습니다.

애플리케이션의 새 버전을 배포한 뒤에는 큐 워커, Laravel Reverb, Laravel Octane처럼 장시간 실행되는 서비스를 리로드(재시작)해야 새 코드가 반영됩니다. Laravel은 이러한 서비스를 종료시켜 주는 reload Artisan 명령을 제공합니다.

php artisan reload

Laravel Cloud를 사용하지 않는다면, 리로드 대상 프로세스가 종료되는 것을 감지해 자동으로 다시 시작해 주는 프로세스 모니터를 직접 설정해야 합니다.

디버그 모드

config/app.php 설정 파일의 debug 옵션은 오류 발생 시 사용자에게 얼마나 많은 정보를 보여 줄지를 결정합니다. 기본적으로 이 옵션은 애플리케이션의 .env 파일에 저장된 APP_DEBUG 환경 변수의 값을 따르도록 설정되어 있습니다.

WARNING

프로덕션 환경에서는 이 값을 항상 false로 두어야 합니다. 프로덕션에서 APP_DEBUG 변수가 true로 설정되어 있으면, 민감한 설정 값이 애플리케이션의 최종 사용자에게 노출될 위험이 있습니다.

헬스 라우트

Laravel에는 애플리케이션의 상태를 모니터링하는 데 사용할 수 있는 내장 헬스 체크 라우트가 포함되어 있습니다. 프로덕션 환경에서는 이 라우트를 통해 업타임 모니터, 로드 밸런서, Kubernetes와 같은 오케스트레이션 시스템에 애플리케이션 상태를 알릴 수 있습니다.

기본적으로 헬스 체크 라우트는 /up 경로로 제공되며, 애플리케이션이 예외 없이 부팅되었다면 HTTP 200 응답을, 그렇지 않다면 HTTP 500 응답을 반환합니다. 이 라우트의 URI는 애플리케이션의 bootstrap/app 파일에서 변경할 수 있습니다.

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

이 라우트로 HTTP 요청이 들어오면 Laravel은 Illuminate\Foundation\Events\DiagnosingHealth 이벤트도 함께 디스패치합니다. 이를 이용해 애플리케이션에 필요한 추가 헬스 체크를 수행할 수 있습니다. 이 이벤트의 리스너 안에서 데이터베이스나 캐시의 상태를 확인할 수 있으며, 문제가 발견되면 리스너에서 예외를 던지기만 하면 됩니다.

Laravel Cloud 또는 Forge로 배포하기

Laravel Cloud

Laravel에 최적화된 완전 관리형 오토스케일링 배포 플랫폼을 원한다면 Laravel Cloud를 살펴보세요. Laravel Cloud는 관리형 컴퓨트, 데이터베이스, 캐시, 오브젝트 스토리지를 제공하는 Laravel용 배포 플랫폼입니다.

Cloud에서 Laravel 애플리케이션을 실행하고, 확장 가능하면서도 단순한 운영 경험을 느껴 보세요. Laravel Cloud는 Laravel 제작진이 프레임워크와 매끄럽게 동작하도록 세밀하게 조정했기 때문에, 기존에 익숙한 방식 그대로 Laravel 애플리케이션을 계속 개발할 수 있습니다.

Laravel Forge

서버를 직접 관리하고 싶지만 견고한 Laravel 애플리케이션을 실행하는 데 필요한 여러 서비스를 모두 직접 설정하기는 부담스럽다면, Laravel 애플리케이션을 위한 VPS 서버 관리 플랫폼인 Laravel Forge가 대안이 될 수 있습니다.

Laravel Forge는 DigitalOcean, Linode, AWS 등 다양한 인프라 제공업체에 서버를 생성할 수 있습니다. 또한 Nginx, MySQL, Redis, Memcached, Beanstalk 등 견고한 Laravel 애플리케이션을 구축하는 데 필요한 모든 도구를 설치하고 관리해 줍니다.

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

번역일: 2026년 10월 31일