必须升级Composer，因1.x已于2022年9月终止维护，不支持PHP 8.2的enum、readonly语法，会报ParseError；2.7.x是当前唯一稳定支持PHP 8.2–8.3的版本。
composer --version 输出是 1.x 或低于 2.7.0？必须升级
Composer 1.x 已于 2022 年 9 月终止维护，不识别 PHP 8.2 的 enum、readonly 语法，运行时直接报 Fatal error: Uncaught ParseError: syntax error, unexpected token "enum"。Composer 2.5.0 起强制要求 PHP ≥ 8.0，2.7.x 是当前唯一稳定支持 PHP 8.2–8.3 的主线版本。
- 运行
composer --version，若输出含1.或2.6.及更低，立即重装 - 别用
sudo apt install composer—— Ubuntu/Debian 官方源仍卡在 2.0.13 - 执行官方脚本：
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"，再校验 SHA384（去 https://www.php.cn/link/594ca739e3609243a6b6a3dd8d871114 复制最新值），最后sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer - 旧版残留路径（如
/usr/bin/composer）必须手动sudo rm，否则新命令不生效
composer.json 里 "php": "^8.2" 写对了，但 install 还是失败？检查 platform 解析结果
Composer 不读你终端里的 php -v，它只认 composer.json 中的 require.php 和 config.platform.php。写宽泛（如 "^8.0"）或漏配 platform，会导致拉下实际不兼容 PHP 8.2 的包（比如未更新 composer.json 的旧版 symfony/polyfill），运行时报 Fatal error: Cannot inherit previously-inherited or override final method。
- 运行
composer show --platform | grep php，确认输出是类似php : 8.2.22，不是8.0.28或空 - 显式锁定最低版本：
"require": {"php": "^8.2"}，别加|| ^7.4分支 - 若开发机是 PHP 8.3 但生产环境是 8.2.10，用
"config": {"platform": {"php": "8.2.10"}}强制依赖解析按目标环境走 - 验证是否生效：
composer why-not php:8.2（注意：该命令仅对正确声明require.php的包有效）
vendor/autoload.php 加载时报错 Class not found 或 readonly 属性解析失败？重建 autoload 映射
PHP 8.2 对 readonly 类属性和常量初始化更严格。如果项目 PSR-4 规则覆盖了含 readonly 的类，但 Composer 生成的 vendor/autoload.php 是在旧 PHP 版本下缓存的，就会在首次 require 时触发解析失败，错误信息类似 ParseError: Cannot declare readonly property。
- 执行
composer dump-autoload -o强制重建优化后的自动加载映射（-o启用 classmap 优化） - 删掉
vendor/autoload.php和vendor/composer/autoload_*.php，再跑一次composer install - 检查
composer.json中autoload配置是否覆盖了含新特性的目录，例如："psr-4": {"App\": "src/"}若src/下有readonly类，确保没有拼写错误或路径遗漏 - 临时调试：新建最小脚本
test.php，仅require_once 'vendor/autoload.php';，然后php -l test.php看是否报语法错误
global require 的 laravel/installer 或 hyperf/cli 找不到命令？PATH 没生效
composer global require 只把二进制文件放进 ~/.composer/vendor/bin/，但这个路径默认不在系统 PATH 里。Windows/macOS/Linux 表现一致：命令不存在不是没装，而是 shell 找不到。
立即学习“PHP免费学习笔记（深入）”；
- 查真实 bin 目录：
composer global config bin-dir --absolute（别猜默认路径） - Linux/macOS：在
~/.zshrc或~/.bashrc末尾加export PATH="$(composer global config bin-dir --absolute):$PATH"，然后source ~/.zshrc - Windows：将该路径（如
%APPDATA%Composer endorin）加入系统或用户级PATH，**必须重启 CMD/PowerShell** - 验证：
echo $PATH或echo %PATH%确认路径已包含，再运行laravel --version
config.platform.php 和 composer show --platform 的输出差异——它不反映你本地 php -v 的结果，只忠实地执行你配置的约束。任何“本地能跑、线上崩”的问题，八成出在这里。 
