[!警告]
Laravel Homestead 是一个遗留软件包，已不再积极维护。 Laravel Sail 可作为现代替代方案使用。
Laravel 致力于让整个 PHP 开发体验愉悦，包括你的本地开发环境。Laravel Homestead 是一个官方的、预封装的 Vagrant 盒子，它为你提供了一个出色的开发环境，无需你在本地机器上安装 PHP、Web 服务器或任何其他服务器软件。
Vagrant 提供了一种简单、优雅的方式管理和配置虚拟机。Vagrant 盒子是完全可抛弃的。如果出了问题，你可以在几分钟内销毁并重新创建这个盒子！
Homestead 运行于任何 Windows、macOS 或 Linux 系统，并包含 Nginx、PHP、MySQL、PostgreSQL、Redis、Memcached、Node，以及所有您开发出色的 Laravel 应用所需的其他软件。
[!WARNING]
如果您正在使用 Windows，您可能需要启用硬件虚拟化 (VT-x)。通常可以通过您的 BIOS 启用它。如果您在 UEFI 系统上使用 Hyper-V，您可能还需要禁用 Hyper-V 以便访问 VT-x。
buntu 22.04
Apache
在启动您的 Homestead 环境之前，您必须安装 Vagrant 以及以下受支持的提供程序之一：
所有这些软件包都为所有流行的操作系统提供了易于使用的可视化安装程序。
要使用 Parallels 提供程序，您将需要安装 Parallels Vagrant 插件。它是免费的。
您可以通过将 Homestead 仓库克隆到您的宿主机上来安装 Homestead。建议将该仓库克隆到您的“home”目录下的一个 Homestead 文件夹中，因为 Homestead 虚拟机将作为所有 Laravel 应用的宿主机。在本文档中，我们将把此目录称为您的“Homestead 目录”：
git clone https://github.com/laravel/homestead.git ~/Homestead克隆 Laravel Homestead 仓库后，你应该切换到 release 分支。此分支始终包含 Homestead 的最新稳定版本：
cd ~/Homestead
git checkout release接下来，在 Homestead 目录下执行 bash init.sh 命令，以创建 Homestead.yaml 配置文件。Homestead.yaml 文件是您配置 Homestead 安装所有设置的地方。此文件将放置在 Homestead 目录中：
# macOS / Linux...
bash init.sh
# Windows...
init.bat您的 Homestead.yaml 文件中的 provider 键指示应使用哪个 Vagrant 提供者： virtualbox 或 parallels：
提供方: virtualbox
[!WARNING]
如果您正在使用 Apple Silicon Parallels 提供程序是必需的。
Homestead.yaml 文件的 folders 属性列出了所有你希望与 Homestead 环境共享的文件夹。当这些文件夹中的文件发生变化时，它们会在你的本地机器和 Homestead 虚拟环境之间保持同步。你可以根据需要配置任意数量的共享文件夹：
folders:
- map: ~/code/project1
to: /home/vagrant/project1[!WARNING]
Windows 用户不应使用~/路径语法，而应使用其项目的完整路径，例如C:\Users\user\Code\project1。
您应该始终将单个应用程序映射到它们自己的文件夹映射，而不是映射一个包含所有应用程序的单个大型目录. 当您映射一个文件夹时，虚拟机必须跟踪针对该文件夹中 每个 文件的所有磁盘 IO. 如果一个文件夹中包含大量文件，您可能会遇到性能下降的情况:
folders:
- map: ~/code/project1
to: /home/vagrant/project1
- map: ~/code/project2
to: /home/vagrant/project2[!警告]
你绝不应该挂载.（当前目录）在 Homestead 使用时。
这会导致 Vagrant 不会映射当前文件夹到/vagrant并会破坏可选功能并导致在配置过程中出现意外结果。
要启用 NFS，您可以添加一个 type 选项到您的文件夹映射中：
folders:
- map: ~/code/project1
to: /home/vagrant/project1
type: "nfs"[!警告]
在 Windows 上使用 NFS 时，您应该考虑安装 vagrant-winnfsd 插件。此插件将为 Homestead 虚拟机内的文件和目录维护正确的用户/组权限。
您还可以传递 Vagrant 的 同步文件夹 支持的任何选项 通过在 options 键下列出它们：
folders:
- map: ~/code/project1
to: /home/vagrant/project1
type: "rsync"
options:
rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
rsync__exclude: ["node_modules"]不熟悉 Nginx？没问题。你的 Homestead.yaml 文件的 sites 属性允许你轻松地将一个“域名”映射到你的 Homestead 环境上的一个文件夹。一个示例站点配置包含在 Homestead.yaml 文件中。同样，你可以根据需要向你的 Homestead 环境添加任意数量的站点。Homestead 可以作为一个方便的、虚拟化的环境，用于你正在处理的每个 Laravel 应用程序：
sites:
- map: homestead.test
to: /home/vagrant/project1/public如果您在预置 Homestead 虚拟机后更改了 sites 属性，您应该在您的终端中执行 vagrant reload --provision 命令，以更新虚拟机上的 Nginx 配置。
[!警告]
Homestead 脚本旨在尽可能保持幂等性。但是，如果您在配置过程中遇到问题，应该通过执行vagrant destroy && vagrant up命令来销毁并重建虚拟机。
Homestead 使用 mDNS 发布主机名，用于自动主机解析。如果您在您的 Homestead.yaml 文件中设置 hostname: homestead，则主机将在 homestead.local 可用。macOS、iOS 和 Linux 桌面发行版默认包含 mDNS 支持。如果您使用 Windows，您必须安装 适用于 Windows 的 Bonjour 打印服务。
使用自动主机名最适用于 按项目安装 的 Homestead。如果您在单个 Homestead 实例上托管多个站点，您可以在您机器上的 hosts 文件中添加您网站的“域名”。hosts 文件将把您的 Homestead 站点的请求重定向到您的 Homestead 虚拟机中。在 macOS 和 Linux 上，此文件位于 /etc/hosts。在 Windows 上，它位于 C:\Windows\System32\drivers\etc\hosts。您添加到此文件的行将如下所示：
192.168.56.56 homestead.test请确保列出的 IP 地址与您的 Homestead.yaml 文件中设置的地址一致。将域名添加到您的 hosts 文件并启动 Vagrant 盒子后，您将能够通过网络浏览器访问该站点：
http://homestead.testHomestead 默认启动多个服务；但是，您可以在供应期间自定义启用或禁用哪些服务。例如，您可以通过修改您的 Homestead.yaml 文件中的 services 选项来启用 PostgreSQL 并禁用 MySQL：
services:
- enabled:
- "postgresql"
- disabled:
- "mysql"指定的服务将会根据它们在 enabled 和 disabled 指令中的顺序启动或停止。
一旦你按照喜好编辑了 Homestead.yaml, 在你的 Homestead 目录下运行 vagrant up 命令. Vagrant 将会启动虚拟机并自动配置你的共享文件夹和 Nginx 站点.
要销毁该机器，您可以使用 vagrant destroy 命令。
不像全局安装 Homestead 并让所有项目共享同一个 Homestead 虚拟机，你可以为每个你管理的项目配置一个 Homestead 实例。为每个项目安装 Homestead 可能很有用，如果你希望在项目中附带一个 Vagrantfile，允许在该项目上工作的其他人在克隆项目仓库后立即 vagrant up。
你可以使用 Composer 包管理器将 Homestead 安装到你的项目中：
composer require laravel/homestead --dev一旦 Homestead 安装完成，调用 Homestead 的 make 命令为你的项目生成 Vagrantfile 和 Homestead.yaml 文件。这些文件将被放置在你的项目根目录中。make 命令将自动配置 sites 和 folders 指令在 Homestead.yaml 文件中：
# macOS / Linux...
php vendor/bin/homestead make
# Windows...
vendor\\bin\\homestead make接下来，在终端中运行 vagrant up 命令，并在浏览器中访问 http://homestead.test 上的项目。请记住，您仍然需要添加一个 /etc/hosts 文件条目，用于 homestead.test 或您选择的域名，如果您没有使用自动 主机名解析。
可选软件是使用您的 Homestead.yaml 文件中的 features 选项安装的。大多数特性可以通过布尔值来启用或禁用，而有些特性则允许配置多个选项：
features:
- blackfire:
server_id: "server_id"
server_token: "server_value"
client_id: "client_id"
client_token: "client_value"
- cassandra: true
- chronograf: true
- couchdb: true
- crystal: true
- dragonflydb: true
- elasticsearch:
version: 7.9.0
- eventstore: true
version: 21.2.0
- flyway: true
- gearman: true
- golang: true
- grafana: true
- influxdb: true
- logstash: true
- mariadb: true
- meilisearch: true
- minio: true
- mongodb: true
- neo4j: true
- ohmyzsh: true
- openresty: true
- pm2: true
- python: true
- r-base: true
- rabbitmq: true
- rustc: true
- rvm: true
- solr: true
- timescaledb: true
- trader: true
- webdriver: true您可以指定一个受支持的 Elasticsearch 版本，它必须是一个精确的版本号 (major.minor.patch)。默认安装将创建一个名为 'homestead' 的集群。您绝不应该分配给 Elasticsearch 超过操作系统一半的内存，所以请确保您的 Homestead 虚拟机至少拥有 Elasticsearch 分配量两倍的内存。
[!注意]
参阅 Elasticsearch 文档 了解如何自定义配置。
启用 MariaDB 将移除 MySQL 并安装 MariaDB。 MariaDB 通常作为 MySQL 的直接替代品，因此您仍应在您的应用程序的数据库配置中使用 mysql 数据库驱动程序。
默认的 MongoDB 安装会设置数据库用户名为 homestead 以及对应的密码为 secret。
默认的 Neo4j 安装会将数据库用户名设置为 homestead 及其对应的密码设置为 secret. 要访问 Neo4j 浏览器，通过您的网络浏览器访问 http://homestead.test:7474. 端口 7687 (Bolt), 7474 (HTTP), 和 7473 (HTTPS) 已准备好服务来自 Neo4j 客户端的请求.
您可以通过修改 Homestead 目录中的 aliases 文件，来为您的 Homestead 虚拟机添加 Bash 别名：
alias c='clear'
alias ..='cd ..'在您更新了 aliases 文件后，您应该使用 vagrant reload --provision 命令重新配置 Homestead 虚拟机。这将确保您的新别名在该机器上可用。
在开始更新 Homestead 之前，您应确保已通过在您的 Homestead 目录中运行以下命令来移除当前的虚拟机：
vagrant destroy接下来，你需要更新 Homestead 源代码。如果你克隆了该仓库，你可以在你最初克隆该仓库的位置执行以下命令：
git fetch
git pull origin release这些命令从 GitHub 仓库拉取最新的 Homestead 代码，获取最新的标签，然后检出最新的标签发布版本。你可以在 Homestead 的 GitHub 发布页面上找到最新的稳定发布版本。
如果您已通过项目的composer.json文件，您应该确保您的composer.json文件中包含"laravel/homestead": "^12"并更新您的依赖项：
composer update接下来，您应该使用 vagrant box update 命令更新 Vagrant box：
vagrant box update更新 Vagrant box 后，您应该从 Homestead 目录运行 bash init.sh 命令，以更新 Homestead 的额外配置文件。系统将询问您是否希望覆盖您现有的 Homestead.yaml、after.sh 和 aliases 文件：
# macOS / Linux...
bash init.sh
# Windows...
init.bat最后，您将需要重新生成您的 Homestead 虚拟机，以利用最新的 Vagrant 安装：
vagrant up你可以通过从你的 Homestead 目录执行 vagrant ssh 终端命令来 SSH 连接到你的虚拟机。
一旦你的 Homestead 环境已完成配置并运行，你可能想要为你的其他 Laravel 项目添加额外的 Nginx 站点。你可以在一个 Homestead 环境上运行任意数量的 Laravel 项目。要添加额外的站点，将该站点添加到你的 Homestead.yaml 文件中。
sites:
- map: homestead.test
to: /home/vagrant/project1/public
- map: another.test
to: /home/vagrant/project2/public[!警告]
您应确保在添加站点前已为项目的目录配置文件夹映射。
如果 Vagrant 没有自动管理您的“hosts”文件，您可能还需要将新站点添加到该文件中。在 macOS 和 Linux 上，此文件位于 /etc/hosts。在 Windows 上，它位于 C:\Windows\System32\drivers\etc\hosts：
192.168.56.56 homestead.test
192.168.56.56 another.test站点添加完成后，从你的 Homestead 目录执行 vagrant reload --provision 终端命令。
Homestead 支持多种“类型”的站点，让您能够轻松运行项目，即使它们不是基于 Laravel 的。例如，我们可以使用 statamic 站点类型轻松地将 Statamic 应用程序添加到 Homestead 中：
sites:
- map: statamic.test
to: /home/vagrant/my-symfony-project/web
type: "statamic"可用的站点类型有：apache， apache-proxy， apigility， expressive， laravel（默认）， proxy（用于 nginx）， silverstripe， statamic， symfony2， symfony4， 以及 zf。
您可以添加额外的 Nginx fastcgi_param 值到您的站点 通过 params 站点指令：
sites:
- map: homestead.test
to: /home/vagrant/project1/public
params:
- key: FOO
value: BAR您可以通过将全局环境变量添加到您的Homestead.yaml文件中：
variables:
- key: APP_ENV
value: local
- key: FOO
value: bar更新了Homestead.yaml文件后，请务必通过执行vagrant reload --provision命令来重新配置（re-provision）该机器。这将更新所有已安装 PHP 版本的 PHP-FPM 配置，并同时更新vagrant用户的环境。
默认情况下，以下端口被转发到您的 Homestead 环境：
如果您愿意，您可以将额外的端口转发到 Vagrant 盒子通过定义一个 ports 配置项在您的 Homestead.yaml 文件中。更新 Homestead.yaml 文件后，请务必通过执行 vagrant reload --provision 命令重新配置机器：
ports:
- send: 50000
to: 5000
- send: 7777
to: 777
protocol: udp以下是你可能希望从宿主机映射到 Vagrant 盒子的额外 Homestead 服务端口列表：
Homestead 支持在同一虚拟机上运行多个 PHP 版本。您可以在 Homestead.yaml 文件中为给定站点指定要使用的 PHP 版本。可用的 PHP 版本有："5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", 和 "8.3", (默认)：
sites:
- map: homestead.test
to: /home/vagrant/project1/public
php: "7.1"在您的 Homestead 虚拟机中, 您可以使用 CLI 访问任何受支持的 PHP 版本：
php5.6 artisan list
php7.0 artisan list
php7.1 artisan list
php7.2 artisan list
php7.3 artisan list
php7.4 artisan list
php8.0 artisan list
php8.1 artisan list
php8.2 artisan list
php8.3 artisan list您可以更改 CLI 使用的 PHP 默认版本，方法是在您的 Homestead 虚拟机中执行以下命令：
php56
php70
php71
php72
php73
php74
php80
php81
php82
php83一个 homestead 数据库已开箱即用地为 MySQL 和 PostgreSQL 配置。要从主机上的数据库客户端连接到您的 MySQL 或 PostgreSQL 数据库，您应该连接到 127.0.0.1 的端口 33060 (MySQL) 或 54320 (PostgreSQL)。这两个数据库的用户名和密码是 homestead / secret。
[!WARNING]
您只能在从您的主机连接到数据库时使用这些非标准端口。您将在您的 Laravel 应用程序的database配置文件中使用默认的 3306 和 5432 端口因为 Laravel 正在 在 虚拟机内部运行。
Homestead 可以在你的 Homestead 虚拟机被销毁时自动备份你的数据库。要利用此功能，你必须使用 Vagrant 2.1.0 或更高版本。或者，如果你使用的是旧版 Vagrant，你必须安装 vagrant-triggers 插件。要启用自动数据库备份，请将以下行添加到你的 Homestead.yaml 文件中：
backup: true配置完成后，Homestead 会在 vagrant destroy 命令执行时，将您的数据库导出到 .backup/mysql_backup 和 .backup/postgres_backup 目录中。这些目录可以在您安装 Homestead 的文件夹中找到，或者在您的项目根目录中找到，如果您正在使用 per project installation 方法。
Laravel 提供了一种便捷的方式来 调度 Cron 任务 通过调度单个 schedule:run Artisan 命令来每分钟运行。 该 schedule:run 命令将检查您在 routes/console.php 文件中定义的任务调度，以确定要运行哪些计划任务。
如果您希望 schedule:run 命令在 Homestead 站点上运行，则可以在定义站点时将 schedule 选项设置为 true ：
sites:
- map: homestead.test
to: /home/vagrant/project1/public
schedule: true站点的 cron 作业将在 Homestead 虚拟机的 /etc/cron.d 目录中定义。
Mailpit 允许您拦截您的外发电子邮件并检查它，而无需实际将邮件发送给其收件人. 要开始使用，更新您的应用程序的.env文件以使用以下邮件设置:
MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=nullMailpit 配置完成后，您可以在 http://localhost:8025 访问 Mailpit 仪表盘。
Minio 是一个开源对象存储服务器，具有与 Amazon S3 兼容的 API。要安装 Minio，请将 特性 部分中的以下配置选项写入您的 Homestead.yaml 文件：
minio: 启用
默认情况下，Minio 在端口 9600 上可用。您可以通过访问 http://localhost:9600 来访问 Minio 控制面板。默认访问密钥是 homestead，而默认秘密密钥是 secretkey。访问 Minio 时，您应始终使用区域 us-east-1。
要使用 Minio，请确保您的 .env 文件包含以下选项：
AWS_USE_PATH_STYLE_ENDPOINT=true
AWS_ENDPOINT=http://localhost:9600
AWS_ACCESS_KEY_ID=homestead
AWS_SECRET_ACCESS_KEY=secretkey
AWS_DEFAULT_REGION=us-east-1要配置 Minio 支持的“S3”存储桶，请在您的 Homestead.yaml 文件中添加 buckets 指令。定义存储桶后，您应该在终端中执行 vagrant reload --provision 命令：
buckets:
- name: your-bucket
policy: public
- name: your-private-bucket
policy: none支持的 policy 值包括：none, download, upload, 和 public
为了在 Homestead 中运行 Laravel Dusk 测试，您应该在您的 Homestead 配置中启用 webdriver 功能:
features:
- webdriver: true启用 webdriver 功能后，您应该在您的终端中执行 vagrant reload --provision 命令。
有时你可能希望将你当前正在处理的内容分享给同事或客户。Vagrant 内置了对此的支持，通过 vagrant share 命令；然而，如果你在 Homestead.yaml 文件中配置了多个站点，这将不起作用。
解决此问题, Homestead 包含它自己的 share 命令. 要开始, 通过 SSH 连接到您的 Homestead 虚拟机 通过 vagrant ssh 并执行 share homestead.test 命令. 此命令将共享您的 Homestead.yaml 配置文件中的 homestead.test 站点. 您可以用您配置的任何其他站点替换 homestead.test:`
share homestead.test运行该命令后，您将看到一个 Ngrok 屏幕出现，其中包含活动日志以及共享站点的公共可访问 URL。如果您想指定自定义区域、子域名或其他 Ngrok 运行时选项，您可以将它们添加到您的 share 命令中：
share homestead.test -region=eu -subdomain=laravel如果您需要通过 HTTPS 而非 HTTP 共享内容，使用 sshare 命令而非 share 命令将使您能够做到这一点。
[!WARNING]
记住，Vagrant 本质上是不安全的并且你正在将你的虚拟机暴露给互联网当运行share命令时。
Homestead 支持使用 Xdebug 进行步进调试。例如，你可以在浏览器中访问一个页面，PHP 将连接到你的 IDE，以允许检查和修改正在运行的代码。
默认情况下，Xdebug 已经运行并准备好接受连接。如果你需要在 CLI 上启用 Xdebug，请在你的 Homestead 虚拟机内执行 sudo phpenmod xdebug 命令。接下来，按照你的 IDE 的说明启用调试。最后，配置你的浏览器，通过扩展程序或 书签小程序 来触发 Xdebug。
[!WARNING]
Xdebug 会导致 PHP 运行速度显著变慢. 要禁用 Xdebug, 请在您的 Homestead 虚拟机中运行sudo phpdismod xdebug并重启 FPM 服务.
**当调试对网络服务器发出请求的功能测试时，自动启动调试比修改测试以通过自定义标头或 Cookie 触发调试更容易。要强制 Xdebug 自动启动，请修改您的 Homestead 虚拟机中的/etc/php/7.x/fpm/conf.d/20-xdebug.ini` 文件并添加以下配置：**
; If Homestead.yaml contains a different subnet for the IP address, this address may be different...
xdebug.client_host = 192.168.10.1
xdebug.mode = debug
xdebug.start_with_request = yes要调试 PHP CLI 应用程序，请在您的 Homestead 虚拟机中使用 xphp shell 别名：
xphp /path/to/scriptBlackfire 是一项用于分析 Web 请求和 CLI 应用程序的服务。它提供了一个交互式用户界面以调用图和时间线形式显示分析数据。它被设计用于开发、暂存和生产环境，且对最终用户没有开销。此外，Blackfire 对代码和 php.ini 配置设置提供性能、质量和安全检查。
[Blackfire Player](https://blackfire.io/docs/player/index) 是一个开源的 Web 页面抓取、Web 测试和 Web 数据提取应用程序，它可以与 Blackfire 协同工作，以便编写性能分析场景脚本。
要启用 Blackfire，在您的 Homestead 配置文件中使用 "features" 设置：
features:
- blackfire:
server_id: "server_id"
server_token: "server_value"
client_id: "client_id"
client_token: "client_value"Blackfire 服务器凭据和客户端凭据 需要 Blackfire 帐户。Blackfire 提供了多种分析应用程序的选项，包括 CLI 工具和浏览器扩展。请 查阅 Blackfire 文档以获取更多详情。
Homestead.yaml文件中的networks属性为你的Homestead虚拟机配置网络接口。 你可以按需配置任意数量的接口：
networks:
- type: "private_network"
ip: "192.168.10.20"要启用桥接接口，请为网络配置bridge设置，并将网络类型更改为public_network：
networks:
- type: "public_network"
ip: "192.168.10.20"
bridge: "en1: Wi-Fi (AirPort)"要启用 DHCP, 只需从您的配置中移除 ip 选项:
networks:
- type: "public_network"
bridge: "en1: Wi-Fi (AirPort)"要更新网络正在使用的设备，你可以添加一个 dev 选项到网络的配置中。默认的 dev 值是 eth0：
networks:
- type: "public_network"
ip: "192.168.10.20"
bridge: "en1: Wi-Fi (AirPort)"
dev: "enp2s0"您可以使用 Homestead 目录根目录中的 after.sh 脚本来扩展 Homestead. 在此文件中，您可以添加任何必要的 shell 命令，以正确配置和自定义您的虚拟机.
在自定义 Homestead 时，Ubuntu 可能会询问您是想保留软件包的原始配置，还是用新的配置文件覆盖它。为避免此情况，在安装软件包时，您应该使用以下命令，以避免覆盖 Homestead 先前写入的任何配置：
sudo apt-get -y \
-o Dpkg::Options::="--force-confdef" \
-o Dpkg::Options::="--force-confold" \
install package-name当您与团队一起使用 Homestead 时，您可能希望调整 Homestead，以更好地适应您的个人开发风格。为此，您可以在您的 Homestead 目录的根目录下(与包含您的 Homestead.yaml 文件的目录相同)创建一个 user-customizations.sh 文件。在此文件中，您可以进行任何您想要的自定义；但是，user-customizations.sh 不应进行版本控制。
NATDNS主机解析器默认情况下，Homestead 将 natdnshostresolver 设置为 on。这使得 Homestead 可以使用你主机的操作系统 DNS 设置。如果你想覆盖此行为，请将以下配置选项添加到你的 Homestead.yaml 文件中：
provider: virtualbox
natdnshostresolver: 'off'