如何完整安装并运行phpEnv全套环境？

本文共计1016个文字，预计阅读时间需要5分钟。

别被伪原创误导。以下是对原文的简化

别被误导。

Windows 用户：直接下载 phpEnv（带 GUI 的集成包）

这是最省事的路径，适合刚学 PHP、不想碰编译和 Shell 配置的人。官网最新版（2026 年仍维护）是 phpEnv-2.5.0.exe，不是 GitHub 上那个纯 CLI 工具。

• 下载后**不要放 C:\Program Files**，路径里不能有中文或空格，推荐 D:\phpEnv
• 安装时勾选“创建桌面快捷方式”，方便后续启停服务
• 首次运行会自动检测并安装 Apache/MySQL/PHP 组件，若卡在“正在下载组件”，关掉杀软重试，或手动下载对应 zip 包放进 D:\phpEnv\temp\ 目录再点“重试”
• 启动后如果 Apache 显示红色（未启动），大概率是 80 端口被 IIS、Skype 或其他程序占了——进控制面板 → “配置” → “端口检测”，把 Apache 改成 8080，然后访问 http://localhost:8080

macOS / Linux 用户：装的是 phpenv（命令行多版本管理器）

它不带 Web 服务器，也不含 MySQL，只管 PHP 解释器本身。你装完它，php -v 会变，但 http://localhost 不会自动出来——那是你自己的 Web 服务器（如 nginx、Valet、Laravel Sail）的事。

• 必须先装 php-build 插件，否则 phpenv install 命令根本不存在：

  git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build

• Shell 配置文件要对：Bash 用 ~/.bash_profile 或 ~/.bashrc，Zsh 用 ~/.zshrc，别混着写
• phpenv install 8.3.13 编译可能失败，常见原因是缺系统依赖：libxml2-dev、openssl-dev、autoconf（macOS 用 brew install autoconf openssl@3 libxml2）
• 装完版本后必须执行 phpenv rehash，否则 php 命令还是老版本——这是最容易漏的一步

.php-version 文件怎么生效？优先级你得清楚

phpenv 切换版本不是靠记忆，而是按固定顺序查三个地方，找到第一个就停：

立即学习“PHP免费学习笔记（深入）”；

• 当前 Shell 会话设的（phpenv shell 7.4.33）→ 最高优先级，退出终端即失效
• 当前目录下存在 .php-version 文件（内容就一行：8.3.13）→ 项目级锁定，进这个目录自动切
• 全局设置（phpenv global 8.1.27）→ 最低优先级，兜底用

注意：.php-version 必须是 UTF-8 无 BOM 格式，Windows 记事本保存会悄悄加 BOM，导致 phpenv 读取失败，报错 version not found——用 VS Code 或 Notepad++ 保存时选“UTF-8”而非“UTF-8 with BOM”。

为什么 php -v 没变？检查 shim 是否被 PATH 覆盖

phpenv 的核心机制是通过 shims 目录里的假 php 可执行文件做路由。一旦你的 PATH 里有别的 PHP（比如 Homebrew 装的 /opt/homebrew/bin/php）排在 ~/.phpenv/shims 前面，那就永远绕过 phpenv。

• 运行 which php，输出应该是 /Users/xxx/.phpenv/shims/php，否则说明 PATH 顺序错了
• 检查 echo $PATH，确保 $(phpenv root)/shims 出现在最前面，而不是末尾
• 某些 IDE（如 PHPStorm）会缓存 PHP 解释器路径，改完 shell 配置后需重启 IDE，否则调试器仍用旧版本

真正的坑不在安装步骤，而在 PATH 和 shim 的隐式覆盖——很多人反复重装 phpenv，其实只是没调好这一行环境变量顺序。