PHP 8.4环境未就绪导致composer install/update失败，需确认php -v显示8.4版本、补全fileinfo等核心扩展、验证autoload解析、检查.env兼容性，并升级Composer至2.5.8+。
新项目执行 composer install 或 composer update 时卡住、报错或提示找不到扩展，说明 PHP 8.4 环境未真正就绪，依赖安装失败不是 Composer 本身的问题，而是底层 PHP 解析器或扩展缺失导致的加载中断。
确认 PHP 8.4 是否被 Composer 正确识别
在项目根目录下执行：
php -v
必须看到明确输出类似 PHP 8.4.7 (cli) 的版本号。如果显示的是 8.3、8.2 或其他版本，说明当前终端默认 PHP 并非宝塔中安装的 8.4 —— 这是绝大多数“依赖安装失败”的起点。此时需手动指定路径：
/www/server/php/84/bin/php -v
若该命令能正确显示 8.4 版本，但直接 php -v 不行，则需将 /www/server/php/84/bin 加入系统 PATH，或后续所有 composer 命令强制前缀：
/www/server/php/84/bin/php /usr/bin/composer install
立即学习“PHP免费学习笔记（深入）”；
检查核心扩展是否已启用
PHP 8.4 编译安装后，fileinfo、mbstring、json、openssl、curl、zlib、xml 这些是 Composer 运行的硬性依赖，缺一不可。任意一个未启用，composer 就会在初始化阶段直接退出，不报具体错误。
执行：
/www/server/php/84/bin/php -m | grep -E "fileinfo|mbstring|json|openssl|curl|zlib|xml"
若某项未出现在输出中（例如完全没看到 fileinfo），不要点面板重试按钮——它不会自动补全扩展。必须进入宝塔 → 软件商店 → PHP 8.4 → 设置 → 安装扩展 → 勾选对应项并安装。特别注意：fileinfo 必须手动安装且依赖 Swap 内存，1G 内存服务器未配 1024MB Swap 时，fileinfo 编译会静默失败，面板显示“安装成功”实则未生成 .so 文件。
验证 vendor/autoload.php 是否可被 PHP 8.4 正确解析
方法一：用 PHP 8.4 直接执行 autoload 文件
/www/server/php/84/bin/php -f vendor/autoload.php
若报 Parse error、Fatal error 或 Class not found，说明 vendor 中某个包存在 PHP 8.4 不兼容语法（如废弃的 create_function、动态属性写法、弱类型比较升级为严格校验）。
方法二：临时降级检测范围
先删掉 vendor 和 composer.lock：
rm -rf vendor composer.lock
再仅安装最基础 autoload 支持：
/www/server/php/84/bin/php /usr/bin/composer install --no-scripts --no-plugins
成功后再逐步启用 scripts 和 plugins。这能快速区分是 autoload 结构问题，还是后期脚本执行失败。
排查 .env 或配置文件引发的早期中断
第一步：① 进入项目根目录，确认是否存在 .env 文件；
② 临时重命名它：
mv .env .env.bak
第二步：执行最小化加载测试：
/www/server/php/84/bin/php -r "require 'vendor/autoload.php'; echo 'OK';"
若输出 OK，说明问题出在 .env 加载环节——常见于 laravel/framework 11+ 或 symfony/dotenv 6.x 在 PHP 8.4 下对注释解析异常，或 .env 中存在未转义的 $ 符号触发变量展开失败。此时需检查 .env 内容是否含 $APP_KEY=base64:... 这类值，$ 后紧跟字母数字时会被误解析，应改为 \$APP_KEY=base64:...。
检查 Composer 自身与 PHP 8.4 的兼容性
旧版 Composer（如 2.2.x）无法识别 PHP 8.4 的新特性标识，会在解析 composer.json 时抛出 “does not match the expected format” 类错误。
执行：
/www/server/php/84/bin/php /usr/bin/composer --version
必须为 Composer 2.5.8 或更高版本。若低于此版本，立即升级：
/www/server/php/84/bin/php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
/www/server/php/84/bin/php composer-setup.php --filename=composer --install-dir=/usr/bin
升级后务必清除 Composer 全局缓存：
/www/server/php/84/bin/php /usr/bin/composer clear-cache
