phpEnv多版本一键切换教程 phpEnv环境安装说明-php教程-PHP中文网

phpenv能实现一键切换，但需安装路径、shell配置和php-build插件三者齐全；缺一则phpenv global/local会静默失效，常见问题源于环境变量未正确加载或插件缺失。

phpenv多版本一键切换教程 phpenv环境安装说明

phpenv 能实现真正的“一键切换”，但前提是安装路径、shell 配置、插件三者全部到位；缺一不可，否则 phpenv global 或 phpenv local 会静默失效。

很多人执行完 git clone 就以为装好了，结果 phpenv --version 报 command not found。根本原因是 shell 没加载到 phpenv 的 bin 目录和 shim 初始化逻辑。

必须把这两行同时写入你的 shell 配置文件（~/.bashrc 或 ~/.zshrc）：
export PATH="$HOME/.phpenv/bin:$PATH"
eval "$(phpenv init -)"
写完不能只改文件就完事——要执行 source ~/.bashrc（或 source ~/.zshrc），或者新开终端；用 exec $SHELL -l 也行，但不如 source 直观可控
验证是否生效：运行 which phpenv 应该返回类似 /home/xxx/.phpenv/bin/phpenv；运行 phpenv --version 有输出才算成功

phpenv 本身不带编译能力，它只是个版本路由层。所有 phpenv install xxx 的实际工作都由 php-build 插件完成。跳过这步，你连第一个 PHP 版本都装不上。

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

手动安装插件命令（必须在 phpenv 初始化之后执行）：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build
安装前建议先装系统依赖，否则编译大概率失败：
sudo apt install build-essential libssl-dev libxml2-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev autoconf（Ubuntu/Debian）
装完插件再试：phpenv install 8.3.13；若提示 “command not found: phpenv-install”，说明插件没放对位置或没 reload shell

这个命令本质是往当前目录写一个 .php-version 文件，然后靠 shims 在执行 php 时自动读取。常见失效原因不是命令错了，而是路径或权限问题。

phpenv local 7.4.33 必须在项目根目录下运行，且该目录需有写权限；它生成的 .php-version 是纯文本，内容就是 7.4.33（无空格、无换行）
进入目录后，用 phpenv version 查看当前解析来源；如果显示 system，说明没读到 .php-version，可能因为：
— 当前目录上层某处也有 .php-version（优先级更高）
— 文件编码是 Windows-style CRLF（某些 shell 解析失败）
— 目录名含空格或特殊字符（极少见但存在）
临时调试可用：phpenv which php 看当前 php 二进制路径是否指向 ~/.phpenv/versions/7.4.33/bin/php

phpenv 按照固定顺序决定最终用哪个版本：shell 会话 > 本地（.php-version） > 全局（~/.phpenv/version）。这个优先级不能改，但容易被忽略。

phpenv shell 5.6.40 只影响当前终端，关掉就消失；适合快速验证旧版兼容性
phpenv global 8.3.13 写入 ~/.phpenv/version，对所有没设 local 或 shell 的场景生效
一旦设置了 phpenv shell，即使你 cd 进某个 .php-version 为 7.4.33 的项目，php -v 仍显示 5.6.40——这是设计行为，不是 bug
清除 shell 级别设置：运行 phpenv shell --unset；清除 local 设置：删掉项目下的 .php-version