报“Definition xxx not found”是编译阶段符号未定义错误，因系统缺build-essential、libssl-dev、libxml2-dev等依赖及php-build插件；需正确配置PATH与phpenv init、执行phpenv rehash，并为PHP 8.4.2等新版本显式指定--enable-mbstring等configure参数。
phpenv install 报 “Definition xxx not found” 怎么办
这是编译阶段典型的符号未定义错误，不是 PHP 本身代码问题，而是构建环境缺关键头文件或链接库。常见于安装 PHP 8.4.2 或其他新版本时。
必须先装齐系统级依赖，否则 configure 阶段就失败：
-
build-essential（含gcc、make） -
libssl-dev、libxml2-dev、libsqlite3-dev -
libonig-dev（PHP 8+ 正则依赖）、libreadline-dev（交互式 CLI 支持） -
autoconf、bison、re2c（PHP 构建必需的语法生成工具）
Ubuntu/Debian 下可一行装全：
sudo apt-get install -y build-essential autoconf bison re2c libssl-dev libxml2-dev libsqlite3-dev libonig-dev libreadline-dev zlib1g-dev libcurl4-openssl-dev
装完别急着重试——还要确认 php-build 插件已就位。如果用的是 ~/.phpenv/plugins/php-build，但目录为空，phpenv install 实际调用的是 fallback 脚本，会跳过很多校验，导致报错更模糊。
立即学习“PHP免费学习笔记（深入）”；
phpenv 命令找不到或 init 失败
执行 phpenv --version 提示 command not found，或 phpenv init - 报 no such command 'init'，说明环境没真正激活。
两个硬性前提缺一不可：
-
export PATH="$HOME/.phpenv/bin:$PATH"必须出现在当前 shell 的配置文件（~/.bashrc或~/.zshrc）里，且不能被后续PATH=...覆盖 -
eval "$(phpenv init -)"必须在 PATH 设置之后执行；顺序反了，phpenv init就根本跑不起来
验证方式很直接：
echo $PATH | grep .phpenv
如果没输出，说明 PATH 没生效；再执行：
ls ~/.phpenv/bin/phpenv
如果提示 No such file，就是克隆路径错了——注意官方推荐是 ~/.phpenv，不是 ~/phpenv 或 /usr/local/phpenv。
安装完 php -v 还是旧版本
最常被忽略的一点：phpenv global 8.4.2 成功后，php -v 却没变。这不是 phpenv 失效，而是 shell 缓存了 php 的路径。
运行这三步定位真实问题：
-
which php—— 看当前调用的是哪个二进制 -
ls -la $(which php)—— 如果指向/usr/bin/php或/opt/homebrew/bin/php，说明系统自带 PHP 或 Homebrew PHP 优先级更高 -
phpenv rehash—— 必须每次新装版本后手动触发，否则~/.phpenv/shims/php不会更新
macOS 用户尤其注意：Homebrew 安装的 PHP 默认写入 /opt/homebrew/bin，而该路径通常在 $PATH 中排在 ~/.phpenv/shims 前面。解决办法只有两个：export PATH="$HOME/.phpenv/shims:$PATH"（加在 PATH 最前），或卸载 Homebrew PHP。
PHP 8.4.2 安装卡在 compiling 阶段
不是网络问题，也不是磁盘满，而是 configure 参数缺失导致编译器找不到某些函数声明。PHP 8.4 对扩展依赖更严格，比如 --enable-mbstring 不显式启用，mb_* 函数就压根不编译，后续链接时就会报 Definition mb_convert_encoding not found 这类错误。
建议为高版本 PHP 创建专属配置文件：
echo '--enable-mbstring --with-curl --with-openssl --with-zlib --with-readline' > ~/.phpenv/plugins/php-build/share/php-build/definitions/8.4.2
然后运行：
PHPBUILD_CONFIGURE_OPTS="$(cat ~/.phpenv/plugins/php-build/share/php-build/definitions/8.4.2)" phpenv install 8.4.2
这个操作绕过了 php-build 内置的默认 definition 文件，避免它加载过时或不兼容的选项。实际项目中，不同 PHP 版本最好各自维护一份 .php-version-options，而不是共用一套全局参数。
