“Definition xxx not found”本质是gcc链接时缺头文件或开发库，常见于缺失libonig-dev、libreadline-dev、libxml2-dev、libssl-dev等-dev包。
phpenv install 报 “Definition xxx not found” 是缺哪些依赖
这本质是编译阶段符号解析失败，不是 PHP 本身报错，而是 gcc 在链接时找不到函数/结构体定义。常见于缺失头文件或开发库。
-
libonig-dev缺失会导致mbstring、PCRE2相关的Definition onig_*错误 -
libreadline-dev缺失会触发Definition rl_*类错误（尤其 PHP 8.4+ 默认启用 readline） -
libxml2-dev和libssl-dev是基础依赖，缺一则整个 configure 阶段就可能跳过关键模块，后续编译时突然报 undefined symbol - Ubuntu/Debian 用户别只装
build-essential，还得补全：sudo apt install autoconf bison re2c libxml2-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libsqlite3-dev libpq-dev libzip-dev libonig-dev libreadline-dev
phpenv 命令找不到或 phpenv init 不生效
这不是安装失败，是 shell 环境没接上。90% 情况下是因为 PATH 或初始化顺序错了。
- 确认
~/.phpenv/bin真的在$PATH里：echo $PATH | grep phpenv，没输出就说明没生效 -
~/.bashrc和~/.bash_profile可能不互通；macOS Catalina+ 默认用zsh，得改~/.zshrc，且必须放在source ~/.zshrc之后再执行eval "$(phpenv init -)" - 执行完配置后，别只
source ~/.bashrc，要新开一个终端或运行exec $SHELL才能确保所有 hook 加载完整 - 如果仍报
phpenv: command not found，直接运行~/.phpenv/bin/phpenv --version看是否可执行——不可执行说明 git clone 失败或权限不对（chmod +x ~/.phpenv/bin/phpenv）
phpenv install 卡在 [Compiling] 或中途退出无日志
卡住 ≠ 冻结，是编译器在跑耗时步骤（比如生成 parser、编译 openssl 绑定），但没输出容易误判。真正失败往往藏在日志末尾。
- 不要 Ctrl+C 中断，先等至少 15 分钟（PHP 8.4.2 全量编译在 4 核机器上常需 8–12 分钟）
- 查日志：
tail -n 50 ~/.phpenv/plugins/php-build/share/php-build/log/8.4.2.log，重点看最后一行是不是make: *** [Makefile:xxx: xxx] Error X - 常见静默失败点：磁盘满（
df -h）、/tmp权限被锁（sudo mount -o remount,exec /tmp）、ulimit -s太小导致栈溢出（设成ulimit -s 65536） - 如果日志里反复出现
configure: error:，说明PHPBUILD_CONFIGURE_OPTS没传进去，或.php-version-options文件路径不对（必须放在当前目录或 HOME 下，且不能是隐藏目录如~/dotfiles/）
装完 php -v 还是旧版本或 command not found
phpenv 安装成功 ≠ 系统开始用它。它靠 shim 机制接管命令，这步容易漏。
立即学习“PHP免费学习笔记（深入）”；
- 先确认版本确实装进去了：
ls -la ~/.phpenv/versions/，看到8.4.2/目录才算落地 - 必须手动运行
phpenv rehash，否则~/.phpenv/shims/php不会生成，shell 就找不到新命令 -
phpenv global 8.4.2后，检查which php输出是不是~/.phpenv/shims/php；如果不是，说明有其他 PHP 在 PATH 更前面（比如系统自带的/usr/bin/php），得调换顺序或删掉干扰项 - Windows 用户注意：phpenv 在原生 Windows 上不工作，必须用 WSL2；若用 phpEnv（带大写 E 的 GUI 工具），那是完全不同的软件，和 phpenv 无关
实际部署时最容易被忽略的是：phpenv rehash 不是可选项，是必做动作；而 PHPBUILD_CONFIGURE_OPTS 环境变量必须在 phpenv install 命令前 export，不能写在脚本里靠 source 加载——子 shell 看不到父 shell 的未导出变量。
