Laravel Homestead

简介

WARNING

Laravel Homestead 是一个已不再积极维护的遗留包。可使用 Laravel Sail 作为现代替代方案。

Laravel 致力于让整个 PHP 开发体验愉悦，包括本地开发环境。Laravel Homestead 是官方预打包的 Vagrant box，能提供出色的开发环境，无需在本机安装 PHP、Web 服务器或其他服务器软件。

Vagrant 提供了简单优雅的方式来管理与配置虚拟机。Vagrant box 完全可销毁重建。若出现问题，你可以在几分钟内销毁并重新创建 box！

Homestead 可运行于任意 Windows、macOS 或 Linux 系统，并包含 Nginx、PHP、MySQL、PostgreSQL、Redis、Memcached、Node，以及开发出色 Laravel 应用所需的其他软件。

WARNING

若使用 Windows，可能需要启用硬件虚拟化（VT-x）。通常可在 BIOS 中启用。若在 UEFI 系统上使用 Hyper-V，可能还需要禁用 Hyper-V 才能访问 VT-x。

包含的软件

• Ubuntu 22.04
• Git
• PHP 8.3
• PHP 8.2
• PHP 8.1
• PHP 8.0
• PHP 7.4
• PHP 7.3
• PHP 7.2
• PHP 7.1
• PHP 7.0
• PHP 5.6
• Nginx
• MySQL 8.0
• lmm
• Sqlite3
• PostgreSQL 15
• Composer
• Docker
• Node (With Yarn, Bower, Grunt, and Gulp)
• Redis
• Memcached
• Beanstalkd
• Mailpit
• avahi
• ngrok
• Xdebug
• XHProf / Tideways / XHGui
• wp-cli

可选软件

• Apache
• Blackfire
• Cassandra
• Chronograf
• CouchDB
• Crystal & Lucky Framework
• Elasticsearch
• EventStoreDB
• Flyway
• Gearman
• Go
• Grafana
• InfluxDB
• Logstash
• MariaDB
• Meilisearch
• MinIO
• MongoDB
• Neo4j
• Oh My Zsh
• Open Resty
• PM2
• Python
• R
• RabbitMQ
• Rust
• RVM (Ruby Version Manager)
• Solr
• TimescaleDB
• Trader (PHP extension)
• Webdriver & Laravel Dusk Utilities

安装与配置

第一步

启动 Homestead 环境之前，必须安装 Vagrant 以及下列受支持的 provider 之一：

• VirtualBox 6.1.x
• Parallels

这些软件包都为各主流操作系统提供了易用的可视化安装程序。

要使用 Parallels provider，需要安装 Parallels Vagrant 插件。该插件免费。

安装 Homestead

你可以通过将 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

设置 Provider

Homestead.yaml 文件中的 provider 键指明应使用哪个 Vagrant provider：virtualbox 或 parallels：

provider: virtualbox

WARNING

若使用 Apple Silicon，则必须使用 Parallels provider。

配置共享文件夹

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

WARNING

使用 Homestead 时切勿挂载 .（当前目录）。这会导致 Vagrant 不将当前文件夹映射到 /vagrant，从而破坏可选功能，并在配置过程中产生意外结果。

若要启用 NFS，可为文件夹映射添加 type 选项：

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "nfs"

WARNING

在 Windows 上使用 NFS 时，应考虑安装 vagrant-winnfsd 插件。该插件会为 Homestead 虚拟机中的文件和目录维持正确的用户/组权限。

你也可以通过在 options 键下列出选项，传入 Vagrant Synced Folders 支持的任意选项：

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "rsync"
      options:
          rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
          rsync__exclude: ["node_modules"]

配置 Nginx 站点

不熟悉 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 配置。

WARNING

Homestead 脚本尽可能做成幂等。但若在配置过程中遇到问题，应执行 vagrant destroy && vagrant up 命令销毁并重建机器。

主机名解析

Homestead 使用 mDNS 发布主机名以实现自动主机解析。若在 Homestead.yaml 中设置 hostname: homestead，主机将在 homestead.local 可用。macOS、iOS 和 Linux 桌面发行版默认包含 mDNS 支持。若使用 Windows，必须安装 Bonjour Print Services for Windows。

自动主机名最适合 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 box 后，即可通过浏览器访问站点：

http://homestead.test

配置服务

Homestead 默认会启动若干服务；不过你可以在配置过程中自定义启用或禁用哪些服务。例如，可通过修改 Homestead.yaml 中的 services 选项启用 PostgreSQL 并禁用 MySQL：

services:
    - enabled:
        - "postgresql"
    - disabled:
        - "mysql"

指定的服务会根据其在 enabled 和 disabled 指令中的顺序启动或停止。

启动 Vagrant Box

按需编辑完 Homestead.yaml 后，在 Homestead 目录运行 vagrant up 命令。Vagrant 将启动虚拟机并自动配置共享文件夹与 Nginx 站点。

若要销毁机器，可使用 vagrant destroy 命令。

按项目安装

除了全局安装 Homestead 并在所有项目间共享同一 Homestead 虚拟机外，你也可以为管理的每个项目分别配置 Homestead 实例。若希望随项目附带 Vagrantfile，让其他协作者在克隆仓库后立即 vagrant up，按项目安装 Homestead 会很有用。

你可以使用 Composer 包管理器将 Homestead 安装到项目中：

composer require laravel/homestead --dev

安装 Homestead 后，调用 Homestead 的 make 命令为项目生成 Vagrantfile 和 Homestead.yaml。这些文件会放在项目根目录。make 命令会自动配置 Homestead.yaml 中的 sites 和 folders 指令：

# macOS / Linux...
php vendor/bin/homestead make

# Windows...
vendor\\bin\\homestead make

接下来在终端运行 vagrant up，并在浏览器访问 http://homestead.test。请记住，若未使用自动主机名解析，仍需为 homestead.test 或你选择的域名添加 /etc/hosts 条目。

安装可选功能

可选软件通过 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

你可以指定受支持的 Elasticsearch 版本，必须是精确版本号（major.minor.patch）。默认安装会创建名为「homestead」的集群。切勿将超过操作系统一半的内存分配给 Elasticsearch，因此请确保 Homestead 虚拟机至少拥有 Elasticsearch 分配量的两倍内存。

INFO

请查阅 Elasticsearch 文档 了解如何自定义配置。

MariaDB

启用 MariaDB 会移除 MySQL 并安装 MariaDB。MariaDB 通常可作为 MySQL 的即插替换，因此在应用的数据库配置中仍应使用 mysql 数据库驱动。

MongoDB

默认 MongoDB 安装会将数据库用户名设为 homestead，对应密码设为 secret。

Neo4j

默认 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 之前，应先在 Homestead 目录运行以下命令，确保已移除当前虚拟机：

vagrant destroy

接下来需要更新 Homestead 源代码。若你是克隆的仓库，可在最初克隆仓库的位置执行以下命令：

git fetch

git pull origin release

这些命令会从 GitHub 仓库拉取最新 Homestead 代码、获取最新标签，然后检出最新的标记发行版。你可以在 Homestead 的 GitHub releases 页面 找到最新稳定发行版。

若通过项目的 composer.json 安装了 Homestead，应确保 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

日常使用

通过 SSH 连接

你可以在 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

WARNING

添加站点之前，应确保已为项目目录配置了文件夹映射。

若 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。

站点参数

你可以通过 params 站点指令为站点添加额外的 Nginx fastcgi_param 值：

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 命令重新配置机器。这会更新所有已安装 PHP 版本的 PHP-FPM 配置，并更新 vagrant 用户的环境。

端口

默认情况下，以下端口会转发到 Homestead 环境：

• HTTP: 8000 → Forwards To 80
• HTTPS: 44300 → Forwards To 443

转发额外端口

如有需要，可在 Homestead.yaml 中定义 ports 配置项，将额外端口转发到 Vagrant box。更新 Homestead.yaml 后，务必执行 vagrant reload --provision 命令重新配置机器：

ports:
    - send: 50000
      to: 5000
    - send: 7777
      to: 777
      protocol: udp

以下是你可能希望从宿主机映射到 Vagrant box 的其他 Homestead 服务端口：

• SSH: 2222 → To 22
• ngrok UI: 4040 → To 4040
• MySQL: 33060 → To 3306
• PostgreSQL: 54320 → To 5432
• MongoDB: 27017 → To 27017
• Mailpit: 8025 → To 8025
• Minio: 9600 → To 9600

PHP 版本

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

你可以在 Homestead 虚拟机内执行以下命令，更改 CLI 使用的默认 PHP 版本：

php56
php70
php71
php72
php73
php74
php80
php81
php82
php83

连接数据库

开箱即用已为 MySQL 和 PostgreSQL 配置了 homestead 数据库。要从宿主机的数据库客户端连接 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

配置完成后，执行 vagrant destroy 时 Homestead 会将数据库导出到 .backup/mysql_backup 和 .backup/postgres_backup 目录。这些目录位于你安装 Homestead 的文件夹中；若使用按项目安装方式，则位于项目根目录。

配置 Cron 计划任务

Laravel 提供了便捷的方式来调度 cron 任务：每分钟运行一次 schedule:run Artisan 命令。schedule:run 命令会检查 routes/console.php 中定义的任务计划，以确定应运行哪些定时任务。

若希望为某个 Homestead 站点运行 schedule:run 命令，可在定义站点时将 schedule 选项设为 true：

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      schedule: true

该站点的 cron 任务会定义在 Homestead 虚拟机的 /etc/cron.d 目录中。

配置 Mailpit

Mailpit 可拦截外发邮件并查看内容，而不会真正发送给收件人。首先，更新应用的 .env 文件以使用以下邮件设置：

MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

配置 Mailpit 后，可访问 http://localhost:8025 查看 Mailpit 控制台。

配置 Minio

Minio 是开源对象存储服务器，提供与 Amazon S3 兼容的 API。要安装 Minio，请在 Homestead.yaml 的 features 部分添加以下配置选项：

minio: true

默认情况下，Minio 在端口 9600 可用。可访问 http://localhost:9600 打开 Minio 控制面板。默认 access key 为 homestead，默认 secret key 为 secretkey。访问 Minio 时应始终使用 region 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。

Laravel Dusk

要在 Homestead 中运行 Laravel Dusk 测试，应在 Homestead 配置中启用 webdriver 功能：

features:
    - webdriver: true

启用 webdriver 功能后，应在终端执行 vagrant reload --provision 命令。

共享你的环境

有时你可能希望与同事或客户共享当前正在进行的工作。Vagrant 通过 vagrant share 命令内置了此支持；但若在 Homestead.yaml 中配置了多个站点，该方法将无法使用。

为解决此问题，Homestead 提供了自己的 share 命令。首先，通过 vagrant ssh SSH 进入 Homestead 虚拟机，然后执行 share homestead.test 命令。该命令会共享 Homestead.yaml 中的 homestead.test 站点。你可以将 homestead.test 替换为其他已配置的站点：

share homestead.test

运行命令后，会出现包含活动日志以及共享站点公开可访问 URL 的 Ngrok 界面。若要指定自定义 region、子域名或其他 Ngrok 运行时选项，可将其添加到 share 命令：

share homestead.test -region=eu -subdomain=laravel

若需要通过 HTTPS 而非 HTTP 共享内容，请使用 sshare 命令替代 share。

WARNING

请记住，Vagrant 本质上不安全，运行 share 命令时会将虚拟机暴露到互联网。

调试与性能分析

使用 Xdebug 调试 Web 请求

Homestead 支持使用 Xdebug 进行单步调试。例如，你可以在浏览器中访问页面，PHP 会连接到 IDE，以便检查和修改正在运行的代码。

默认情况下，Xdebug 已在运行并准备接受连接。若需在 CLI 上启用 Xdebug，请在 Homestead 虚拟机内执行 sudo phpenmod xdebug 命令。然后按 IDE 说明启用调试。最后，通过扩展或书签小工具配置浏览器以触发 Xdebug。

WARNING

Xdebug 会显著降低 PHP 运行速度。要禁用 Xdebug，请在 Homestead 虚拟机内运行 sudo phpdismod xdebug 并重启 FPM 服务。

自动启动 Xdebug

在调试向 Web 服务器发起请求的功能测试时，自动启动调试比修改测试以通过自定义 header 或 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

调试 CLI 应用

要调试 PHP CLI 应用，请在 Homestead 虚拟机内使用 xphp shell 别名：

xphp /path/to/script

使用 Blackfire 分析应用

Blackfire 是用于分析 Web 请求和 CLI 应用的服务。它提供交互式界面，以调用图和时间线展示分析数据。适用于开发、预发布和生产环境，对最终用户无额外开销。此外，Blackfire 还提供对代码和 php.ini 配置的性能、质量与安全检查。

Blackfire Player 是开源的 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

你可以使用 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 不应纳入版本控制。

Provider 特定设置

VirtualBox

natdnshostresolver

默认情况下，Homestead 将 natdnshostresolver 设置为 on。这允许 Homestead 使用宿主机操作系统的 DNS 设置。若要覆盖此行为，请在 Homestead.yaml 中添加以下配置选项：

provider: virtualbox
natdnshostresolver: 'off'