Matomo 运行依赖 Web 服务器调用的 PHP-FPM 实例，而非 phpenv 管理的 CLI 版本；需确保 Nginx 的 fastcgi_pass 指向正确版本的 php-fpm socket 或端口，并验证该 FPM 实例加载了 mysqli、mbstring 等必要扩展及对应 php.ini 配置。
phpenv 本身不安装 Matomo，它只管理 PHP 版本；Matomo 是独立 PHP 应用，需手动部署在 phpenv 提供的 PHP 环境之上。 混淆这两者会导致权限错误、php-fpm 启动失败或 Matomo 报 “PHP version too low” —— 因为 phpenv 切换的版本未被 Web 服务器实际调用。
确认 phpenv 管理的 PHP 被 Web 服务器使用
Matomo 运行依赖 Web 服务器（如 Nginx/Apache）调用正确的 PHP-FPM 实例。phpenv 安装的 PHP 是 CLI 版本，默认不提供 php-fpm 服务。你必须额外编译或安装对应版本的 php-fpm 并手动配置。
- 运行
phpenv versions查看已安装版本（如8.3.13），再执行phpenv which php确认 CLI 路径（如~/.phpenv/versions/8.3.13/bin/php） - 但
php-fpm不在该路径下 —— 它通常位于/usr/sbin/php-fpm8.3（系统包）或需用php-build插件重编译带 FPM 支持的版本 - 检查当前生效的 FPM：运行
ps aux | grep php-fpm，看进程指向哪个二进制；若用系统 PHP（如php8.1-fpm），则 phpenv 的版本切换对 Matomo 无效 - Nginx 配置中
fastcgi_pass必须指向真实运行的 FPM socket，例如unix:/run/php/php8.3-fpm.sock，而非 phpenv 的 bin 目录
用 phpenv 版本编译带 FPM 的 PHP（非 apt 包）
若坚持用 phpenv 管理的 PHP 运行 Matomo（比如测试兼容性），必须启用 FPM 支持。这需要 php-build 插件和手动编译，不能仅靠 phpenv install 默认行为。
- 先安装插件：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 设置编译选项（关键！）：
export PHP_BUILD_CONFIGURE_OPTS="--enable-fpm --with-mysqli --with-pdo-mysql --with-openssl --with-zlib" - 执行安装：
phpenv install 8.3.13—— 此时会在~/.phpenv/versions/8.3.13/sbin/php-fpm生成 FPM 二进制 - 手动启动：
~/.phpenv/versions/8.3.13/sbin/php-fpm -y ~/.phpenv/versions/8.3.13/etc/php-fpm.conf（需先复制并修改默认配置，指定pid、error_log和wwwpool） - Nginx 的
fastcgi_pass改为127.0.0.1:9000或对应 socket 路径
Matomo 安装时验证 PHP 环境是否匹配
Matomo 安装向导的「系统检查」页显示的 PHP 版本，取决于 Web 服务器调用的 PHP，不是终端里 php -v 的结果。常见误判点：
立即学习“PHP免费学习笔记（深入）”；
- 浏览器访问
http://yoursite/matomo显示 “PHP 7.4 required”，但终端执行phpenv local 8.3.13 && php -v显示 8.3 —— 说明 Web 服务器仍在用旧版 FPM - Matomo 报错
mbstring extension is missing：即使php -m | grep mbstring有输出，也要确认该扩展在 FPM 的php.ini中启用（路径通常是~/.phpenv/versions/8.3.13/etc/php-fpm.d/www.conf对应的php.ini） - 数据库连接失败却提示“PHP extension mysqli not loaded”：实际是 FPM 加载了另一个
php.ini（可通过phpinfo()页面确认Loaded Configuration File路径）
更推荐的组合方式：phpenv + 系统 PHP-FPM
生产环境不建议用 phpenv 编译的 PHP-FPM 托管 Matomo。稳定性、日志管理、systemd 集成都远不如系统包。正确分工是：
- 用
phpenv global 8.3.13管理开发时的 CLI 工具链（如composer、phpunit） - 用
apt install php8.3-fpm php8.3-mysql php8.3-mbstring安装系统级 FPM，由systemctl管理 - Matomo 网站根目录下放
.php-version文件仅作团队开发提示，不影响运行时 - 部署脚本中用
phpenv exec 8.3.13 composer install确保依赖按目标版本解析
真正容易被忽略的是：Matomo 的 config/config.ini.php 中 [Database] 段的 databaseHost 若填 localhost，PHP 会尝试走 socket 连接；而 MariaDB 默认只监听本地 socket，不监听 127.0.0.1 的 TCP 端口 —— 导致连接超时。此时应填 127.0.0.1 或确认 skip-networking 在 /etc/mysql/mariadb.conf.d/50-server.cnf 中已被注释。
