PHP版本不匹配导致服务启动失败的典型现象是解析错误或函数未定义，根源在于CLI、Web服务器、FPM及Composer平台配置未对齐，需逐项验证并统一至项目所需版本。
PHP版本低于要求导致服务启动失败的典型现象
看到类似 Parse error: syntax error, unexpected '[' 或 Fatal error: Uncaught Error: Call to undefined function sodium_crypto_aead_xchacha20poly1305_ietf<em>encrypt()</em> 这类报错，基本可以锁定是 PHP 版本太低。现代框架（Laravel 9+、Symfony 6+）、Composer 包（如 ramsey/uuid v4+）或扩展函数（sodium*、str_starts_with()）都依赖 PHP 7.4、8.0 甚至 8.1+ 的语法或内置能力。
常见触发场景包括：
- 执行
php artisan serve或php bin/console server:run失败 - Nginx/Apache 加载 PHP-FPM 时 worker 启动即退出
-
composer install成功但运行时报Function not found
确认当前 PHP 实际版本和 CLI/FPM 是否一致
很多问题出在「你以为用的是 PHP 8.x，其实 CLI 和 Web 走的是不同二进制」。先分别查清：
- 终端执行：
php -v（看 CLI 版本） - 创建一个
info.php文件，内容为<?php phpinfo(); ?>，通过浏览器访问（看 Web SAPI 实际加载的版本） - 若用 PHP-FPM，查进程：
ps aux | grep php-fpm，再对主进程 PID 执行ls -l /proc/{PID}/exe确认调用路径
特别注意：
立即学习“PHP免费学习笔记（深入）”；
- macOS 用 Homebrew 安装多版本时，默认
php可能指向旧版，而php@8.2是新版别名 - Ubuntu/Debian 上
php命令可能由update-alternatives管理，需运行sudo update-alternatives --config php - Docker 中镜像标签（如
php:7.4-apache）写死版本，改配置不改镜像无效
修改 Web 服务器配置强制使用指定 PHP 版本
Apache 和 Nginx 不会自动“升级”PHP，必须显式指向新版二进制或 socket。
Apache（mod_php 模式已淘汰，现多用 FPM）：
- 确保启用
proxy_fcgi和setenvif - 在虚拟主机中指定：
ProxyPassMatch ^/(.<em>.php(/.</em>)?)$ fcgi://127.0.0.1:9001/var/www/html/（对应 PHP-FPM 监听地址） - 更可靠的是用 Unix socket：
fcgi://unix:/var/run/php/php8.2-fpm.sock
Nginx：
- 检查
fastcgi_pass行是否匹配实际 PHP-FPM 配置（如fastcgi_pass unix:/run/php/php8.2-fpm.sock;） - 对应的 pool 配置文件（如
/etc/php/8.2/fpm/pool.d/www.conf）必须存在且未被注释
漏掉这步，哪怕系统装了 PHP 8.2，Web 请求仍会落到旧版 FPM 进程上。
Composer 和项目 require 对 PHP 版本的隐性约束
composer.json 中的 "php": "^8.1" 只影响 composer install 阶段校验，不阻止运行时调用低版本 PHP。但更隐蔽的问题是：
-
composer.lock里记录的包版本，可能已在安装时降级适配旧 PHP（比如选了monolog/monologv2.8 而非 v3.x），导致后续即使升 PHP 也缺新功能 - 某些包的 autoloader 会做运行时 PHP 版本检查（如
symfony/polyfill自动 fallback，但性能差、行为不一致）
建议操作：
- 升级 PHP 后，删掉
vendor/和composer.lock，重新composer install - 运行
composer show php确认当前环境满足platform.php设置 - 如需临时兼容，可在
composer.json加"config": {"platform": {"php": "8.2.0"}}，但仅用于构建，不解决运行时问题
PHP 版本不匹配的问题，往往不是“没装对”，而是“没切对”——CLI、FPM、Web 服务器、Composer 平台配置，四个地方只要一个没对齐，就会表现成“启动失败”，排查时得一个个拎出来打点验证。
