설정

업데이트됨

번역일: 2026년 6월 26일

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

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 26일

설정

소개
환경 설정
설정 값 접근
설정 캐싱
설정 파일 퍼블리싱
디버그 모드
점검 모드

소개

Laravel 프레임워크의 모든 설정 파일은 config 디렉터리에 위치합니다. 각 옵션에는 설명이 주석으로 달려 있으니, 파일을 열어 어떤 옵션을 사용할 수 있는지 살펴보시기 바랍니다.

이 설정 파일들을 통해 데이터베이스 연결 정보, 메일 서버 정보, 애플리케이션 URL, 암호화 키 등 다양한 핵심 설정 값을 관리할 수 있습니다.

`about` 명령어

about Artisan 명령어를 사용하면 애플리케이션의 설정, 드라이버, 환경 정보를 한눈에 확인할 수 있습니다.

php artisan about

전체 출력 중 특정 섹션만 보고 싶다면 --only 옵션으로 필터링할 수 있습니다.

php artisan about --only=environment

특정 설정 파일의 값을 상세하게 확인하려면 config:show 명령어를 사용하세요.

php artisan config:show database

환경 설정

애플리케이션이 실행되는 환경(로컬, 스테이징, 프로덕션 등)에 따라 설정 값을 다르게 적용해야 하는 경우가 많습니다. 예를 들어 로컬 개발 환경과 운영 서버에서 서로 다른 캐시 드라이버를 사용하고 싶을 수 있습니다.

Laravel은 이를 간편하게 처리하기 위해 DotEnv PHP 라이브러리를 활용합니다. 새로 설치한 Laravel 프로젝트의 루트 디렉터리에는 자주 사용하는 환경 변수들이 정의된 .env.example 파일이 포함되어 있으며, 설치 과정에서 이 파일이 자동으로 .env로 복사됩니다.

Laravel의 기본 .env 파일에는 로컬 환경과 운영 서버에서 달라질 수 있는 공통 설정 값들이 담겨 있습니다. 이 값들은 config 디렉터리의 설정 파일에서 Laravel의 env 함수를 통해 읽어 들입니다.

팀 단위로 개발하는 경우, .env.example 파일을 계속 업데이트하고 저장소에 포함시키는 것을 권장합니다. 플레이스홀더 값을 넣어두면 다른 팀원들이 애플리케이션 실행에 필요한 환경 변수가 무엇인지 쉽게 파악할 수 있습니다.

NOTE

.env 파일의 변수는 서버 레벨이나 시스템 레벨에서 설정된 외부 환경 변수에 의해 덮어쓰일 수 있습니다.

환경 파일 보안

.env 파일은 개발자마다, 서버마다 다른 설정이 필요하기 때문에 소스 컨트롤(Git 등)에 커밋해서는 안 됩니다. 만약 저장소에 접근 권한을 가진 침입자가 생기면 민감한 인증 정보가 그대로 노출될 수 있습니다.

단, Laravel의 내장 환경 파일 암호화 기능을 사용하면 암호화된 환경 파일을 소스 컨트롤에 안전하게 포함시킬 수 있습니다.

추가 환경 파일

환경 변수를 로드하기 전에 Laravel은 외부에서 APP_ENV 환경 변수가 제공되었는지, 또는 --env CLI 인자가 지정되었는지 확인합니다. 해당 값이 존재하면 .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 파일에 정의된 변수들은 애플리케이션이 요청을 받을 때 PHP의 $_ENV 슈퍼글로벌에 자동으로 로드됩니다. 설정 파일 내에서는 env 함수를 사용해 이 값을 가져올 수 있습니다. 실제로 Laravel의 기본 설정 파일을 살펴보면 이 함수가 곳곳에서 사용되는 것을 확인할 수 있습니다.

'debug' => (bool) env('APP_DEBUG', false),

env 함수의 두 번째 인자는 기본값입니다. 해당 키에 대한 환경 변수가 존재하지 않을 경우 이 기본값이 반환됩니다.

현재 환경 확인

현재 애플리케이션 환경은 .env 파일의 APP_ENV 변수를 통해 결정됩니다. App 파사드의 environment 메서드로 이 값에 접근할 수 있습니다.

use Illuminate\Support\Facades\App;

$environment = App::environment();

environment 메서드에 인자를 전달하면 현재 환경이 해당 값과 일치하는지 확인할 수 있습니다. 전달한 값 중 하나라도 일치하면 true를 반환합니다.

if (App::environment('local')) {
    // 로컬 환경입니다
}

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

NOTE

서버 레벨에서 APP_ENV 환경 변수를 설정하면 현재 환경 감지를 덮어쓸 수 있습니다.

환경 파일 암호화

암호화되지 않은 환경 파일은 소스 컨트롤에 저장해서는 안 됩니다. 하지만 Laravel의 환경 파일 암호화 기능을 사용하면 암호화된 환경 파일을 나머지 코드와 함께 안전하게 소스 컨트롤에 포함시킬 수 있습니다.

암호화

환경 파일을 암호화하려면 env:encrypt 명령어를 사용합니다.

php artisan env:encrypt

이 명령어를 실행하면 .env 파일이 암호화되어 .env.encrypted 파일에 저장됩니다. 복호화 키는 명령어 출력 결과에 표시되며, 안전한 패스워드 관리 도구에 보관해야 합니다. 직접 암호화 키를 지정하려면 --key 옵션을 사용하세요.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

NOTE

제공하는 키의 길이는 사용하는 암호화 알고리즘이 요구하는 키 길이와 일치해야 합니다. 기본적으로 Laravel은 32자 키가 필요한 AES-256-CBC 알고리즘을 사용합니다. --cipher 옵션을 통해 Laravel 암호화에서 지원하는 다른 알고리즘을 자유롭게 사용할 수 있습니다.

.env와 .env.staging처럼 여러 환경 파일이 있는 경우 --env 옵션으로 암호화할 환경 파일을 지정할 수 있습니다.

php artisan env:encrypt --env=staging

변수 이름 유지 암호화

환경 파일을 암호화할 때 --readable 옵션을 사용하면 변수 이름은 그대로 유지하면서 값만 암호화할 수 있습니다.

php artisan env:encrypt --readable

이 옵션을 사용하면 암호화된 파일이 다음과 같은 형식으로 생성됩니다.

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

변수 이름이 그대로 보이므로 민감한 데이터를 노출하지 않으면서도 어떤 환경 변수가 존재하는지 확인할 수 있습니다. 풀 리퀘스트(PR) 리뷰 시에도 파일을 복호화하지 않고도 어떤 변수가 추가, 삭제, 이름 변경되었는지 파악할 수 있어 편리합니다.

env:decrypt 명령어는 어떤 형식이 사용되었는지 자동으로 감지하므로 복호화 시 별도의 옵션을 지정할 필요가 없습니다.

NOTE

--readable 옵션을 사용하면 원본 환경 파일의 주석과 빈 줄은 암호화된 출력에 포함되지 않습니다.

복호화

환경 파일을 복호화하려면 env:decrypt 명령어를 사용합니다. 이 명령어는 LARAVEL_ENV_ENCRYPTION_KEY 환경 변수에서 복호화 키를 가져옵니다.

php artisan env:decrypt

또는 --key 옵션으로 키를 직접 전달할 수도 있습니다.

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

env:decrypt 명령어를 실행하면 .env.encrypted 파일의 내용을 복호화하여 .env 파일에 저장합니다.

커스텀 암호화 알고리즘을 사용한 경우 --cipher 옵션을 함께 지정할 수 있습니다.

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

여러 환경 파일이 있는 경우 --env 옵션으로 복호화할 환경을 지정할 수 있습니다.

php artisan env:decrypt --env=staging

기존 환경 파일을 덮어쓰려면 --force 옵션을 사용하세요.

php artisan env:decrypt --force

설정 값 접근

애플리케이션 어디서든 Config 파사드나 전역 config 함수를 사용해 설정 값에 쉽게 접근할 수 있습니다. 설정 값은 "점(dot) 표기법"으로 접근하며, 파일명과 옵션 키를 순서대로 연결합니다. 해당 설정 값이 존재하지 않을 경우 반환할 기본값을 지정할 수도 있습니다.

use Illuminate\Support\Facades\Config;

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

$value = config('app.timezone');

// 설정 값이 없을 경우 기본값 반환
$value = config('app.timezone', 'Asia/Seoul');

런타임에 설정 값을 변경하려면 Config 파사드의 set 메서드를 사용하거나 config 함수에 배열을 전달하세요.

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

정적 분석을 지원하기 위해 Config 파사드는 타입을 지정한 설정 조회 메서드도 제공합니다. 조회된 값이 기대하는 타입과 다르면 예외가 발생합니다.

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

설정 캐싱

애플리케이션의 성능을 높이려면 config:cache Artisan 명령어로 모든 설정 파일을 하나의 파일로 캐싱하세요. 모든 설정 옵션이 단일 파일로 합쳐져 프레임워크가 훨씬 빠르게 로드할 수 있습니다.

php artisan config:cache

이 명령어는 일반적으로 운영 배포 프로세스의 일부로 실행해야 합니다. 로컬 개발 중에는 설정 값을 자주 변경해야 하므로 실행하지 않는 것이 좋습니다.

설정이 캐싱되면 이후 요청이나 Artisan 명령어 실행 시 .env 파일이 로드되지 않습니다. 따라서 env 함수는 외부(시스템 레벨)의 환경 변수만 반환하게 됩니다.

이 때문에 env 함수는 반드시 config 디렉터리의 설정 파일 내에서만 호출해야 합니다. Laravel의 기본 설정 파일들을 살펴보면 이 패턴을 잘 확인할 수 있습니다. 설정 값은 위에서 소개한 config 함수를 통해 애플리케이션 어디서든 접근하면 됩니다.

캐싱된 설정을 지우려면 config:clear 명령어를 사용하세요.

php artisan config:clear

WARNING

배포 프로세스 중 config:cache 명령어를 실행한다면, env 함수를 반드시 설정 파일 내에서만 호출하고 있는지 확인하세요. 설정이 캐싱된 후에는 .env 파일이 로드되지 않으므로, env 함수는 시스템 레벨의 외부 환경 변수만 반환합니다.

설정 파일 퍼블리싱

대부분의 Laravel 설정 파일은 이미 config 디렉터리에 게시되어 있습니다. 단, cors.php나 view.php 같은 일부 파일은 대부분의 애플리케이션에서 수정할 필요가 없어 기본적으로 게시되지 않습니다.

필요하다면 config:publish Artisan 명령어로 이러한 설정 파일을 게시할 수 있습니다.

php artisan config:publishphp artisan config:publish --all

디버그 모드

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

WARNING

로컬 개발 환경에서는 APP_DEBUG를 true로 설정하세요. 운영 환경에서는 반드시 false로 설정해야 합니다. 운영 환경에서 true로 설정하면 민감한 설정 값이 최종 사용자에게 노출될 위험이 있습니다.

점검 모드

애플리케이션이 점검 모드(Maintenance Mode)일 때는 모든 요청에 대해 커스텀 뷰가 표시됩니다. 업데이트 또는 유지보수 작업 중에 애플리케이션을 일시적으로 비활성화할 때 유용합니다. 점검 모드 확인 로직은 애플리케이션의 기본 미들웨어 스택에 포함되어 있으며, 점검 모드일 때는 503 상태 코드와 함께 Symfony\Component\HttpKernel\Exception\HttpException이 발생합니다.

점검 모드를 활성화하려면 down Artisan 명령어를 실행하세요.

php artisan down

모든 점검 모드 응답에 Refresh HTTP 헤더를 포함시키려면 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"

점검 모드를 활성화한 후 해당 토큰이 포함된 URL로 접속하면, Laravel이 브라우저에 점검 모드 우회 쿠키를 발급합니다.

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Laravel이 시크릿 토큰을 자동으로 생성하게 하려면 with-secret 옵션을 사용하세요. 점검 모드 활성화 직후 시크릿이 출력됩니다.

php artisan down --with-secret

이 숨겨진 라우트에 접속하면 애플리케이션의 / 라우트로 리다이렉트됩니다. 쿠키가 발급된 후에는 점검 모드가 아닌 것처럼 애플리케이션을 정상적으로 이용할 수 있습니다.

NOTE

점검 모드 시크릿은 일반적으로 영문자, 숫자, 그리고 선택적으로 하이픈(-)으로 구성하는 것을 권장합니다. URL에서 특별한 의미를 갖는 ?나 & 같은 문자는 사용하지 마세요.

다중 서버 환경에서의 점검 모드

기본적으로 Laravel은 파일 기반 시스템으로 점검 모드 여부를 판단합니다. 따라서 점검 모드를 활성화하려면 애플리케이션을 호스팅하는 모든 서버에서 php artisan down 명령어를 실행해야 합니다.

이 대신 캐시 기반 점검 모드 처리 방식을 사용할 수 있습니다. 이 방식은 한 서버에서만 php artisan down 명령어를 실행하면 됩니다. 적용하려면 .env 파일에서 점검 모드 관련 변수를 수정하세요. 모든 서버에서 접근 가능한 캐시 store를 선택해야 점검 모드 상태가 전체 서버에 일관되게 적용됩니다.

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

점검 모드 뷰 사전 렌더링

배포 과정 중 php artisan down 명령어를 사용하면 Composer 의존성이나 인프라 구성 요소가 업데이트되는 동안 접속한 사용자가 오류 화면을 볼 수 있습니다. 이는 점검 모드 여부를 확인하고 뷰를 렌더링하기 위해 Laravel 프레임워크의 상당 부분이 먼저 부팅되어야 하기 때문입니다.

이 문제를 해결하기 위해 Laravel은 요청 사이클의 매우 초기에 반환될 점검 모드 뷰를 미리 렌더링할 수 있는 기능을 제공합니다. 이 뷰는 애플리케이션 의존성이 로드되기 전에 렌더링됩니다. down 명령어의 render 옵션을 사용해 원하는 템플릿을 사전 렌더링하세요.

php artisan down --render="errors::503"

점검 모드 요청 리다이렉트

점검 모드 중에는 사용자가 접속하려는 모든 URL에 점검 모드 뷰가 표시됩니다. 모든 요청을 특정 URL로 리다이렉트하고 싶다면 redirect 옵션을 사용하세요. 예를 들어 모든 요청을 /로 리다이렉트하려면 다음과 같이 실행합니다.

php artisan down --redirect=/

점검 모드 비활성화

점검 모드를 해제하려면 up 명령어를 사용하세요.

php artisan up

NOTE

resources/views/errors/503.blade.php 파일을 생성하면 기본 점검 모드 템플릿을 원하는 대로 커스터마이징할 수 있습니다.

점검 모드와 큐

애플리케이션이 점검 모드인 동안에는 큐에 등록된 Job이 처리되지 않습니다. 점검 모드가 해제되면 Job들은 정상적으로 다시 처리됩니다.

점검 모드 대안

점검 모드를 사용하면 애플리케이션이 잠시 다운타임을 가질 수밖에 없습니다. 무중단 배포가 필요하다면 Laravel Cloud 같은 완전 관리형 플랫폼을 활용하는 것을 고려해 보세요.