如何离线安装多版本phpEnv并查阅使用手册？

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

phpphpenv 本身不提供离线安装包，所有版本安装都依赖编译（通过 php-build 插件）或从源码拉取。没有预编译的二进制包，因此不能直接离线部署。若想在无网络环境下使用指定 PHP 版本，必须提前在联网的机器上完成构建和打包整个 ~/.phpenv/versions/ 目录。

---

为什么 phpenv install 必须联网

phpenv install 实际调用的是 php-build 插件，它会：

• 从 https://www.php.net/distributions/ 下载 php-x.y.z.tar.xz 源码包
• 自动下载并编译依赖（如 libxml2、openssl、zlib 等，取决于 configure 参数）
• 执行 ./configure && make && make install，输出到 ~/.phpenv/versions/x.y.z/

断网时，第一步就失败，报错类似：Error: failed to download https://www.php.net/distributions/php-8.3.13.tar.xz

---

离线部署的唯一可行路径：提前构建 + 打包迁移

适用于 CI 节点、内网服务器、Docker 构建阶段等场景：

• 在有网且环境一致（同 OS、同 glibc 版本、同基础 dev 工具链）的机器上，运行：phpenv install 8.3.13
• 确认成功后，执行：phpenv rehash（生成 shim 脚本）
• 打包整个版本目录：tar -czf php-8.3.13-offline.tgz ~/.phpenv/versions/8.3.13
• 把 php-8.3.13-offline.tgz 和 ~/.phpenv/shims/php（或其他用到的 shim）一并拷到目标机器
• 解压到相同路径：tar -xzf php-8.3.13-offline.tgz -C ~/.phpenv/versions/
• 手动补全 shim（如果目标机没装 phpenv）：ln -sf ~/.phpenv/versions/8.3.13/bin/php ~/.phpenv/shims/php

注意：phpenv global 8.3.13 之后需再跑一次 phpenv rehash，否则其他命令（如 phpize、pear）可能找不到。

---

phpenv 离线使用时最常漏掉的三件事

• 忘记同步 ~/.phpenv/version（全局）或项目下的 .php-version 文件——没这俩，phpenv 不知道该用哪个版本
• 没检查目标机是否装了编译产物依赖库，比如 libonig.so.5 或 libargon2.so.1；PHP 8.3+ 动态链接这些，缺一个就报 php: error while loading shared libraries
• 误以为 phpenv install --dry-run 可以预下载——它只打印步骤，不真正下载；要用 php-build 命令单独触发下载：php-build --definitions ~/.phpenv/plugins/php-build/share/php-build/ 8.3.13 /tmp/php-src

离线不是不能做，但得把“构建环境”和“运行环境”的差异想清楚——phpenv 的核心是路径调度，它不管二进制能不能跑，只管把 php 命令指向哪。真正卡住你的，永远是动态链接那一层。