메인 콘텐츠로 건너뛰기

소개

Laravel 프레임워크의 설정 파일은 모두 config/ 디렉터리에 저장되어 있습니다. 각 옵션에는 코멘트가 붙어 있으므로 파일을 열고 이용 가능한 옵션을 확인해 봐 주세요. 설정 파일에서는 데이터베이스 접속 정보·메일 서버 정보·애플리케이션 URL이나 암호화 키 등 다양한 코어 설정 값을 관리합니다.

about 명령

about Artisan 명령을 사용하면 애플리케이션의 설정·드라이버·환경의 개요를 확인할 수 있습니다.
php artisan about
특정 섹션만 확인하고 싶은 경우에는 --only 옵션을 사용합니다.
php artisan about --only=environment
특정 설정 파일의 값을 자세히 확인하려면 config:show 명령이 편리합니다.
php artisan config:show database

환경 설정(.env)

실행 환경에 따라 설정 값을 전환하고 싶은 경우가 많이 있습니다. 예를 들어 로컬과 프로덕션에서 캐시 드라이버를 바꾸고 싶은 경우 등입니다. Laravel은 이를 간단하게 하기 위해 DotEnv PHP 라이브러리를 이용하고 있습니다. 새로 설치할 때 애플리케이션의 루트 디렉터리에는 일반적인 환경 변수가 정의된 .env.example 파일이 포함되어 있으며, 설치 과정 중에 자동으로 .env로 복사됩니다.
팀에서 개발하는 경우, .env.example 파일을 갱신하면서 리포지토리에 포함해 두면 편리합니다. 플레이스홀더 값을 설정해 두면 팀의 다른 개발자가 어떤 환경 변수가 필요한지 명확히 파악할 수 있습니다.

환경 파일의 보안

.env 파일은 소스 컨트롤에 커밋하지 마세요. 개발자나 서버별로 다른 설정이 필요하며, 리포지토리에 포함하면 사고 발생 시 기밀 정보가 유출될 위험이 있습니다.
다만 Laravel에는 환경 파일을 암호화하는 기능이 내장되어 있어, 암호화된 상태라면 소스 컨트롤에 안전하게 저장할 수 있습니다.

추가 환경 파일

애플리케이션 기동 시 Laravel은 APP_ENV 환경 변수나 CLI의 --env 인수가 지정되어 있는지 확인합니다. 지정되어 있는 경우 .env.[APP_ENV] 파일이 존재하면 그것을 로드합니다. 존재하지 않는 경우에는 기본 .env 파일이 사용됩니다.

환경 변수의 타입

.env 파일의 변수는 모두 문자열로 해석되지만, env() 함수에서 보다 폭넓은 타입을 반환할 수 있도록 다음 특수 값이 준비되어 있습니다.
.env의 값env()의 반환 값
true(bool) true
(true)(bool) true
false(bool) false
(false)(bool) false
empty(string) ''
(empty)(string) ''
null(null) null
(null)(null) null
공백을 포함하는 값을 설정하려면 큰따옴표로 감쌉니다.
APP_NAME="My Application"

환경 변수 취득

.env 파일에 작성한 모든 변수는 요청을 받을 때 $_ENV PHP 슈퍼글로벌에 로드됩니다. 설정 파일 내에서는 env() 함수를 사용해 값을 가져올 수 있습니다.
'debug' => (bool) env('APP_DEBUG', false),
두 번째 인수는 기본값입니다. 해당 환경 변수가 존재하지 않는 경우에 반환됩니다.

현재 환경 확인

현재 환경은 .env 파일의 APP_ENV 변수로 결정됩니다. App 파사드의 environment 메서드로 가져올 수 있습니다.
use Illuminate\Support\Facades\App;

$environment = App::environment();
인수를 전달해 특정 환경인지 확인할 수도 있습니다.
if (App::environment('local')) {
    // 로컬 환경
}

if (App::environment(['local', 'staging'])) {
    // 로컬 또는 스테이징 환경
}

환경 파일의 암호화

암호화되지 않은 환경 파일은 소스 컨트롤에 저장해서는 안 되지만, Laravel에는 환경 파일을 암호화하는 기능이 있습니다.
php artisan env:encrypt
실행하면 .env가 암호화되고, 암호화된 내용이 .env.encrypted 파일에 저장됩니다. 복호화 키는 명령의 출력에 표시되므로 안전한 비밀번호 매니저에 저장해 주세요. 복호화하려면 env:decrypt 명령을 사용합니다.
php artisan env:decrypt

설정 값 접근

Config 파사드나 글로벌 config() 함수를 사용해 애플리케이션 어디에서든 설정 값에 접근할 수 있습니다. “점 표기법”을 사용해 파일명과 옵션명을 조합해 지정합니다.
use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

// 글로벌 함수로도 가져올 수 있다
$value = config('app.timezone');

// 존재하지 않을 경우의 기본값을 지정
$value = config('app.timezone', 'Asia/Tokyo');
실행 시 설정 값을 변경하려면 Config::set() 또는 배열을 config()에 전달합니다.
Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);
타입 지정 취득 메서드도 준비되어 있으며, 타입이 일치하지 않는 경우 예외가 던져집니다.
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

설정 캐시

애플리케이션의 성능을 향상시키려면 모든 설정 파일을 하나의 파일로 캐시합니다.
php artisan config:cache
이 명령은 모든 설정 옵션을 하나의 파일로 모아 프레임워크가 빠르게 로드할 수 있게 합니다.
config:cache 명령은 프로덕션 환경의 배포 프로세스 일부로 실행해 주세요. 로컬 개발 중에는 설정이 자주 바뀌므로 실행하지 않는 것을 권장합니다.
캐시가 만들어지면 .env 파일은 프레임워크의 요청이나 Artisan 명령 실행 시에 로드되지 않게 됩니다. 따라서 env() 함수는 시스템 레벨의 환경 변수만 반환합니다.
이 때문에 env() 함수는 반드시 config/ 디렉터리 내의 설정 파일에서만 호출해 주세요. 애플리케이션 내의 다른 곳에서는 config() 함수를 사용해 설정 값을 가져옵니다.
캐시를 삭제하려면 config:clear 명령을 사용합니다.
php artisan config:clear

설정 파일 게시

Laravel의 설정 파일 다수는 이미 config/ 디렉터리에 게시되어 있지만, cors.phpview.php 등 일부 파일은 기본적으로 게시되어 있지 않습니다. 미게시된 설정 파일을 게시하려면 config:publish 명령을 사용합니다.
php artisan config:publish

php artisan config:publish --all

디버그 모드

config/app.phpdebug 옵션은 오류 정보를 사용자에게 어느 정도 표시할지를 결정합니다. 이 옵션은 기본적으로 .env 파일의 APP_DEBUG 환경 변수 값을 따릅니다.
프로덕션 환경에서는 APP_DEBUG를 반드시 false로 설정해 주세요. true 그대로 두면 애플리케이션의 기밀 설정 값이 최종 사용자에게 공개될 위험이 있습니다.
# 로컬 개발
APP_DEBUG=true

# 프로덕션 환경
APP_DEBUG=false

유지 보수 모드

애플리케이션이 유지 보수 모드일 때 모든 요청에 대해 커스텀 뷰가 표시됩니다. 이를 통해 업데이트 중이나 유지 보수 작업 중에 애플리케이션을 일시적으로 “무효화”할 수 있습니다.

유지 보수 모드 활성화

php artisan down
--refresh 옵션을 지정하면 브라우저가 지정한 초 수 후에 자동으로 다시 로드됩니다.
php artisan down --refresh=15
--retry 옵션은 Retry-After HTTP 헤더의 값으로 설정됩니다.
php artisan down --retry=60

유지 보수 모드 바이패스

시크릿 토큰을 사용해 특정 사용자만 접근할 수 있도록 하려면 --secret 옵션을 사용합니다.
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
--with-secret 옵션을 사용하면 Laravel이 토큰을 자동 생성합니다.
php artisan down --with-secret

여러 서버에서의 유지 보수 모드

기본적으로 Laravel은 파일 기반으로 유지 보수 모드를 관리합니다. 여러 서버 구성인 경우에는 캐시 기반 방법이 편리합니다.
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

유지 보수 뷰의 사전 렌더링

배포 중에 php artisan down을 실행하는 경우, 의존 관계 갱신 중에 접근한 사용자가 오류를 보게 될 수 있습니다. 이를 방지하려면 --render 옵션으로 뷰를 사전 렌더링합니다.
php artisan down --render="errors::503"
유지 보수 모드 중에 모든 요청을 특정 URL로 리다이렉트할 수도 있습니다.
php artisan down --redirect=/

유지 보수 모드 무효화

php artisan up
유지 보수 모드의 기본 템플릿은 resources/views/errors/503.blade.php를 생성함으로써 커스터마이징할 수 있습니다.
다운타임을 완전히 없애고 싶은 경우, Laravel Cloud 같은 풀 매니지드 플랫폼의 이용을 검토해 주세요.

다음 단계

라우팅

URL과 컨트롤러를 연결하는 라우팅의 기초를 배웁니다.
마지막 수정일 2026년 7월 13일