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 환경에서 동작하는 경량 개발 환경입니다. 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 패키지로 설치합니다:

composer global require laravel/valet

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

valet install

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

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

PHP 버전 관리

NOTE

글로벌 PHP 버전을 변경하지 않고, isolate 명령어를 사용해 사이트별로 PHP 버전을 지정할 수도 있습니다.

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

valet use php@8.2valet use php

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

php=php@8.2

이 파일이 있으면 valet use 명령어 실행 시 파일을 읽어 해당 버전을 자동으로 적용합니다.

WARNING

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

데이터베이스

애플리케이션에 데이터베이스가 필요하다면 DBngin을 추천합니다. MySQL, PostgreSQL, Redis를 모두 포함하는 무료 올인원 데이터베이스 관리 도구입니다. 설치 후 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를 통해 PHP 8.0 이상 버전도 함께 설치해 두세요.

사이트 서비스

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

`park` 명령어

park 명령어는 여러 애플리케이션이 모여 있는 디렉토리를 Valet에 등록합니다. 등록("park")된 디렉토리 안의 모든 하위 디렉토리는 http://<디렉토리명>.test 형태로 브라우저에서 바로 접근할 수 있습니다:

cd ~/Sitesvalet park

이것으로 끝입니다. 이제 "parked" 디렉토리 안에 새 애플리케이션 디렉토리를 만들기만 하면 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 명령어에 원하는 이름을 인수로 전달하세요. 예를 들어 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 도메인에 TLS를 적용하려면:

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 버전에 맞는 CLI나 도구로 자동 프록시됩니다:

valet phpvalet composervalet which-php

격리된 모든 사이트와 해당 PHP 버전 목록은 isolated 명령어로 확인합니다:

valet isolated

글로벌 PHP 버전으로 되돌리려면 사이트 루트 디렉토리에서 unisolate 명령어를 실행하세요:

valet unisolate

Valet은 로컬 사이트를 외부에 공유하는 기능을 내장하고 있어, 모바일 기기에서 테스트하거나 팀원·클라이언트와 사이트를 공유할 때 편리합니다.

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

valet share-tool ngrok

선택한 도구가 설치되어 있지 않으면(ngrok, cloudflared는 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=eu처럼 share 명령어에 ngrok 파라미터를 추가로 전달할 수 있습니다. 자세한 내용은 ngrok 공식 문서를 참고하세요.

Expose를 사용하려면 Expose 계정을 만들고 인증 토큰으로 로그인하세요. 지원하는 추가 명령줄 옵션은 Expose 공식 문서를 참고하세요.

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

같은 로컬 네트워크에 있는 다른 기기(예: 스마트폰, 태블릿)에서 Mac의 IP 주소(192.168.1.10/application.test 등)로 접근하려면, 해당 사이트의 Nginx 설정 파일에서 listen 지시어의 127.0.0.1: 접두사를 제거해야 합니다.

valet secure를 실행하지 않은 사이트라면 /usr/local/etc/nginx/valet/valet.conf 파일을 수정하고, HTTPS가 적용된 사이트(valet secure 실행)라면 ~/.config/valet/Nginx/앱이름.test 파일을 수정하세요.

설정 수정 후에는 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를 동시에 실행해야 하는 경우, 둘 다 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를 위해 직접 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의 경우:

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

`isStaticFile` 메서드

isStaticFile 메서드는 요청이 이미지나 CSS 같은 정적 파일에 대한 것인지 판단합니다. 정적 파일이라면 해당 파일의 절대 경로를, 그렇지 않으면 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;
    }

    /**
     * 애플리케이션 프론트 컨트롤러의 절대 경로를 반환합니다.
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        return $sitePath.'/public_html/index.php';
    }
}

기타 Valet 명령어

명령어	설명
`valet list`	모든 Valet 명령어 목록을 표시합니다.
`valet diagnose`	Valet 디버깅을 위한 진단 정보를 출력합니다.
`valet directory-listing`	디렉토리 목록

Laravel Valet

소개

설치

PHP 버전 관리

데이터베이스

설치 초기화

Valet 업그레이드

Valet 4로 업그레이드

사이트 서비스

`park` 명령어

`link` 명령어

TLS로 사이트 보안 설정

기본 사이트 설정

사이트별 PHP 버전 지정

사이트 공유

ngrok으로 사이트 공유

Expose로 사이트 공유

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

사이트별 환경 변수

서비스 프록시

커스텀 Valet 드라이버

`serves` 메서드

`isStaticFile` 메서드

`frontControllerPath` 메서드

로컬 드라이버

기타 Valet 명령어