phpenv 启动配置必须写入 shell 初始化文件（如 ~/.zshrc 或 ~/.bashrc），添加 export PATH="$HOME/.phpenv/bin:$PATH" 和 eval "$(phpenv init -)" 两行，执行 source 生效；phpenv init - 需动态执行不可复制粘贴；项目级版本依赖 .php-version 文件置于根目录；phpenv global 不影响系统级进程。
phpenv 启动配置必须写进 shell 初始化文件
phpenv 本身没有“开机启动”概念，它依赖 shell 启动时加载的初始化逻辑。如果你关掉终端再打开，phpenv 命令就报 command not found，说明初始化没生效——根本原因就是 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）里漏了关键两行。
常见错误现象：phpenv --version 正常，但新开一个终端后 phpenv 找不到；或者 php -v 显示系统自带 PHP，不是 phpenv 管理的版本。
- 必须把这两行同时加进你的 shell 配置文件（注意不是
~/.profile或~/.bash_profile，除非你明确知道它被 source）： export PATH="$HOME/.phpenv/bin:$PATH"eval "$(phpenv init -)"- Zsh 用户默认读
~/.zshrc，Bash 用户通常读~/.bashrc；macOS Catalina 及之后默认用 Zsh，别错配成.bash_profile - 加完后执行
source ~/.zshrc（或对应文件），不要只靠重启终端——有些终端（如 VS Code 内置终端）不会自动 reload
为什么 phpenv init - 输出的内容不能直接复制粘贴
phpenv init - 不是静态字符串，它会根据当前 shell 类型动态生成 shim 路径和补全逻辑。直接复制输出内容到配置文件，下次换 shell 或升级 phpenv 就可能失效。
正确做法永远是让 shell 在每次启动时实时调用它，即保留 eval "$(phpenv init -)" 这一行。它实际做的事包括：
立即学习“PHP免费学习笔记（深入）”；
- 在
$HOME/.phpenv/shims建立所有已安装 PHP 版本的php、phpize、composer等命令软链 - 把
$HOME/.phpenv/shims插入PATH最前面，确保优先调用 shims 而非系统 PHP - 为当前 shell 注册命令补全（比如敲
phpenv in<tab></tab>自动补全成install）
phpenv local 和 .php-version 文件必须放在项目根目录
项目级版本切换不靠“开机启动”，而靠目录感知。当你执行 phpenv local 8.2.18，它会在当前目录写一个 .php-version 文件，内容就是 8.2.18。下一次你 cd 进这个目录，shim 机制自动识别并激活对应版本。
容易踩的坑：
-
.php-version必须是纯文本，不能有空格、BOM、换行符；Windows 编辑器保存容易带 BOM，建议用vim或 VS Code（编码选 UTF-8 without BOM） - 如果子目录里也有
.php-version，它会覆盖父目录的设置——这是设计行为，不是 bug -
phpenv local不会自动rehash，安装新版本后进项目目录首次运行php可能失败，手动跑一次phpenv rehash即可
全局版本 phpenv global 不等于系统默认 PHP
phpenv global 8.3.13 只影响所有未设置 .php-version 的目录，它不修改 /usr/bin/php，也不影响 cron、systemd service 或其他脱离用户 shell 环境的进程。
如果你需要让 cron 任务也走 phpenv 管理的 PHP，不能只设 global，得显式指定路径：
0 2 * * * /home/you/.phpenv/versions/8.3.13/bin/php /path/to/script.php
或者在 crontab 里先 source 环境：
0 2 * * * cd /path/to/project && source ~/.zshrc && php script.php
注意：systemd service、supervisord 等更严格，它们默认不加载用户 shell 配置，必须在 unit 文件里用 Environment=PATH=... 显式注入 $HOME/.phpenv/shims。
