배포

번역일: 2026년 6월 20일

배포

소개
서버 요구사항
서버 설정
- Nginx
최적화
디버그 모드
Forge / Vapor로 간편하게 배포하기

소개

Laravel 애플리케이션을 프로덕션 환경에 배포할 때는 몇 가지 중요한 사항을 챙겨야 합니다. 이 문서에서는 애플리케이션이 최대한 효율적으로 동작하도록 배포 시 확인해야 할 핵심 항목들을 정리합니다.

서버 요구사항

Laravel 프레임워크를 실행하려면 아래 최소 PHP 버전과 확장 모듈이 필요합니다. 웹 서버 환경을 구성하기 전에 반드시 충족 여부를 확인하세요.

PHP >= 8.1
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 Forge와 같은 공식 서버 관리·배포 서비스를 활용하는 것도 좋은 방법입니다.

아래 설정에서 핵심은 모든 요청이 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 ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

최적화

배포 시 아래 최적화 작업들을 함께 수행하면 애플리케이션 응답 속도와 안정성을 크게 개선할 수 있습니다.

오토로더 최적화

프로덕션 배포 시에는 Composer 오토로더 맵을 최적화해야 합니다. 최적화된 맵이 있으면 Composer가 클래스 파일 위치를 훨씬 빠르게 찾을 수 있습니다.

composer install --optimize-autoloader --no-dev

NOTE

오토로더 최적화와 더불어, composer.lock 파일을 반드시 소스 저장소에 포함하세요. composer.lock 파일이 있으면 의존성 설치 속도가 눈에 띄게 빨라집니다.

설정 캐싱

배포 프로세스 중에 config:cache Artisan 명령어를 실행하면 모든 설정 파일을 하나의 캐시 파일로 합칩니다. 이를 통해 Laravel이 설정 값을 읽을 때 파일 시스템에 접근하는 횟수를 크게 줄일 수 있습니다.

php artisan config:cache

WARNING

config:cache를 실행한 이후에는 .env 파일이 더 이상 로드되지 않습니다. 따라서 env() 함수는 설정 파일 내부에서만 호출해야 합니다. 설정 캐시가 적용된 상태에서 라우트나 서비스 프로바이더 등 설정 파일 밖에서 env()를 호출하면 항상 null이 반환됩니다.

이벤트 캐싱

이벤트 자동 감지(Event Discovery) 기능을 사용하고 있다면, 배포 시 이벤트와 리스너 매핑 정보를 캐싱하세요. 매핑 정보를 캐싱하면 런타임에 클래스 탐색 과정이 생략되어 성능이 향상됩니다.

php artisan event:cache

라우트 캐싱

라우트가 많은 규모 있는 애플리케이션이라면 route:cache 명령어로 라우트 등록 정보를 캐싱하세요. 수백 개의 라우트를 단일 메서드 호출로 처리할 수 있게 되어 라우트 등록 속도가 크게 빨라집니다.

php artisan route:cache

뷰 캐싱

배포 시 view:cache 명령어를 실행하면 모든 Blade 뷰를 미리 컴파일해 둡니다. 요청이 들어올 때마다 뷰를 컴파일하는 과정이 생략되므로 뷰를 반환하는 요청의 응답 속도가 향상됩니다.

php artisan view:cache

아래는 배포 시 권장되는 최적화 명령어를 한눈에 정리한 흐름입니다.

디버그 모드

config/app.php의 debug 옵션은 에러 발생 시 얼마나 많은 정보를 화면에 표시할지를 결정합니다. 이 값은 기본적으로 .env 파일의 APP_DEBUG 환경 변수를 따릅니다.

WARNING

프로덕션 환경에서는 APP_DEBUG 값을 반드시 false로 설정해야 합니다. true로 설정된 상태로 운영하면 .env 파일의 데이터베이스 비밀번호, API 키 등 민감한 설정 값이 에러 화면을 통해 외부에 노출될 수 있습니다.

Forge / Vapor로 간편하게 배포하기

Laravel Forge

서버 직접 구성이 부담스럽거나 Nginx, MySQL, Redis 등 다양한 서비스 설치·관리가 익숙하지 않다면 Laravel Forge를 활용해 보세요.

Laravel Forge는 DigitalOcean, Linode, AWS 등 다양한 클라우드 인프라에 서버를 생성하고, Laravel 운영에 필요한 Nginx, MySQL, Redis, Memcached, Beanstalk 등을 자동으로 설치·관리해 줍니다. 서버 설정보다 애플리케이션 개발에 집중하고 싶은 팀에 특히 유용합니다.

NOTE

Laravel Forge를 이용한 배포 전체 과정이 궁금하다면 Laravel Bootcamp와 Laracasts의 Forge 동영상 시리즈를 참고하세요.

Laravel Vapor

서버리스 환경에서 자동 스케일링되는 배포 플랫폼을 원한다면 Laravel Vapor를 확인해 보세요. Laravel Vapor는 AWS 기반의 Laravel 전용 서버리스 배포 플랫폼입니다. 트래픽 변화에 자동으로 대응하며, Laravel 제작팀이 직접 프레임워크와의 완벽한 호환성을 보장합니다. 기존 Laravel 개발 방식 그대로 코드를 작성하면서도 서버리스의 확장성과 운영 편의성을 누릴 수 있습니다.