phpEnv配置微擎站点教程 phpEnv特定环境参数配置指南-php教程-PHP中文网

phpenv和phpEnv是两个完全不同的工具：phpenv是Linux/macOS下命令行驱动的PHP版本管理工具，依赖编译，支持项目级版本切换；phpEnv是Windows图形化集成环境，版本锁定、不支持自由升级，与微擎v4+兼容性差。

phpenv配置微擎站点教程 phpenv特定环境参数配置指南

phpEnv 不是 phpenv —— 这是两个完全不同的东西，混用会导致环境彻底失效。微擎官方文档和生产部署实践里压根不提 phpEnv（Windows 集成包），它和 phpenv（Linux/macOS 多版本管理工具）在定位、实现、配置逻辑上毫无交集。你要配微擎，得先分清自己用的是哪套底层环境。

确认你实际在用的是 phpenv 还是 phpEnv

如果你在 macOS 或 Linux 终端里敲 phpenv --version 能返回版本号，且路径是 ~/.phpenv，那你用的是 phpenv；如果你双击运行的是一个带图形界面的 Windows 程序，主窗口写着“PHPEnv 控制面板”，那才是 phpEnv（已多年未更新，不支持 PHP 8.2+，与微擎 v4+ 兼容性差）。

phpenv：命令行驱动，靠 phpenv local 7.4.33 切换项目级 PHP 版本，依赖编译，适合开发者本地调试多版本兼容性
phpEnv：Windows 桌面软件，内置 Apache/MySQL/PHP 打包，版本锁定死，无法自由升级 PHP，.php-version 文件对它完全无效
微擎 v3.0+ 强制要求 mbstring、openssl、pdo_mysql、curl、fileinfo 等扩展启用，phpEnv 默认不开启 fileinfo 和 opcache，直接导致安装页白屏或提示“缺少必要扩展”

phpenv 下跑微擎必须启用的扩展和参数

微擎不是普通 PHP 应用，它在安装和运行阶段会主动探测扩展状态。用 phpenv install 编译时若漏掉关键选项，装完也跑不起来。

必须加 --enable-mbstring：微擎路由解析、模板渲染全依赖 mbstring，缺了直接 500
必须加 --with-pdo-mysql：哪怕你用的是 MySQLi，微擎底层仍会 fallback 到 PDO 检测逻辑
必须加 --enable-fileinfo：上传模块、图片处理、插件校验都走这个扩展，不启用则后台上传失败、模块安装卡住
推荐加 --enable-opcache：微擎模板缓存和 opcode 缓存强耦合，不启用会导致页面加载慢 3 倍以上
避免用 --disable-cgi：微擎部分 CLI 工具（如 ./framework/cli.php）依赖 CGI SAPI，禁用后定时任务执行失败

完整编译示例：phpenv install 7.4.33 --enable-mbstring --with-pdo-mysql --enable-fileinfo --enable-opcache

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

phpenv 的 .php-version 文件对微擎无效？不是，是你放错了位置

.php-version 文件只在当前目录及其子目录生效，但微擎的入口是 web/ 子目录下的 index.php，而多数人把 .php-version 放在项目根目录（即包含 app/、data/、web/ 的那一层）。phpenv 的 shims 只在执行命令时读取该文件，Web Server（如 Nginx）启动的 PHP-FPM 进程根本不看它。

正确做法：确保 Web Server 的 PHP-FPM pool 配置指向你用 phpenv which php 查到的实际二进制路径，例如 /Users/xxx/.phpenv/versions/7.4.33/bin/php
验证方式：在微擎 web/ 目录下建个 info.php，写，浏览器访问，看 “Loaded Configuration File” 是否指向你期望的 7.4.33 的 php.ini
别信 phpenv local 后立刻生效——它只影响 shell 当前目录下的 php 命令，不影响 FPM。FPM 必须手动 reload

微擎安装时提示 “mysqli extension not loaded” 却 php -m 里有？

这是最典型的配置错位：CLI 和 FPM 使用的是两套 php.ini。你用 php -m 看到的扩展，是 CLI SAPI 加载的；而微擎走的是 FPM，它加载的是另一个 php.ini（通常在 ~/.phpenv/versions/7.4.33/etc/php-fpm.d/www.conf 里指定的 php_admin_value[extension_dir] 路径下的配置）。

查 CLI 的 ini：运行 php --ini
查 FPM 的 ini：在 phpinfo() 页面搜索 “Configuration File (php.ini) Path”
常见错误：编译时加了 --enable-mysqli，但 FPM 的 php.ini 里没写 extension=mysqli.so，或者写成了 extension=php_mysqli.dll（Linux 下无效）
临时验证：在 FPM 的 php.ini 末尾加一行 extension=mysqli（不带 .so），然后 sudo pkill php-fpm && phpenv exec php-fpm