Laravel Valet

• 简介
• 安装
  • 升级 Valet
• 提供服务
  • "Park" 命令
  • "Link" 命令
  • 使用 TLS 保护站点
  • 提供默认站点
  • 每个站点的 PHP 版本
• 共享站点
  • 在本地网络上共享站点
• 站点特定环境变量
• 代理服务
• 自定义 Valet 驱动
  • 本地驱动
• 其他 Valet 命令
• Valet 目录和文件
  • 磁盘访问

简介

NOTE

想在 macOS 或 Windows 上使用更简单的方式开发 Laravel 应用程序吗？试试 Laravel Herd。Herd 包含了 Laravel 开发入门所需的一切，包括 Valet、PHP 和 Composer。

Laravel Valet 是为 macOS 极简主义者打造的一款开发环境。Laravel Valet 会配置你的 Mac，使其在开机时始终在后台运行 Nginx。然后，使用 DnsMasq，Valet 代理所有对 *.test 域的请求，指向你本地机器上安装的站点。

换句话说，Valet 是一个极快的 Laravel 开发环境，仅占用大约 7 MB 内存。Valet 不能完全替代 Sail 或 Homestead，但如果你想要灵活的基础功能、追求极速，或者使用的机器内存有限，Valet 是一个很好的替代方案。

开箱即用，Valet 支持包括但不限于以下框架/CMS：

• Laravel
• Bedrock
• CakePHP 3
• ConcreteCMS
• Contao
• Craft
• Drupal
• ExpressionEngine
• Jigsaw
• Joomla
• Katana
• Kirby
• Magento
• OctoberCMS
• Sculpin
• Slim
• Statamic
• 静态 HTML
• Symfony
• WordPress
• Zend

不过，你也可以通过自己的 自定义驱动 来扩展 Valet。

安装

WARNING

Valet 需要 macOS 和 Homebrew。安装前，请确保没有其他程序（如 Apache 或 Nginx）绑定到本地机器的 80 端口。

首先，你需要使用 update 命令确保 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

安装 Valet 后，尝试在终端中使用诸如 ping foobar.test 的命令 ping 任意 *.test 域。如果 Valet 安装正确，你应该能看到该域响应 127.0.0.1。

Valet 将在每次机器启动时自动启动其所需的服务。

PHP 版本

NOTE

除了修改全局 PHP 版本外，你还可以通过 isolate 命令 让 Valet 对每个站点使用不同的 PHP 版本。

Valet 允许你使用 valet use php@version 命令切换 PHP 版本。如果指定的 PHP 版本尚未安装，Valet 将通过 Homebrew 安装它：

valet use php@8.2

valet use php

你还可以在项目的根目录创建一个 .valetrc 文件。.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。

升级 Valet

你可以通过在终端中执行 composer global require laravel/valet 命令来更新 Valet 安装。升级后，最好运行 valet install 命令，以便 Valet 在必要时对你的配置文件进行额外升级。

升级到 Valet 4

如果你正在从 Valet 3 升级到 Valet 4，请执行以下步骤以正确升级你的 Valet 安装：

• 如果你添加了 .valetphprc 文件来自定义站点的 PHP 版本，请将每个 .valetphprc 文件重命名为 .valetrc。然后，在 .valetrc 文件的现有内容前加上 php=。
• 更新任何自定义驱动，使其符合新驱动系统的命名空间、扩展、类型提示和返回类型提示。你可以参考 Valet 的 SampleValetDriver 作为示例。
• 如果你使用 PHP 7.1 - 7.4 来提供服务，请确保你仍然使用 Homebrew 安装一个版本 >= 8.0 的 PHP，因为 Valet 将使用此版本（即使它不是你的主要链接版本）来运行其某些脚本。

提供服务

安装 Valet 后，你就可以开始为 Laravel 应用程序提供服务了。Valet 提供了两个命令来帮助你提供应用程序：park 和 link。

park 命令

park 命令在你的机器上注册一个包含你应用程序的目录。一旦该目录被 Valet“停放”后，该目录下的所有子目录都可以通过你的 Web 浏览器以 http://<directory-name>.test 的形式访问：

cd ~/Sites

valet park

就这样。现在，你在“停放”目录中创建的任何应用程序都将自动使用 http://<directory-name>.test 约定提供服务。因此，如果你的停放目录包含一个名为 "laravel" 的目录，那么该目录中的应用程序就可以通过 http://laravel.test 访问。此外，Valet 会自动允许你使用通配符子域（http://foo.laravel.test）访问该站点。

link 命令

link 命令也可以用来为你的 Laravel 应用程序提供服务。如果你想为目录中的单个站点提供服务，而不是整个目录，此命令非常有用：

cd ~/Sites/laravel

valet link

一旦应用程序使用 link 命令链接到 Valet，你就可以使用其目录名访问该应用程序。因此，上面示例中链接的站点可以通过 http://laravel.test 访问。此外，Valet 会自动允许你使用通配符子域（http://foo.laravel.test）访问该站点。

如果你想使用不同的主机名来提供服务，可以将主机名传递给 link 命令。例如，你可以运行以下命令，使应用程序可以通过 http://application.test 访问：

cd ~/Sites/laravel

valet link application

当然，你也可以使用 link 命令在子域上提供服务：

valet link api.application

你可以执行 links 命令来显示所有链接目录的列表：

valet links

unlink 命令可用于销毁站点的符号链接：

cd ~/Sites/laravel

valet unlink

使用 TLS 保护站点

默认情况下，Valet 通过 HTTP 提供服务。但是，如果你想通过加密的 TLS（使用 HTTP/2）提供服务，可以使用 secure 命令。例如，如果你的站点在 laravel.test 域上由 Valet 提供服务，则应运行以下命令来保护它：

valet secure laravel

要“解除保护”一个站点并恢复为通过纯 HTTP 提供服务，请使用 unsecure 命令。与 secure 命令一样，此命令接受你想要解除保护的主机名：

valet unsecure laravel

提供默认站点

有时，你可能希望配置 Valet，使其在访问未知的 test 域时提供一个“默认”站点，而不是返回 404。为此，你可以在 ~/.config/valet/config.json 配置文件中添加一个 default 选项，其中包含应作为默认站点的路径：

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

每个站点的 PHP 版本

默认情况下，Valet 使用全局 PHP 安装来为你的站点提供服务。但是，如果你需要在不同的站点上支持多个 PHP 版本，可以使用 isolate 命令来指定特定站点应使用的 PHP 版本。isolate 命令会配置 Valet，对当前工作目录中的站点使用指定的 PHP 版本：

cd ~/Sites/example-site

valet isolate php@8.0

如果你的站点名称与其所在目录的名称不匹配，可以使用 --site 选项指定站点名称：

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

为了方便，你可以使用 valet php、composer 和 which-php 命令，根据站点配置的 PHP 版本将调用代理到相应的 PHP CLI 或工具：

valet php
valet composer
valet which-php

你可以执行 isolated 命令来显示所有隔离站点及其 PHP 版本的列表：

valet isolated

要将站点恢复到 Valet 全局安装的 PHP 版本，你可以在站点根目录下调用 unisolate 命令：

valet unisolate

共享站点

Valet 包含一个命令，可以将你的本地站点与世界共享，这为在移动设备上测试你的站点或与团队成员和客户共享提供了一种简单的方法。

开箱即用，Valet 支持通过 ngrok 或 Expose 共享你的站点。在共享站点之前，你应该使用 share-tool 命令更新你的 Valet 配置，指定 ngrok、expose 或 cloudflared：

valet share-tool ngrok

如果你选择了一个工具，但尚未通过 Homebrew（对于 ngrok 和 cloudflared）或 Composer（对于 Expose）安装，Valet 将自动提示你安装它。当然，这两个工具都需要你先验证你的 ngrok 或 Expose 帐户，然后才能开始共享站点。

要共享一个站点，请在终端中导航到该站点的目录，然后运行 Valet 的 share 命令。一个可公开访问的 URL 将被放入你的剪贴板，并可直接粘贴到你的浏览器中或与你的团队共享：

cd ~/Sites/laravel

valet share

要停止共享你的站点，可以按 Control + C。

WARNING

如果你使用自定义 DNS 服务器（如 1.1.1.1），ngrok 共享可能无法正常工作。如果你遇到这种情况，请打开 Mac 的系统设置，进入网络设置，打开高级设置，然后转到 DNS 标签，将 127.0.0.1 添加为你的第一个 DNS 服务器。

通过 Ngrok 共享站点

使用 ngrok 共享你的站点需要你 创建一个 ngrok 帐户 并 设置一个身份验证令牌。获得身份验证令牌后，你可以使用该令牌更新你的 Valet 配置：

valet set-ngrok-token YOUR_TOKEN_HERE

NOTE

你可以向 share 命令传递额外的 ngrok 参数，例如 valet share --region=eu。有关更多信息，请查阅 ngrok 文档。

通过 Expose 共享站点

使用 Expose 共享你的站点需要你 创建一个 Expose 帐户 并 通过你的身份验证令牌对 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“驱动”来为运行在 Valet 本身不支持的框架或 CMS 上的 PHP 应用程序提供服务。安装 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）。

完成自定义 Valet 驱动后，请将其放置在 ~/.config/valet/Drivers 目录中，并使用 FrameworkValetDriver.php 命名约定。例如，如果你正在为 WordPress 编写一个自定义 Valet 驱动，你的文件名应该是 WordPressValetDriver.php。

让我们来看看你的自定义 Valet 驱动应实现的每个方法的示例实现。

serves 方法

如果你的驱动应该处理传入的请求，serves 方法应返回 true。否则，该方法应返回 false。因此，在此方法中，你应该尝试确定给定的 $sitePath 是否包含你试图提供服务的项目类型。

例如，假设我们正在编写一个 WordPressValetDriver。我们的 serves 方法可能如下所示：

/**
 * Determine if the driver serves the request.
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

isStaticFile 方法

isStaticFile 应确定传入的请求是否针对“静态”文件，例如图像或样式表。如果文件是静态的，该方法应返回磁盘上静态文件的完整路径。如果传入的请求不是针对静态文件的，该方法应返回 false：

/**
 * Determine if the incoming request is for a static file.
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }

    return false;
}

WARNING

仅当 serves 方法为传入请求返回 true 且请求 URI 不是 / 时，才会调用 isStaticFile 方法。

frontControllerPath 方法

frontControllerPath 方法应返回应用程序的“前端控制器”的完整路径，这通常是一个“index.php”文件或类似文件：

/**
 * Get the fully resolved path to the application's front controller.
 */
public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
{
    return $sitePath.'/public/index.php';
}

本地驱动

如果你想为单个应用程序定义一个自定义 Valet 驱动，请在应用程序的根目录中创建一个 LocalValetDriver.php 文件。你的自定义驱动可以扩展基础的 ValetDriver 类，或扩展现有的特定于应用程序的驱动，例如 LaravelValetDriver：

use Valet\Drivers\LaravelValetDriver;

class LocalValetDriver extends LaravelValetDriver
{
    /**
     * Determine if the driver serves the request.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }

    /**
     * Get the fully resolved path to the application's front controller.
     */
    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/

此目录包含所有 链接项目 的符号链接。

~/.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“完全磁盘访问权限”。否则，你可能会遇到服务器错误或 Nginx 的其他不可预测行为，尤其是在提供静态资源时。通常，macOS 会自动提示你授予 Nginx 对这些位置的完全访问权限。或者，你可以通过 系统偏好设置 > 安全性与隐私 > 隐私 并选择 完全磁盘访问权限 来手动执行此操作。接下来，在主窗口窗格中启用所有 nginx 条目。