phpEnv多版本多站点配置教程

phpEnv 是一个专注于 PHP 版本切换的命令行工具，但它本身不提供 Web 服务、域名管理或虚拟主机功能，因此无法直接搭建多站点环境；真正的多版本多站点运行需要你手动协同配置 Web 服务器（如 Apache/Nginx）、PHP-FPM 实例、DNS 或 hosts 解析、文档根目录及项目级版本控制（.php-version），同时警惕常见陷阱：安装失败多因系统依赖缺失、项目版本不生效常因文件位置或格式错误、Web 请求仍用旧版 PHP 则是因为 php-fpm 守护进程完全绕过 phpenv 的 shim 机制——理解“谁在什么上下文中调用哪个 PHP”才是配置成功的关键。

phpenv 能直接搭多站点？不能。它只管 PHP 版本切换，不提供 Web 服务（如 Apache/Nginx）、不管理域名、不自动配虚拟主机。所谓“多站点”，得靠你额外配 Web 服务器 + 域名解析 + 文档根目录指向，phpenv 只确保每个站点调用对的 php 二进制和扩展。

phpenv install 命令失败：常见依赖缺失

执行 phpenv install 8.3.13 报错退出，90% 是系统缺编译依赖或开发头文件。不是网络问题，也不是 phpenv 本身坏了。

• Ubuntu/Debian 上必须先装：build-essential libxml2-dev libsqlite3-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev zlib1g-dev
• CentOS/RHEL/Fedora 上对应是：gcc make autoconf bison re2c libxml2-devel openssl-devel sqlite-devel curl-devel libjpeg-devel libpng-devel freetype-devel zlib-devel
• macOS（Homebrew）：brew install autoconf bison libxml2 openssl@3 sqlite3 curl jpeg pngquant freetype，并确认 pkg-config 在 PATH 中
• 安装完别忘了 phpenv rehash，否则新装的 PHP 不会被 shim 捕获

项目级 PHP 版本不生效：检查 .php-version 文件位置与内容

你在项目根目录运行 phpenv local 7.4.33，但 php -v 还是显示 8.3 —— 很可能 .php-version 文件没被读到，或内容有空格/换行符。

• .php-version 必须放在项目最外层目录（即 cd 进去后 pwd 输出的路径），不能在子目录里
• 文件内容只能是纯版本号，例如：7.4.33，不能带空格、v 前缀、注释或 Windows CRLF 换行
• 用 cat -A .php-version 查看是否含不可见字符；用 phpenv version-name 确认当前实际解析出的版本名
• 如果项目用了 Git，记得把 .php-version 加入 .gitignore —— 它属于开发环境配置，不该提交

Web 服务器调用的 PHP 还是系统默认版：shim 机制不作用于 CGI/FPM

你在终端里 php -v 显示 7.4.33，但浏览器访问 localhost 显示 PHP 8.1 —— 因为 Web 服务器（Apache/Nginx + PHP-FPM）启动时根本没走 phpenv 的 shims，它直连系统 /usr/bin/php 或 FPM socket。

• phpenv 的 shims 只对 shell 子进程有效（比如你在终端敲 php script.php），对守护进程（如 php-fpm）完全无效
• 要让站点用指定 PHP 版本，必须手动配置 Web 服务器：
  • Apache：改 LoadModule php_module 路径，或用 SetHandler "proxy:fcgi://127.0.0.1:9000" 指向对应版本的 php-fpm
  • Nginx：在 fastcgi_pass 里指定不同端口或 socket，每个 PHP 版本起独立 php-fpm 实例（路径如 $HOME/.phpenv/versions/7.4.33/sbin/php-fpm）
• 别指望 phpenv shell 7.4.33 能影响已启动的 php-fpm 进程 —— 它只改当前 shell 的 PATH，FPM 是独立 daemon

真正麻烦的点不在安装，而在「哪个进程用哪个 PHP」—— 终端命令、CLI 脚本、Web 请求、Cron 任务、Composer 自身，它们的执行上下文完全不同，phpenv 只覆盖其中一部分。漏掉任一环节，版本就对不上。

好了，本文到此结束，带大家了解了《phpEnv多版本多站点配置教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！