Laravel Valet

• 簡介
• 安裝
  • 升級 Valet
• 伺服網站
  • 「Park」指令
  • 「Link」指令
  • 使用 TLS 保護網站安全
  • 伺服預設網站
  • 單站點 PHP 版本
• 分享網站
  • 在本機網路上分享網站
• 站點特定環境變數
• 代理服務
• 自訂 Valet 驅動程式
  • 本地驅動程式
• 其他 Valet 指令
• Valet 目錄和檔案
  • 磁碟存取

簡介

Laravel Valet 是一個為 macOS 極簡主義者設計的開發環境。Laravel Valet 設定您的 Mac，使其在機器啟動時始終在背景執行 Nginx。然後，使用 DnsMasq，Valet 將 *.test 網域上的所有請求代理到指向安裝在本機電腦上的站點。

換句話說，Valet 是一個速度極快的 Laravel 開發環境，僅使用約 7 MB 的 RAM。Valet 並非 Sail 或 Homestead 的完整替代品，但如果您想要彈性的基礎功能、偏好極致速度，或是在 RAM 容量有限的機器上工作，則是一個絕佳的替代方案。

Valet 開箱即用的支援包括但不限於：

但是，您可以透過自己的自訂驅動程式來擴展 Valet。

安裝

首先，要開始使用，您需要使用 update 指令確保 Homebrew 是最新的

1brew update

接下來，您應該使用 Homebrew 安裝 PHP

1brew install php

安裝 PHP 後，您就可以安裝 Composer 套件管理器。此外，您應確保 $HOME/.composer/vendor/bin 目錄在您的系統「PATH」中。安裝 Composer 後，您可以將 Laravel Valet 作為全域 Composer 套件安裝

1composer global require laravel/valet

最後，您可以執行 Valet 的 install 指令。這將設定並安裝 Valet 和 DnsMasq。此外，Valet 依賴的守護進程將被設定為在您的系統啟動時啟動

1valet install

安裝 Valet 後，請嘗試使用 ping foobar.test 之類的指令，在終端機上 ping 任何 *.test 網域。如果 Valet 安裝正確，您應該會看到此網域在 127.0.0.1 上回應。

每次您的機器啟動時，Valet 都會自動啟動其所需的服務。

PHP 版本

Valet 允許您使用 valet use php@version 指令切換 PHP 版本。如果指定的 PHP 版本尚未安裝，Valet 將透過 Homebrew 安裝它

1valet use [email protected]
2 
3valet use php

您也可以在專案的根目錄中建立 .valetrc 檔案。.valetrc 檔案應包含站點應使用的 PHP 版本

1php=php@8.2

建立此檔案後，您可以簡單地執行 valet use 指令，該指令將透過讀取檔案來判斷站點偏好的 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 安裝

伺服網站

安裝 Valet 後，您就可以開始伺服您的 Laravel 應用程式。Valet 提供了兩個指令來協助您伺服您的應用程式：park 和 link。

park 指令

park 指令會在您的機器上註冊一個包含您的應用程式的目錄。一旦使用 Valet「停放」了目錄，該目錄中的所有目錄都可以在您的網頁瀏覽器中以 http://<directory-name>.test 存取

1cd ~/Sites
2 
3valet park

就是這樣。現在，您在「停放」目錄中建立的任何應用程式都將自動使用 http://<directory-name>.test 慣例進行伺服。因此，如果您的停放目錄包含一個名為「laravel」的目錄，則該目錄中的應用程式將可在 http://laravel.test 存取。此外，Valet 還自動允許您使用萬用字元子網域 (http://foo.laravel.test) 存取該站點。

link 指令

link 指令也可以用於伺服您的 Laravel 應用程式。如果您只想在目錄中伺服單個站點，而不是整個目錄，則此指令非常有用

1cd ~/Sites/laravel
2 
3valet link

一旦使用 link 指令將應用程式連結到 Valet，您就可以使用其目錄名稱存取該應用程式。因此，上面範例中連結的站點可以在 http://laravel.test 存取。此外，Valet 還自動允許您使用萬用字元子網域 (http://foo.laravel.test) 存取該站點。

如果您想在不同的主機名稱上伺服應用程式，您可以將主機名稱傳遞給 link 指令。例如，您可以執行以下指令，使應用程式可在 http://application.test 上使用

1cd ~/Sites/laravel
2 
3valet link application

當然，您也可以使用 link 指令在子網域上伺服應用程式

1valet link api.application

您可以執行 links 指令來顯示所有連結目錄的列表

1valet links

unlink 指令可用於銷毀站點的符號連結

1cd ~/Sites/laravel
2 
3valet unlink

使用 TLS 保護網站安全

預設情況下，Valet 通過 HTTP 伺服站點。但是，如果您想使用 HTTP/2 通過加密 TLS 伺服站點，您可以使用 secure 指令。例如，如果您的站點正在由 Valet 在 laravel.test 網域上伺服，您應該執行以下指令來保護它

1valet secure laravel

要「取消保護」站點並恢復為通過純 HTTP 伺服其流量，請使用 unsecure 指令。與 secure 指令一樣，此指令接受您要取消保護的主機名稱

1valet unsecure laravel

伺服預設網站

有時，您可能希望在訪問未知 test 網域時，將 Valet 設定為伺服「預設」站點，而不是 404。為了實現這一點，您可以將 default 選項添加到您的 ~/.config/valet/config.json 設定檔中，其中包含應作為預設站點的站點路徑

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

單站點 PHP 版本

預設情況下，Valet 使用您的全域 PHP 安裝來伺服您的站點。但是，如果您需要在各種站點之間支援多個 PHP 版本，您可以使用 isolate 指令來指定特定站點應使用的 PHP 版本。isolate 指令會設定 Valet 為位於您目前工作目錄中的站點使用指定的 PHP 版本

1cd ~/Sites/example-site
2 
3valet isolate [email protected]

如果您的站點名稱與包含它的目錄名稱不符，您可以使用 --site 選項指定站點名稱

1valet isolate [email protected] --site="site-name"

為了方便起見，您可以根據站點設定的 PHP 版本，使用 valet php、composer 和 which-php 指令將呼叫代理到適當的 PHP CLI 或工具

1valet php
2valet composer
3valet which-php

您可以執行 isolated 指令來顯示所有隔離站點及其 PHP 版本的列表

1valet isolated

要將站點恢復為 Valet 的全域安裝 PHP 版本，您可以從站點的根目錄調用 unisolate 指令

1valet unisolate

分享網站

Valet 包括一個與世界分享本機站點的指令，提供了一種在行動裝置上測試您的站點或與團隊成員和客戶分享它的簡便方法。

Valet 開箱即用地支援透過 ngrok 或 Expose 分享您的站點。在分享站點之前，您應該使用 share-tool 指令更新您的 Valet 設定，指定 ngrok 或 expose

1valet share-tool ngrok

如果您選擇了一個工具，並且沒有透過 Homebrew（對於 ngrok）或 Composer（對於 Expose）安裝它，Valet 將自動提示您安裝它。當然，這兩個工具都要求您先驗證您的 ngrok 或 Expose 帳戶，然後才能開始分享站點。

要分享站點，請在您的終端機中導航到站點的目錄，然後執行 Valet 的 share 指令。一個公開可存取的 URL 將被放置在您的剪貼簿中，並準備好直接貼到您的瀏覽器中或與您的團隊分享

1cd ~/Sites/laravel
2 
3valet share

要停止分享您的站點，您可以按下 Control + C。

透過 Ngrok 分享網站

使用 ngrok 分享您的站點需要您建立一個 ngrok 帳戶並設定一個身份驗證權杖。取得身份驗證權杖後，您可以使用該權杖更新您的 Valet 設定

1valet set-ngrok-token YOUR_TOKEN_HERE

透過 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 陣列中

 1<?php
 2 
 3return [
 4    // Set $_SERVER['key'] to "value" for the laravel.test site...
 5    'laravel' => [
 6        'key' => 'value',
 7    ],
 8 
 9    // Set $_SERVER['key'] to "value" for all sites...
10    '*' => [
11        'key' => 'value',
12    ],
13];

代理服務

有時您可能希望將 Valet 網域代理到本機電腦上的另一個服務。例如，您可能偶爾需要在執行 Valet 的同時在 Docker 中執行單獨的站點；但是，Valet 和 Docker 不能同時綁定到 80 端口。

為了解決這個問題，您可以使用 proxy 指令來產生代理。例如，您可以將來自 http://elasticsearch.test 的所有流量代理到 http://127.0.0.1:9200

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

您可以使用 unproxy 指令移除代理

1valet unproxy elasticsearch

您可以使用 proxies 指令列出所有已代理的站點設定

1valet 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 方法可能如下所示

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

isStaticFile 方法

isStaticFile 應判斷傳入的請求是否針對「靜態」檔案，例如影像或樣式表。如果檔案是靜態的，則該方法應傳回磁碟上靜態檔案的完整路徑。如果傳入的請求不是針對靜態檔案，則該方法應傳回 false

 1/**
 2 * Determine if the incoming request is for a static file.
 3 *
 4 * @return string|false
 5 */
 6public function isStaticFile(string $sitePath, string $siteName, string $uri)
 7{
 8    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
 9        return $staticFilePath;
10    }
11 
12    return false;
13}

frontControllerPath 方法

frontControllerPath 方法應傳回您的應用程式「前端控制器」的完整路徑，這通常是「index.php」檔案或等效檔案

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

本地驅動程式

如果您想為單個應用程式定義自訂 Valet 驅動程式，請在應用程式的根目錄中建立 LocalValetDriver.php 檔案。您的自訂驅動程式可以擴展基礎 ValetDriver 類別，或擴展現有的應用程式特定驅動程式，例如 LaravelValetDriver

 1use Valet\Drivers\LaravelValetDriver;
 2 
 3class LocalValetDriver extends LaravelValetDriver
 4{
 5    /**
 6     * Determine if the driver serves the request.
 7     */
 8    public function serves(string $sitePath, string $siteName, string $uri): bool
 9    {
10        return true;
11    }
12 
13    /**
14     * Get the fully resolved path to the application's front controller.
15     */
16    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
17    {
18        return $sitePath.'/public_html/index.php';
19    }
20}

其他 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 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 pool 設定檔。

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

此檔案是用於為您的站點建置 SSL 憑證的預設 Nginx 設定。

磁碟存取

自 macOS 10.14 起，預設情況下，對某些檔案和目錄的存取受到限制。這些限制包括「桌面」、「文件」和「下載」目錄。此外，網路磁碟區和可移除磁碟區存取也受到限制。因此，Valet 建議您的站點資料夾位於這些受保護位置之外。

但是，如果您希望從這些位置之一伺服站點，您將需要授予 Nginx「完整磁碟存取權」。否則，您可能會遇到伺服器錯誤或來自 Nginx 的其他不可預測的行為，尤其是在伺服靜態資源時。通常，macOS 會自動提示您授予 Nginx 對這些位置的完整存取權。或者，您可以透過 系統偏好設定 > 安全性與隱私 > 隱私 並選擇 完整磁碟存取權 手動執行此操作。接下來，在主視窗格中啟用任何 nginx 項目。