Laravel Valet

번역일: 2026년 6월 25일

Laravel Valet

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

소개

NOTE

macOS나 Windows에서 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 준비가 되었다면 Valet을 글로벌 패키지로 설치합니다:

composer global require laravel/valet

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

valet install

설치가 완료되면 터미널에서 ping foobar.test 명령어로 *.test 도메인이 정상적으로 응답하는지 확인해보세요. 올바르게 설치되었다면 127.0.0.1로 응답이 돌아와야 합니다.

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

PHP 버전

NOTE

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

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

valet use php@8.2valet use php

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

php=php@8.2

이 파일이 있으면 valet use 명령어만 실행해도 Valet이 파일을 읽어 자동으로 올바른 PHP 버전을 사용합니다.

WARNING

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

데이터베이스

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

설치 초기화

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를 사용해 사이트를 제공하고 있다면, Homebrew를 통해 PHP 8.0 이상 버전도 설치되어 있어야 합니다. Valet이 일부 스크립트 실행에 이 버전을 사용하기 때문입니다(기본 연결 버전이 아니어도 됩니다).

사이트 제공

Valet 설치가 완료되면 Laravel 애플리케이션을 바로 제공할 수 있습니다. Valet은 사이트 제공을 위해 park와 link 두 가지 명령어를 제공합니다.

`park` 명령어

park 명령어는 여러 애플리케이션이 들어 있는 디렉터리 전체를 Valet에 등록합니다. 한 번 "파킹"하면 그 안의 모든 하위 디렉터리가 http://<디렉터리명>.test 형태의 URL로 자동으로 접근 가능해집니다:

cd ~/Sitesvalet park

이게 전부입니다. 이제 파킹된 디렉터리 안에 새 프로젝트를 만들기만 하면 자동으로 http://<디렉터리명>.test로 접근할 수 있습니다. 예를 들어 파킹된 디렉터리 안에 laravel이라는 디렉터리가 있다면 http://laravel.test로 접근할 수 있습니다. 와일드카드 서브도메인(http://foo.laravel.test)도 자동으로 지원됩니다.

`link` 명령어

link 명령어는 디렉터리 전체가 아닌 특정 사이트 하나만 Valet에 등록할 때 사용합니다:

cd ~/Sites/laravelvalet link

링크가 완료되면 디렉터리 이름을 기반으로 http://laravel.test에서 애플리케이션에 접근할 수 있습니다. 와일드카드 서브도메인(http://foo.laravel.test)도 자동으로 지원됩니다.

다른 호스트명으로 접근하고 싶다면 link 명령어에 원하는 이름을 인수로 전달합니다:

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/홍길동/Sites/example-site",

사이트별 PHP 버전 지정

기본적으로 Valet은 전역 PHP 설치를 사용합니다. 여러 사이트에서 서로 다른 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 버전으로 자동으로 프록시되어 실행됩니다:

valet phpvalet composervalet which-php

격리(isolated) 설정된 모든 사이트와 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 여기에_토큰_입력

NOTE

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

Expose를 사용하려면 Expose 계정을 만들고 인증 토큰으로 로그인해야 합니다.

지원하는 추가 옵션은 Expose 공식 문서를 참고하세요.

기본적으로 Valet은 인터넷으로부터 개발 머신을 보호하기 위해 내부 127.0.0.1 인터페이스로만 트래픽을 허용합니다.

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

valet secure를 실행하지 않은 프로젝트(HTTPS가 아닌 경우)라면 /usr/local/etc/nginx/valet/valet.conf 파일을 수정합니다. HTTPS로 제공 중인 경우(valet secure를 실행한 경우)에는 ~/.config/valet/Nginx/앱이름.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/홍길동/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
{
    return $sitePath.'/public/index.php';
}

로컬 드라이버

특정 애플리케이션 하나에만 적용되는 커스텀 드라이버가 필요하다면, 해당 애플리케이션의 루트 디렉터리에 LocalValetDriver.php 파일을 만드세요. 로컬 드라이버는 기본 ValetDriver 클래스나 LaravelValetDriver 같은 기존 드라이버를 상속할 수 있습니다:

use Valet\Drivers\LaravelValetDriver;

class LocalValetDriver extends LaravelValetDriver
{
    /**
     * 이 드라이버가 요청을 처리해야 하는지 판단합니다.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }

    /**

Laravel Valet

소개

설치

PHP 버전

데이터베이스

설치 초기화

Valet 업그레이드

Valet 4로 업그레이드

사이트 제공

`park` 명령어

`link` 명령어

TLS로 사이트 보안 설정

기본 사이트 설정

사이트별 PHP 버전 지정

사이트 공유

ngrok으로 사이트 공유

Expose로 사이트 공유

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

사이트별 환경 변수

서비스 프록시

커스텀 Valet 드라이버

`serves` 메서드

`isStaticFile` 메서드

`frontControllerPath` 메서드

로컬 드라이버