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 支持包括但不限于：

• 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

您可以通过 isolate 命令指示 Valet 使用每个站点的 PHP 版本，而不是修改全局 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

Valet 一次只提供一个 PHP 版本，即使您安装了多个 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 为站点提供服务。但是，如果您想使用 HTTP/2 通过加密 TLS 为站点提供服务，可以使用 secure 命令。例如，如果您的站点由 Valet 在 laravel.test 域上提供服务，您应该运行以下命令来保护它：

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 文档 了解有关它支持的额外命令行参数的信息。

在本地网络上共享站点

Valet 默认将传入流量限制在内部 127.0.0.1 接口，以便您的开发机器不会暴露于来自 Internet 的安全风险。

如果您希望允许本地网络上的其他设备通过您机器的 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 驱动后，使用 FrameworkValetDriver.php 命名约定将其放置在 ~/.config/valet/Drivers 目录中。例如，如果您正在为 WordPress 编写自定义 valet 驱动，您的文件名应该是 WordPressValetDriver.php。

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

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';
}

本地驱动

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

use Valet\Drivers\ValetDriver;

class LocalValetDriver extends ValetDriver
{
    /**
     * 确定驱动是否为请求提供服务。
     */
    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/index.php';
    }
}

其他 Valet 命令

命令	描述
valet list	显示所有 Valet 命令列表。
valet diagnose	显示诊断信息以帮助调试 Valet。
valet directory-listing	确定是否显示目录列表。默认为「off」。
valet forget	从停放目录运行此命令以从停放目录列表中删除它。
valet log	查看 Valet 服务写入的日志。
valet paths	查看所有停放路径。
valet restart	重启 Valet 守护进程。
valet start	启动 Valet 守护进程。
valet stop	停止 Valet 守护进程。
valet trust	添加 sudoers 文件以使 Valet 命令运行无需输入密码。
valet uninstall	卸载 Valet：显示手动卸载说明。传递 --force 选项以激进地删除所有 Valet 资源。

Valet 目录和文件

在排查 Valet 环境问题时，您可能会发现以下目录和文件信息很有用：

路径	描述
~/.config/valet	包含 Valet 的所有配置和日志。定期备份此目录是个好习惯。
~/.config/valet/dnsmasq.d	包含 DNS 配置文件。
~/.config/valet/nginx	包含 Valet 生成的所有 Nginx 站点配置。这些文件在运行 link、secure 和 proxy 命令时重建。
~/.config/valet/ssl	包含所有证书和 CA 文件。
~/.config/valet/Drivers	包含自定义 Valet 驱动。
~/.config/valet/Extensions	包含自定义 Valet 扩展。
~/.config/valet/config.json	Valet 的主配置文件。
~/.config/valet/valet-sock.php	用于运行 PHP 的 Unix 套接字。
~/.config/valet/Drivers/Require.php	Valet 驱动自动加载器。

磁盘访问

自 macOS Catalina 起，默认情况下不允许应用程序访问用户的桌面、文档和下载目录。由于 Valet 通过 Nginx 提供站点服务，它需要访问这些目录才能提供存储在其中的站点。因此，当尝试从这些目录之一提供站点时，macOS 会自动提示您授予 Nginx 访问权限。

但是，如果您希望从这些位置之一提供站点，您需要授予 Nginx「完全磁盘访问权限」。否则，您可能会遇到服务器错误或 Nginx 的其他不可预测行为，尤其是在提供静态资源时。通常，macOS 会自动提示您授予 Nginx 对这些位置的完全访问权限。或者，您可以通过 系统偏好设置 > 安全性与隐私 > 隐私 并选择 完全磁盘访问权限 来手动执行此操作。然后，在主窗口窗格中启用任何 nginx 条目。