Laravel Valet

번역일: 2026년 6월 25일

Laravel Valet

소개
설치
- Valet 업그레이드
사이트 서빙
사이트 공유
- 로컬 네트워크에서 사이트 공유
사이트별 환경 변수
서비스 프록시
커스텀 Valet 드라이버
- 로컬 드라이버
기타 Valet 명령어
Valet 디렉터리 및 파일
- 디스크 접근 권한

소개

NOTE

macOS에서 Laravel 개발을 더 간편하게 시작하고 싶다면 Laravel Herd를 살펴보세요. Herd는 Valet, PHP, Composer를 포함한 Laravel 개발에 필요한 모든 것을 한 번에 제공합니다.

Laravel Valet은 macOS 환경에 최적화된 미니멀리스트 개발 환경입니다. Valet은 Mac이 시작될 때 백그라운드에서 Nginx가 항상 실행되도록 구성하고, DnsMasq를 사용해 *.test 도메인으로 들어오는 모든 요청을 로컬 머신에 설치된 사이트로 프록시합니다.

한마디로, Valet은 약 7MB의 RAM만 사용하는 초고속 Laravel 개발 환경입니다. Sail이나 Homestead를 완전히 대체하는 것은 아니지만, 가볍고 빠른 환경을 선호하거나 RAM이 제한된 머신에서 작업하는 개발자에게 훌륭한 대안입니다.

Valet은 기본적으로 다음 프레임워크 및 CMS를 지원합니다(이 외에도 많습니다):

지원하지 않는 프레임워크나 CMS는 커스텀 드라이버를 작성해 추가할 수 있습니다.

설치

WARNING

Valet은 macOS와 Homebrew가 필요합니다. 설치 전에 Apache나 Nginx 같은 다른 프로그램이 로컬 머신의 포트 80을 사용하고 있지 않은지 확인하세요.

먼저 Homebrew를 최신 상태로 업데이트합니다:

brew update

다음으로 Homebrew를 통해 PHP를 설치합니다:

brew install php

PHP 설치가 완료되면 Composer 패키지 매니저를 설치합니다. 또한 $HOME/.composer/vendor/bin 디렉터리가 시스템 PATH에 포함되어 있는지 확인하세요. Composer 설치 후 Laravel Valet을 글로벌 Composer 패키지로 설치합니다:

composer global require laravel/valet

마지막으로 Valet의 install 명령어를 실행합니다. 이 명령어는 Valet과 DnsMasq를 설정하고 설치하며, Valet이 의존하는 데몬들이 시스템 시작 시 자동으로 실행되도록 구성합니다:

valet install

설치가 완료되면 터미널에서 ping foobar.test와 같이 *.test 도메인에 핑을 보내 확인합니다. Valet이 정상적으로 설치되었다면 127.0.0.1에서 응답이 돌아와야 합니다.

Valet은 머신이 부팅될 때마다 필요한 서비스를 자동으로 시작합니다.

PHP 버전

NOTE

전역 PHP 버전을 변경하는 대신, isolate 명령어를 사용해 사이트별로 PHP 버전을 지정할 수 있습니다.

Valet은 valet use php@version 명령어로 PHP 버전을 전환할 수 있습니다. 지정한 버전이 아직 설치되어 있지 않으면 Homebrew를 통해 자동으로 설치합니다:

valet use php@8.1valet use php

프로젝트 루트에 .valetrc 파일을 생성해 사이트에서 사용할 PHP 버전을 지정할 수도 있습니다:

php=php@8.1

이 파일을 생성한 후 valet use 명령어를 실행하면 Valet이 파일을 읽어 해당 사이트에 맞는 PHP 버전을 자동으로 선택합니다.

WARNING

여러 PHP 버전이 설치되어 있더라도 Valet은 한 번에 하나의 PHP 버전만 서빙합니다.

데이터베이스

애플리케이션에 데이터베이스가 필요하다면 DBngin을 확인해 보세요. MySQL, PostgreSQL, Redis를 포함한 무료 올인원 데이터베이스 관리 도구입니다. DBngin을 설치하면 root 사용자 이름과 빈 비밀번호로 127.0.0.1에 접속할 수 있습니다.

설치 초기화

Valet이 제대로 동작하지 않는다면 composer global require laravel/valet 명령어 실행 후 valet install을 실행해 설치를 초기화하면 대부분의 문제를 해결할 수 있습니다. 드물게 valet uninstall --force 후 valet install을 실행하는 강제 초기화가 필요할 수 있습니다.

Valet 업그레이드

터미널에서 composer global require laravel/valet 명령어를 실행하면 Valet을 업데이트할 수 있습니다. 업그레이드 후에는 valet install을 실행하여 설정 파일을 최신 상태로 유지하는 것이 좋습니다.

Valet 4로 업그레이드

Valet 3에서 Valet 4로 업그레이드하는 경우 다음 단계를 따르세요:

사이트의 PHP 버전을 지정하기 위해 .valetphprc 파일을 사용하고 있었다면, 각 파일의 이름을 .valetrc로 변경하고 파일 내용 앞에 php=를 추가하세요.
커스텀 드라이버가 있다면 새 드라이버 시스템의 네임스페이스, 확장자, 타입 힌트, 반환 타입 힌트에 맞게 업데이트하세요. Valet의 SampleValetDriver를 참고할 수 있습니다.
PHP 7.1~7.4를 사용하고 있다면, Valet이 일부 스크립트 실행에 사용할 PHP 8.0 이상 버전을 Homebrew로 설치해 두세요. 이 버전이 기본 링크 버전이 아니어도 됩니다.

사이트 서빙

Valet 설치가 완료되면 Laravel 애플리케이션을 서빙할 준비가 된 것입니다. Valet은 애플리케이션 서빙을 위해 park와 link 두 가지 명령어를 제공합니다.

`park` 명령어

park 명령어는 애플리케이션들이 있는 디렉터리를 Valet에 등록합니다. 디렉터리가 "park"되면 그 안에 있는 모든 하위 디렉터리가 http://<디렉터리명>.test 형태로 브라우저에서 접근 가능해집니다:

cd ~/Sitesvalet park

이것으로 끝입니다. 이제 "parked" 디렉터리 안에 생성하는 모든 애플리케이션은 자동으로 http://<디렉터리명>.test 규칙으로 서빙됩니다. 예를 들어 parked 디렉터리 안에 "laravel"이라는 디렉터리가 있다면 http://laravel.test로 접근할 수 있습니다. 와일드카드 서브도메인(http://foo.laravel.test)도 자동으로 지원됩니다.

`link` 명령어

link 명령어는 디렉터리 전체가 아닌 특정 사이트 하나만 서빙하고 싶을 때 유용합니다:

cd ~/Sites/laravelvalet link

link 명령어로 연결된 애플리케이션은 디렉터리 이름을 기반으로 접근할 수 있습니다. 위 예시에서 연결된 사이트는 http://laravel.test로 접근할 수 있으며, 와일드카드 서브도메인(http://foo.laravel.test)도 자동으로 지원됩니다.

다른 호스트명으로 서빙하고 싶다면 link 명령어에 원하는 호스트명을 전달할 수 있습니다. 예를 들어 다음 명령어를 실행하면 http://application.test로 접근할 수 있습니다:

cd ~/Sites/laravelvalet link application

서브도메인으로도 서빙할 수 있습니다:

valet link api.application

연결된 모든 디렉터리 목록을 확인하려면 links 명령어를 사용합니다:

valet links

사이트의 심볼릭 링크를 제거하려면 unlink 명령어를 사용합니다:

cd ~/Sites/laravelvalet unlink

TLS로 사이트 보안 설정

기본적으로 Valet은 HTTP로 사이트를 서빙합니다. HTTP/2를 사용한 암호화된 TLS로 서빙하려면 secure 명령어를 사용하세요. 예를 들어 laravel.test 도메인을 보안 설정하려면 다음과 같이 실행합니다:

valet secure laravel

보안 설정을 해제하고 일반 HTTP로 되돌리려면 unsecure 명령어를 사용합니다:

valet unsecure laravel

기본 사이트 서빙

알 수 없는 test 도메인에 접근했을 때 404 대신 특정 사이트를 기본으로 서빙하고 싶다면 ~/.config/valet/config.json 설정 파일에 default 옵션을 추가하세요:

"default": "/Users/Sally/Sites/example-site",

사이트별 PHP 버전 지정

기본적으로 Valet은 전역 PHP를 사용해 사이트를 서빙합니다. 여러 사이트에서 각기 다른 PHP 버전을 사용해야 한다면 isolate 명령어로 특정 사이트에 사용할 PHP 버전을 지정할 수 있습니다. isolate 명령어는 현재 작업 디렉터리의 사이트에 지정한 PHP 버전을 적용합니다:

cd ~/Sites/example-sitevalet isolate php@8.0

사이트 이름이 디렉터리 이름과 다를 경우 --site 옵션으로 사이트 이름을 지정할 수 있습니다:

valet isolate php@8.0 --site="site-name"

편의를 위해 valet php, composer, which-php 명령어를 사용하면 사이트에 설정된 PHP 버전에 맞는 PHP CLI나 도구로 자동 전환됩니다:

valet phpvalet composervalet which-php

격리된 모든 사이트와 해당 PHP 버전 목록을 확인하려면 isolated 명령어를 사용합니다:

valet isolated

사이트를 전역 PHP 버전으로 되돌리려면 사이트 루트 디렉터리에서 unisolate 명령어를 실행합니다:

valet unisolate

Valet은 로컬 사이트를 외부에 공유하는 기능을 제공합니다. 모바일 기기에서 테스트하거나 팀원 및 클라이언트와 사이트를 공유할 때 유용합니다.

Valet은 기본적으로 ngrok과 Expose를 통한 사이트 공유를 지원합니다. 공유 전에 share-tool 명령어로 사용할 도구를 지정하세요:

valet share-tool ngrok

선택한 도구가 설치되어 있지 않으면(ngrok은 Homebrew, Expose는 Composer), Valet이 자동으로 설치를 안내합니다. 두 도구 모두 사이트 공유를 시작하기 전에 계정 인증이 필요합니다.

사이트를 공유하려면 터미널에서 사이트 디렉터리로 이동한 후 share 명령어를 실행하세요. 공개 접근 가능한 URL이 클립보드에 복사되어 브라우저에 바로 붙여넣거나 팀원에게 공유할 수 있습니다:

cd ~/Sites/laravelvalet share

공유를 중지하려면 Control + C를 누르세요.

WARNING

1.1.1.1과 같은 커스텀 DNS 서버를 사용하는 경우 ngrok 공유가 제대로 동작하지 않을 수 있습니다. 이 경우 Mac의 시스템 설정 → 네트워크 → 고급 → DNS 탭에서 127.0.0.1을 첫 번째 DNS 서버로 추가하세요.

ngrok을 사용한 사이트 공유를 위해서는 ngrok 계정 생성 및 인증 토큰 설정이 필요합니다. 인증 토큰을 발급받은 후 Valet 설정에 등록하세요:

valet set-ngrok-token YOUR_TOKEN_HERE

NOTE

valet share --region=eu와 같이 share 명령어에 추가 ngrok 파라미터를 전달할 수 있습니다. 자세한 내용은 ngrok 공식 문서를 참고하세요.

Expose를 사용한 사이트 공유를 위해서는 Expose 계정 생성 및 인증 토큰으로 인증이 필요합니다.

지원하는 추가 명령행 파라미터에 대해서는 Expose 공식 문서를 참고하세요.

Valet은 기본적으로 인터넷으로부터의 보안 위험을 방지하기 위해 내부 127.0.0.1 인터페이스로만 트래픽을 허용합니다.

로컬 네트워크의 다른 기기에서 머신의 IP 주소(예: 192.168.1.10/application.test)로 Valet 사이트에 접근하려면 해당 사이트의 Nginx 설정 파일을 직접 수정해 listen 지시어의 제한을 제거해야 합니다. 포트 80과 443의 listen 지시어에서 127.0.0.1: 접두사를 제거하면 됩니다.

valet secure를 실행하지 않은 프로젝트라면 /usr/local/etc/nginx/valet/valet.conf 파일을 편집해 모든 비HTTPS 사이트의 네트워크 접근을 열 수 있습니다. HTTPS로 서빙 중인 사이트(valet secure를 실행한 경우)라면 ~/.config/valet/Nginx/app-name.test 파일을 편집하세요.

Nginx 설정을 업데이트한 후 valet restart 명령어를 실행해 변경 사항을 적용하세요.

사이트별 환경 변수

일부 프레임워크 기반 애플리케이션은 서버 환경 변수에 의존하지만 프로젝트 내에서 해당 변수를 설정하는 방법을 제공하지 않는 경우가 있습니다. Valet은 프로젝트 루트에 .valet-env.php 파일을 추가해 사이트별 환경 변수를 설정할 수 있습니다. 이 파일은 사이트/환경 변수 쌍의 배열을 반환해야 하며, 배열에 지정된 각 사이트에 대해 전역 $_SERVER 배열에 추가됩니다:

<?php

return [
    // laravel.test 사이트에 대해 $_SERVER['key']를 "value"로 설정...
    'laravel' => [
        'key' => 'value',
    ],

    // 모든 사이트에 대해 $_SERVER['key']를 "value"로 설정...
    '*' => [
        'key' => 'value',
    ],
];

서비스 프록시

로컬 머신의 다른 서비스로 Valet 도메인을 프록시해야 할 때가 있습니다. 예를 들어 Valet을 실행하면서 Docker로 별도 사이트를 운영해야 하는 경우가 있는데, Valet과 Docker가 동시에 포트 80을 사용할 수는 없습니다.

이럴 때 proxy 명령어를 사용합니다. 예를 들어 http://elasticsearch.test의 모든 트래픽을 http://127.0.0.1:9200으로 프록시하려면 다음과 같이 실행합니다:

# HTTP로 프록시...valet proxy elasticsearch http://127.0.0.1:9200# TLS + HTTP/2로 프록시...valet proxy elasticsearch http://127.0.0.1:9200 --secure

프록시를 제거하려면 unproxy 명령어를 사용합니다:

valet unproxy elasticsearch

프록시로 설정된 모든 사이트 목록을 확인하려면 proxies 명령어를 사용합니다:

valet proxies

커스텀 Valet 드라이버

Valet이 기본적으로 지원하지 않는 프레임워크나 CMS를 사용하는 PHP 애플리케이션을 서빙하려면 커스텀 Valet "드라이버"를 작성할 수 있습니다. Valet을 설치하면 ~/.config/valet/Drivers 디렉터리가 생성되며, 그 안에 커스텀 드라이버 작성 방법을 보여주는 SampleValetDriver.php 예시 파일이 포함되어 있습니다.

커스텀 드라이버는 serves, isStaticFile, frontControllerPath 세 가지 메서드만 구현하면 됩니다.

세 메서드 모두 $sitePath, $siteName, $uri를 인수로 받습니다. $sitePath는 머신에서 서빙 중인 사이트의 전체 경로(예: /Users/Lisa/Sites/my-project)이고, $siteName은 도메인의 "호스트"/"사이트 이름" 부분(my-project)이며, $uri는 들어오는 요청 URI(/foo/bar)입니다.

커스텀 드라이버 작성이 완료되면 FrameworkValetDriver.php 네이밍 규칙에 따라 ~/.config/valet/Drivers 디렉터리에 파일을 배치하세요. 예를 들어 WordPress용 커스텀 드라이버를 작성한다면 파일명은 WordPressValetDriver.php가 됩니다.

`serves` 메서드

serves 메서드는 드라이버가 해당 요청을 처리해야 하면 true를, 그렇지 않으면 false를 반환해야 합니다. 이 메서드 안에서 주어진 $sitePath가 서빙하려는 유형의 프로젝트를 포함하는지 확인하세요.

예를 들어 WordPressValetDriver를 작성한다면 serves 메서드는 다음과 같이 작성할 수 있습니다:

/**
 * 드라이버가 해당 요청을 처리할지 결정합니다.
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

`isStaticFile` 메서드

isStaticFile 메서드는 들어오는 요청이 이미지나 스타일시트 같은 "정적" 파일에 대한 것인지 확인해야 합니다. 정적 파일이라면 디스크에 있는 해당 파일의 전체 경로를 반환하고, 그렇지 않으면 false를 반환합니다:

/**
 * 들어오는 요청이 정적 파일에 대한 것인지 확인합니다.
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }

    return false;
}

WARNING

isStaticFile 메서드는 serves 메서드가 true를 반환하고 요청 URI가 /가 아닌 경우에만 호출됩니다.

`frontControllerPath` 메서드

frontControllerPath 메서드는 애플리케이션의 "프론트 컨트롤러"(일반적으로 index.php 파일)에 대한 전체 경로를 반환해야 합니다:

/**
 * 애플리케이션의 프론트 컨트롤러 전체 경로를 반환합니다.
 */
public function frontControllerPath(string $sitePath, string $siteName, string $uri): string

Laravel Valet

소개

설치

PHP 버전

데이터베이스

설치 초기화

Valet 업그레이드

Valet 4로 업그레이드

사이트 서빙

`park` 명령어

`link` 명령어

TLS로 사이트 보안 설정

기본 사이트 서빙

사이트별 PHP 버전 지정

사이트 공유

ngrok으로 사이트 공유

Expose로 사이트 공유

로컬 네트워크에서 사이트 공유

사이트별 환경 변수

서비스 프록시

커스텀 Valet 드라이버

`serves` 메서드

`isStaticFile` 메서드

`frontControllerPath` 메서드