phpenv仅管理PHP版本切换，不提供Web服务器或API调试能力；需额外配置Nginx+PHP-FPM、正确设置fastcgi_pass与重写规则，并确保对应PHP版本的扩展和php.ini生效，否则易出现404、502或500错误。
phpenv 本身不直接提供 Web 服务器或 API 调试能力，它只负责管理 PHP 版本切换；要跑通本地 API，你必须额外配好 Web 服务（如 Nginx + PHP-FPM）和路由规则，否则 phpenv 切换完版本，curl http://localhost/api/users 依然 404 或 502。
phpenv 安装后必须手动启用 PHP-FPM
很多人以为装完 phpenv 就能直接跑 PHP 脚本，其实它只改了 php 命令的指向。Web 请求走的是 PHP-FPM 进程，而 phpenv install 默认不启动、也不注册 FPM 服务。
- 确认当前 PHP 版本已编译 FPM：运行
phpenv which php得到路径后，检查同级目录是否存在php-fpm（例如~/.phpenv/versions/8.2.12/sbin/php-fpm） - 手动启动 FPM：用
~/.phpenv/versions/8.2.12/sbin/php-fpm -y ~/.phpenv/versions/8.2.12/etc/php-fpm.conf，注意路径要和你安装的版本一致 - 关键配置项：
listen = /var/run/php/php8.2-fpm.sock必须和 Nginx 的fastcgi_pass对齐；如果报错 “No such file or directory”，说明 sock 文件路径不匹配或权限不对 - 别依赖系统级 service：macOS/Linux 上
phpenv安装的 PHP 是用户级的，systemd 或 brew services 都管不到它
Nginx 配置里不能硬写 PHP 版本号
当你用 phpenv global 8.1 切换版本后，Nginx 不会自动感知——它的 fastcgi_pass 仍连着旧版 sock 文件，导致 502 Bad Gateway。
- 推荐做法：在 Nginx
server块里用变量或符号链接统一指向当前版本，例如fastcgi_pass unix:/var/run/php/current.sock;，再由脚本维护/var/run/php/current.sock软链到真实路径 - 更稳妥的调试方式：改用 TCP 端口而非 Unix socket，比如
fastcgi_pass 127.0.0.1:9001;，并在 PHP-FPM 的www.conf里设listen = 127.0.0.1:9001，避免 socket 权限问题 - 切版本后必须重启 PHP-FPM（不是 reload），否则新配置不生效；Nginx 可 reload，但 FPM 必须 stop → start
API 路由 404 的真正原因常不在代码里
用 phpenv 搭 API 时，index.php 能返回 JSON，但 /api/v1/users 404，大概率是 Web 服务器没配对重写规则，而不是框架路由错了。
立即学习“PHP免费学习笔记（深入）”；
- ThinkPHP/Laravel 等框架依赖
try_files $uri $uri/ /index.php?$query_string;，漏掉这行，所有非物理文件路径都会 404 - Apache 用户注意：
.htaccess是否被允许？检查AllowOverride All是否在对应Directory块中启用 - 用
curl -v http://localhost/index.php/api/users直接调入口，能通说明框架正常，问题纯属 Nginx/Apache 配置 - 别在
phpenv下用内置服务器（php -S）跑 API：它不支持并发、无重写、不读.htaccess或 Nginx 规则，仅适合极简 demo
最易被忽略的一点：phpenv 管理的 PHP 版本，其 php.ini 和扩展是独立的。比如你用 phpenv install 8.2.12，那 pdo_mysql、mbstring、json 这些扩展必须在该版本的 php.ini 里显式开启，且路径指向该版本的 extensions 目录——缺一个，API 就可能卡在数据库连接或中文处理上，错误日志却只显示 “500 Internal Server Error”，没有具体提示。
