Laravel Valet

업데이트됨

번역일: 2026년 7월 28일

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

원문 수정: 2026년 7월 28일
번역 갱신: 2026년 7월 28일

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 패키지로 설치합니다:

composer global require laravel/valet

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

valet install

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

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

PHP 버전

NOTE

전역 PHP 버전을 변경하지 않고 사이트별로 다른 PHP 버전을 사용하려면 isolate 명령어를 사용하세요.

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

valet use php@8.2valet use php

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

php=php@8.2

이 파일을 만들어 두면 valet use 명령어만 실행해도 파일을 읽어 적절한 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로 사이트를 서비스하고 있다면, Homebrew를 통해 PHP 8.0 이상 버전도 설치되어 있는지 확인하세요. Valet은 일부 스크립트 실행 시 이 버전을 사용합니다.

사이트 제공

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

`park` 명령어

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

cd ~/Sitesvalet park

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

`link` 명령어

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

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/Sally/Sites/example-site",

사이트별 PHP 버전 지정

기본적으로 Valet은 전역 PHP 버전으로 사이트를 서비스합니다. 여러 사이트에서 서로 다른 PHP 버전을 사용해야 한다면 isolate 명령어로 사이트마다 별도의 PHP 버전을 지정할 수 있습니다. 현재 작업 디렉토리의 사이트에 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 버전을 확인하려면:

valet isolated

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

valet unisolate

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

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

valet share-tool ngrok

선택한 도구가 설치되어 있지 않으면 Valet이 자동으로 설치를 안내합니다. 각 도구를 사용하려면 해당 서비스(ngrok 또는 Expose)에 계정 인증이 필요합니다.

사이트를 공유하려면 해당 사이트 디렉토리에서 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와 같이 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 파일을 편집해 모든 HTTP 사이트의 네트워크 접근을 열 수 있습니다. 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를 동시에 실행해야 하는 경우, 두 서비스가 포트 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

프록시 설정된 사이트 목록을 확인하려면:

valet proxies

커스텀 Valet 드라이버

Valet이 기본으로 지원하지 않는 프레임워크나 CMS를 위해 직접 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 메서드는 들어온 요청이 이미지나 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`	디렉토리 목록 표시 동작을 설정합니다. 기본값은 "off"로, 디렉토리 접근 시 404를 반환합니다.
`valet forget`	파킹된 디렉토리에서 실행하면 해당 디렉토리를 파킹 목록에서 제거합니다.
`valet log`	Valet 서비스가 기록한 로그 목록을 확인합니다.
`valet paths`	파킹된 모든 경로를 표시합니다.
`valet restart`	Valet 데몬을 재시작합니다.
`valet start`	Valet 데몬을 시작합니다.
`valet stop`	Valet 데몬을 중지합니다.
`valet trust`	Brew와 Valet에 sudoers 파일을 추가해 비밀번호 입력 없이 Valet 명령어를 실행할 수 있도록 합니다.
`valet uninstall`	Valet을 제거합니다. `--force` 옵션을 사용하면 Valet 관련 파일을 모두 강제 삭제합니다.

Valet 디렉토리 및 파일

Valet 환경 문제를 진단할 때 다음 디렉토리와 파일 정보가 도움이 됩니다:

`~/.config/valet`

Valet의 모든 설정이 저장되는 디렉토리입니다. 정기적으로 백업해 두는 것을 권장합니다.

`~/.config/valet/dnsmasq.d/`

DNSMasq 설정 파일이 저장되는 디렉토리입니다.

`~/.config/valet/Drivers/`

Valet 드라이버가 저장되는 디렉토리입니다. 드라이버는 각 프레임워크/CMS를 어떻게 서비스할지 결정합니다.

`~/.config/valet/Nginx/`

Valet의 모든 Nginx 사이트 설정 파일이 저장되는 디렉토리입니다. install과 secure 명령어 실행 시 다시 생성됩니다.

`~/.config/valet/Sites/`

link 명령어로 연결된 프로젝트들의 심볼릭 링크가 저장됩니다.

`~/.config/valet/config.json`

Valet의 메인 설정 파일입니다.

`~/.config/valet/valet.sock`

Valet의 Nginx가 사용하는 PHP-FPM 소켓 파일입니다. PHP가 정상적으로 실행 중일 때만 존재합니다.

`~/.config/valet/Log/fpm-php.www.log`

PHP 오류의 사용자 로그 파일입니다.

`~/.config/valet/Log/nginx-error.log`

Nginx 오류의 사용자 로그 파일입니다.

`/usr/local/var/log/php-fpm.log`

PHP-FPM 오류의 시스템 로그 파일입니다.

`/usr/local/var/log/nginx`

Nginx의 접근 로그와 오류 로그가 저장되는 디렉토리입니다.

`/usr/local/etc/php/X.X/conf.d`

다양한 PHP 설정을 위한 *.ini 파일들이 저장되는 디렉토리입니다.

`/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf`

PHP-FPM 풀 설정 파일입니다.

`~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf`

사이트 SSL 인증서 생성에 사용되는 기본 Nginx 설정 파일입니다.

디스크 접근

macOS 10.14부터 일부 파일과 디렉토리에 대한 접근이 기본적으로 제한됩니다. 데스크탑, 문서, 다운로드 디렉토리와 네트워크 볼륨, 이동식 볼륨이 이에 해당합니다. 따라서 Valet에서 사용할 사이트 폴더는 이러한 보호된 위치 밖에 두는 것을 권장합니다.

그러나 위와 같은 위치에서 사이트를 서비스해야 한다면 Nginx에 "전체 디스크 접근" 권한을 부여해야 합니다. 그렇지 않으면 특히 정적 파일을 서비스할 때 서버 오류나 예기치 않은 동작이 발생할 수 있습니다. 일반적으로 macOS가 자동으로 권한 부여 창을 띄워주지만, 수동으로 설정하려면 시스템 환경설정 > 보안 및 개인 정보 보호 > 개인 정보 보호 > 전체 디스크 접근에서 nginx 항목을 활성화하면 됩니다.

Laravel Valet

소개

설치

PHP 버전

데이터베이스

설치 초기화

Valet 업그레이드

Valet 4로 업그레이드

사이트 제공

`park` 명령어

`link` 명령어

TLS로 사이트 보안 적용

기본 사이트 설정

사이트별 PHP 버전 지정

사이트 공유

ngrok으로 사이트 공유

Expose로 사이트 공유

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

사이트별 환경 변수

서비스 프록시

커스텀 Valet 드라이버

`serves` 메서드

`isStaticFile` 메서드

`frontControllerPath` 메서드

로컬 드라이버

기타 Valet 명령어

Valet 디렉토리 및 파일

~/.config/valet

~/.config/valet/dnsmasq.d/

~/.config/valet/Drivers/

~/.config/valet/Nginx/

~/.config/valet/Sites/

~/.config/valet/config.json

~/.config/valet/valet.sock

~/.config/valet/Log/fpm-php.www.log

~/.config/valet/Log/nginx-error.log

/usr/local/var/log/php-fpm.log

/usr/local/var/log/nginx

/usr/local/etc/php/X.X/conf.d

/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf

~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf

디스크 접근

`~/.config/valet`

`~/.config/valet/dnsmasq.d/`

`~/.config/valet/Drivers/`

`~/.config/valet/Nginx/`

`~/.config/valet/Sites/`

`~/.config/valet/config.json`

`~/.config/valet/valet.sock`

`~/.config/valet/Log/fpm-php.www.log`

`~/.config/valet/Log/nginx-error.log`

`/usr/local/var/log/php-fpm.log`

`/usr/local/var/log/nginx`

`/usr/local/etc/php/X.X/conf.d`

`/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf`

`~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf`