macOS 多版本 PHP 开发环境搭建

引言

在现代 PHP 开发中，不同项目可能依赖不同版本的 PHP 运行环境。本指南将详细介绍如何在 macOS

系统上使用 Homebrew 包管理器搭建包含 Nginx、MySQL 和多版本 PHP 的开发环境，实现不同 PHP

版本的并行运行与灵活切换。

准备工作

安装 Homebrew

Homebrew 是 macOS 上的包管理工具，我们将使用它来安装所有需要的组件。如果尚未安装，请打

开终端执行以下命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/

HEAD/install.sh)"

安装完成后，运行以下命令验证安装：

brew --version

更新系统组件

确保 Homebrew 及其配方列表是最新的：

brew update

brew upgrade

安装核心组件

安装 Nginx 服务器

Nginx 是一个高性能的 HTTP 和反向代理服务器，我们用它来处理 HTTP 请求并转发给相应的 PHP 处

理器：

# 安装 Nginx

brew install nginx

# 启动 Nginx 服务

brew services start nginx

# 设置开机自启动

sudo brew services start nginx

验证 Nginx 是否安装成功：

◦ 访问 http://localhost:8080

◦ 如看到 "Welcome to nginx!" 页面，则表示安装成功

Nginx 主要文件位置：

◦ 配置文件：/usr/local/etc/nginx/nginx.conf

◦ 网站根目录（默认）：/usr/local/var/www

安装 MySQL 数据库

# 安装 MySQL

brew install mysql

# 启动 MySQL 服务

brew services start mysql

# 执行安全配置向导

mysql_secure_installation

在安全配置向导中，建议进行以下设置：

1. 设置 root 用户密码

2. 移除匿名用户

3. 禁止 root 用户远程登录

4. 删除 test 数据库并权限

验证 MySQL 安装：

mysql -u root -p

输入设置的密码，如能成功登录 MySQL 命令行，则表示安装成功。

安装多版本 PHP

Homebrew 允许同时安装多个 PHP 版本，我们以目前常用的 7.4、8.0 和 8.1 版本为例：

# 安装 PHP 7.4

brew install php@7.4

# 安装 PHP 8.0

brew install php@8.0

# 安装 PHP 8.1

brew install php@8.1

注意：Homebrew 可能会不定期移除旧版本 PHP 的支持，如果某个版本无法安装，可以考虑使用第

三方仓库如 shivammathur/php

配置多版本 PHP 共存

每个 PHP 版本都通过 FPM（FastCGI 进程管理器）处理请求，为了避免端口冲突，需要为不同版本配

置不同的端口：

# PHP 7.4 FPM 默认使用 9000 端口，保持默认即可

# 配置 PHP 8.0 FPM 使用 9001 端口

sed -i.bak 's/listen = 127.0.0.1:9000/listen = 127.0.0.1:9001/' /usr/local/etc/php/8.0/php-fpm.d/

www.conf

# 配置 PHP 8.1 FPM 使用 9002 端口

sed -i.bak 's/listen = 127.0.0.1:9000/listen = 127.0.0.1:9002/' /usr/local/etc/php/8.1/php-fpm.d/

www.conf

启动所有 PHP-FPM 服务：

# 启动 PHP 7.4 FPM

brew services start php@7.4

# 启动 PHP 8.0 FPM

brew services start php@8.0

# 启动 PHP 8.1 FPM

brew services start php@8.1

检查 PHP-FPM 服务状态：

brew services list | grep php

配置 Nginx 支持多版本 PHP

组织站点配置文件

为了更好地管理多个站点，我们创建专用的配置目录：

# 创建站点配置目录

mkdir -p /usr/local/etc/nginx/sites-available

mkdir -p /usr/local/etc/nginx/sites-enabled

编辑 Nginx 主配置文件，引入站点配置：

nano /usr/local/etc/nginx/nginx.conf

在 http 块中添加以下行：

include /usr/local/etc/nginx/sites-enabled/*;

创建版本专用站点配置

为每个 PHP 版本创建独立的 Nginx 站点配置：

1. PHP 7.4 站点配置

# /usr/local/etc/nginx/sites-available/php74.test

server {

listen 80;

server_name php74.test;

root /Users/your_username/Sites/php74.test;

index index.php index.html;

# 日志配置

access_log /usr/local/var/log/nginx/php74.access.log;

error_log /usr/local/var/log/nginx/php74.error.log;

location / {

try_files $uri $uri/ /index.php?$query_string;

}

# PHP 处理配置

location ~ \.php$ {

fastcgi_pass 127.0.0.1:9000; # 对应PHP 7.4 FPM端口

fastcgi_index index.php;

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

include fastcgi_params;

}

}

2. PHP 8.0 站点配置

# /usr/local/etc/nginx/sites-available/php80.test

server {

listen 80;

server_name php80.test;

root /Users/your_username/Sites/php80.test;

index index.php index.html;

# 日志配置

access_log /usr/local/var/log/nginx/php80.access.log;

error_log /usr/local/var/log/nginx/php80.error.log;

location / {

try_files $uri $uri/ /index.php?$query_string;

}

# PHP 处理配置

location ~ \.php$ {

fastcgi_pass 127.0.0.1:9001; # 对应PHP 8.0 FPM端口

fastcgi_index index.php;

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

include fastcgi_params;

}

}

3. PHP 8.1 站点配置

# /usr/local/etc/nginx/sites-available/php81.test

server {

listen 80;

server_name php81.test;

root /Users/your_username/Sites/php81.test;

index index.php index.html;

# 日志配置

access_log /usr/local/var/log/nginx/php81.access.log;

error_log /usr/local/var/log/nginx/php81.error.log;

location / {

try_files $uri $uri/ /index.php?$query_string;

}

# PHP 处理配置

location ~ \.php$ {

fastcgi_pass 127.0.0.1:9002; # 对应PHP 8.1 FPM端口

fastcgi_index index.php;

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

include fastcgi_params;

}

}

注意：将配置中的 your_username 替换为你的 macOS 用户名

启用站点配置

通过创建符号链接启用站点配置：

# 启用站点配置

ln -s /usr/local/etc/nginx/sites-available/php74.test /usr/local/etc/nginx/sites-enabled/

ln -s /usr/local/etc/nginx/sites-available/php80.test /usr/local/etc/nginx/sites-enabled/

ln -s /usr/local/etc/nginx/sites-available/php81.test /usr/local/etc/nginx/sites-enabled/

配置本地域名解析

编辑 hosts 文件，添加本地域名解析：

sudo nano /etc/hosts

添加以下内容：

127.0.0.1 php74.test

127.0.0.1 php80.test

127.0.0.1 php81.test

保存并退出编辑器（按 Ctrl+O 保存，Ctrl+X 退出）。

创建测试环境

创建站点目录

# 创建站点根目录

mkdir -p /Users/your_username/Sites/{php74.test,php80.test,php81.test}

创建测试文件

为每个版本创建 phpinfo 测试文件：

# PHP 7.4 测试文件

echo "" > /Users/your_username/Sites/php74.test/index.php

# PHP 8.0 测试文件

echo "" > /Users/your_username/Sites/php80.test/index.php

# PHP 8.1 测试文件

echo "" > /Users/your_username/Sites/php81.test/index.php

重启服务

使所有配置生效：

# 重启 Nginx

brew services restart nginx

# 重启所有 PHP-FPM 服务

brew services restart php@7.4

brew services restart php@8.0

brew services restart php@8.1

验证环境

打开浏览器，分别访问以下地址，确认各版本 PHP 正常工作：

◦ http://php74.test - 应显示 PHP 7.4 信息

◦ http://php80.test - 应显示 PHP 8.0 信息

◦ http://php81.test - 应显示 PHP 8.1 信息

命令行 PHP 版本切换

为方便在命令行中使用不同版本的 PHP，配置版本别名：

# 对于 Zsh 用户

nano ~/.zshrc

# 对于 Bash 用户

nano ~/.bash_profile

添加以下内容：

# PHP 版本切换别名

alias php74='/usr/local/opt/php@7.4/bin/php'

alias php80='/usr/local/opt/php@8.0/bin/php'

alias php81='/usr/local/opt/php@8.1/bin/php'

# PHP 命令行工具别名

alias phpcgi74='/usr/local/opt/php@7.4/bin/php-cgi'

alias phpcgi80='/usr/local/opt/php@8.0/bin/php-cgi'

alias phpcgi81='/usr/local/opt/php@8.1/bin/php-cgi'

# Composer 版本适配

alias composer74='php74 /usr/local/bin/composer'

alias composer80='php80 /usr/local/bin/composer'

alias composer81='php81 /usr/local/bin/composer'

使配置生效：

# 对于 Zsh 用户

source ~/.zshrc

# 对于 Bash 用户

source ~/.bash_profile

验证命令行版本：

php74 -v # 显示 PHP 7.4 版本信息

php80 -v # 显示 PHP 8.0 版本信息

php81 -v # 显示 PHP 8.1 版本信息

常见问题与解决方案

Nginx 启动失败

1. 检查端口占用情况：

lsof -i :80

2. 检查配置文件语法错误：

nginx -t

PHP-FPM 无法启动

1. 检查端口是否被占用：

lsof -i :9000 # 替换为对应版本的端口号

2. 查看错误日志：

cat /usr/local/var/log/php@7.4/error.log # 替换为对应版本

无法访问站点

1. 检查目录权限：

chmod -R 755 /Users/your_username/Sites

2. 确认 hosts 文件配置正确：

cat /etc/hosts | grep test

3. 检查 Nginx 日志获取详细错误信息：

tail -f /usr/local/var/log/nginx/error.log

总结

通过本指南，你已成功在 macOS 上搭建了支持多版本 PHP 的开发环境。这个环境允许你同时运行多

个 PHP 版本，通过不同的域名访问不同版本的应用，同时也能在命令行中灵活切换 PHP 版本。

这种配置特别适合需要维护多个不同 PHP 版本项目的开发者，能够显著提高开发效率并减少环境切换

带来的麻烦。