Laravel 中文文档

主题

全部文档

Laravel Valet ​

简介 ​

INFO

想在 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](https://laravel.com)
  • [Bedrock](https://roots.io/bedrock/)
  • [CakePHP 3](https://cakephp.org)
  • [ConcreteCMS](https://www.concretecms.com/)
  • [Contao](https://contao.org/en/)
  • [Craft](https://craftcms.com)
  • [Drupal](https://www.drupal.org/)
  • [ExpressionEngine](https://www.expressionengine.com/)
  • [Jigsaw](https://jigsaw.tighten.co)
  • [Joomla](https://www.joomla.org/)
  • [Katana](https://github.com/themsaid/katana)
  • [Kirby](https://getkirby.com/)
  • [Magento](https://magento.com/)
  • [OctoberCMS](https://octobercms.com/)
  • [Sculpin](https://sculpin.io/)
  • [Slim](https://www.slimframework.com)
  • [Statamic](https://statamic.com)
  • 静态 HTML
  • [Symfony](https://symfony.com)
  • [WordPress](https://wordpress.org)
  • [Zend](https://framework.zend.com)

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

安装 ​

WARNING

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

首先，使用 update 命令确保 Homebrew 是最新的：

shell
brew update

接下来，使用 Homebrew 安装 PHP：

shell
brew install php

安装 PHP 后，即可安装 Composer 包管理器。此外，应确保 $HOME/.composer/vendor/bin 目录已加入系统的「PATH」。安装 Composer 后，可将 Laravel Valet 安装为全局 Composer 包：

shell
composer global require laravel/valet

最后，可执行 Valet 的 install 命令。这会配置并安装 Valet 与 DnsMasq。此外，Valet 依赖的守护进程也会配置为系统启动时启动：

shell
valet install

Valet 安装完成后，可在终端用类似 ping foobar.test 的命令 ping 任意 *.test 域名。若安装正确，应看到该域名响应 127.0.0.1。

每次开机时，Valet 会自动启动所需服务。

PHP 版本 ​

INFO

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

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

shell
valet use php@8.2

valet use php

你也可以在项目根目录创建 .valetrc 文件。该文件应包含站点应使用的 PHP 版本：

shell
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，请按以下步骤正确升级：

  • 若曾添加 `.valetphprc` 文件自定义站点 PHP 版本，请将每个 `.valetphprc` 重命名为 `.valetrc`，然后在 `.valetrc` 现有内容前加上 `php=`。
  • 更新所有自定义驱动，使其符合新驱动系统的命名空间、扩展、类型提示与返回类型提示。可参考 Valet 的 [SampleValetDriver](https://github.com/laravel/valet/blob/d7787c025e60abc24a5195dc7d4c5c6f2d984339/cli/stubs/SampleValetDriver.php) 作为示例。
  • 若使用 PHP 7.1–7.4 服务站点，请仍通过 Homebrew 安装 8.0 或更高版本的 PHP，因为 Valet 会用该版本运行部分脚本，即使它不是你的主链接版本。

托管站点 ​

Valet 安装完成后，即可开始托管 Laravel 应用。Valet 提供两个命令帮助你托管应用：park 和 link。

park 命令 ​

park 命令会在本机注册一个包含应用的目录。目录被 Valet「park」后，该目录下的所有子目录都可通过浏览器访问 http://<directory-name>.test：

shell
cd ~/Sites

valet park

就这么简单。现在，在「已 park」目录中创建的任何应用都会自动按 http://<directory-name>.test 约定提供服务。因此，若已 park 目录包含名为「laravel」的目录，其中的应用可通过 http://laravel.test 访问。此外，Valet 还自动支持通配符子域名访问（http://foo.laravel.test）。

link 命令也可用于托管 Laravel 应用。若只想托管目录中的单个站点而非整个目录，该命令很有用：

shell
cd ~/Sites/laravel

valet link

使用 link 命令将应用链接到 Valet 后，可通过其目录名访问应用。因此，上例中链接的站点可通过 http://laravel.test 访问。此外，Valet 还自动支持通配符子域名访问（http://foo.laravel.test）。

若希望用不同主机名托管应用，可将主机名传给 link 命令。例如，运行以下命令可使应用在 http://application.test 可用：

shell
cd ~/Sites/laravel

valet link application

当然，也可以使用 link 命令在子域名上托管应用：

shell
valet link api.application

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

shell
valet links

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

shell
cd ~/Sites/laravel

valet unlink

使用 TLS 保护站点 ​

默认情况下，Valet 通过 HTTP 提供站点服务。若希望通过加密 TLS 并使用 HTTP/2 提供服务，可使用 secure 命令。例如，若站点由 Valet 在 laravel.test 域名上提供服务，应运行以下命令进行保护：

shell
valet secure laravel

若要「取消保护」站点并恢复为普通 HTTP，请使用 unsecure 命令。与 secure 一样，该命令接受你希望取消保护的主机名：

shell
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 版本：

shell
cd ~/Sites/example-site

valet isolate php@8.0

若站点名称与包含它的目录名不匹配，可使用 --site 选项指定站点名称：

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

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

shell
valet php
valet composer
valet which-php

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

shell
valet isolated

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

shell
valet unisolate

共享站点 ​

Valet 包含用于将本地站点共享到公网的命令，便于在移动设备上测试，或与团队成员和客户共享。

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

shell
valet share-tool ngrok

若选择的工具尚未通过 Homebrew（ngrok 和 cloudflared）或 Composer（Expose）安装，Valet 会自动提示你安装。当然，这些工具都需要你先验证 ngrok 或 Expose 账户才能开始共享站点。

要共享站点，请在终端进入站点目录并运行 Valet 的 share 命令。公开可访问的 URL 会放入剪贴板，可直接粘贴到浏览器或与团队共享：

shell
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 配置：

shell
valet set-ngrok-token YOUR_TOKEN_HERE

INFO

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

通过 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
<?php

return [
    // Set $_SERVER['key'] to "value" for the laravel.test site...
    'laravel' => [
        'key' => 'value',
    ],

    // Set $_SERVER['key'] to "value" for all sites...
    '*' => [
        'key' => 'value',
    ],
];

代理服务 ​

有时你可能希望将 Valet 域名代理到本机上的另一个服务。例如，偶尔需要在运行 Valet 的同时在 Docker 中运行另一个站点；但 Valet 和 Docker 不能同时绑定 80 端口。

为此，可使用 proxy 命令生成代理。例如，可将 http://elasticsearch.test 的所有流量代理到 http://127.0.0.1:9200：

shell
# Proxy over HTTP...
valet proxy elasticsearch http://127.0.0.1:9200

# Proxy over TLS + HTTP/2...
valet proxy elasticsearch http://127.0.0.1:9200 --secure

可使用 unproxy 命令移除代理：

shell
valet unproxy elasticsearch

可使用 proxies 命令列出所有已代理的站点配置：

shell
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 是域名的「host」/「站点名」部分（my-project）。$uri 是传入请求的 URI（/foo/bar）。

完成自定义 Valet 驱动后，请按 FrameworkValetDriver.php 命名约定将其放在 ~/.config/valet/Drivers 目录。例如，若为 WordPress 编写自定义驱动，文件名应为 WordPressValetDriver.php。

下面来看自定义 Valet 驱动应实现的每个方法的示例。

serves 方法 ​

若驱动应处理传入请求，serves 方法应返回 true；否则返回 false。因此，在该方法中应判断给定的 $sitePath 是否包含你要服务的项目类型。

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

php
/**
 * 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：

php
/**
 * 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 或等效文件：

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 命令 ​

Command描述
valet listDisplay a list of all Valet commands.
valet diagnoseOutput diagnostics to aid in debugging Valet.
valet directory-listingDetermine directory-listing behavior. Default is "off", which renders a 404 page for directories.
valet forgetRun this command from a "parked" directory to remove it from the parked directory list.
valet logView a list of logs which are written by Valet's services.
valet pathsView all of your "parked" paths.
valet restartRestart the Valet daemons.
valet startStart the Valet daemons.
valet stopStop the Valet daemons.
valet trustAdd sudoers files for Brew and Valet to allow Valet commands to be run without prompting for your password.
valet uninstallUninstall Valet: shows instructions for manual uninstall. Pass the --force option to aggressively delete all of Valet's resources.

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 socket。仅在 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 条目。