Laravel 12/13 多模态API文档生成要求PHP≥8.1（Laravel 12）或≥8.2（Laravel 13），必须严格匹配框架版本；官方推荐使用l5-swagger或laravel-openapi，禁用不兼容的旧版apidoc-generator，并同步更新laravel-lang等依赖以避免冲突。
多模态API文档生成在 Laravel 12/13 中虽强大，但依赖冲突是高频拦路虎——不是工具不行，而是版本链没对齐。核心矛盾常出现在 框架主版本、PHP运行时、文档生成器扩展包、语言包或OpenAPI适配器 四者之间。只要理清约束关系，问题基本可控。
确认Laravel与PHP版本是否匹配
多模态文档功能（如内置 OpenAPI 推导、@apiResource 自动解析）从 Laravel 12 起深度集成，但要求 PHP ≥ 8.1；Laravel 13 则强制要求 PHP ≥ 8.2。若你用的是 Ubuntu 或其他 Linux 系统：
- 运行
php -v检查实际版本，注意 CLI 和 Web SAPI 版本可能不一致 - 查看
composer.json中"laravel/framework"的版本，对照官方兼容表（例如 Laravel 13.x 对应"php": "^8.2"） - 若 PHP 版本偏低，不要强行降级文档包，应先升级 PHP（如 Ubuntu 上用
sudo apt install php8.2-cli并切换默认版本）
检查文档生成器与Laravel主版本的绑定关系
Laravel 12/13 的多模态能力已原生增强，传统第三方包（如 mpociot/laravel-apidoc-generator）在 Laravel 13 下大概率失效或部分失能。官方推荐路径是：
- 优先使用 Laravel 自带机制：基于
@OA\Get等注解 +l5-swagger（适配 Laravel 12+）或laravel-openapi（轻量、Laravel 13 原生友好） - 若坚持用旧版 apidoc-generator，请明确指定分支：
composer require --dev mpociot/laravel-apidoc-generator:4.x（仅兼容 Laravel 10–11），不支持 Laravel 12/13 的路由合并与中间件新注册方式 - 安装前运行
composer why-not laravel/framework:13.0可快速定位哪个包在阻断升级
处理 laravel-lang 等国际化依赖的连带冲突
很多团队在加多模态文档的同时会引入 laravel-lang/lang 实现中文错误提示或文档本地化，但它极易引发连锁冲突：
- 错误典型提示：
require laravel-lang/publisher ^17.0 but found v13.2.0 - 必须核对版本矩阵：Laravel 13 →
laravel-lang/lang:^12.0+laravel-lang/publisher:^17.0+ - 执行命令时带上依赖联动更新：
composer require laravel-lang/lang --update-with-dependencies - 若已有
composer.lock锁死旧版 publisher，可先运行composer update laravel-lang/publisher --with-all-dependencies再装 lang
清理缓存与锁定文件再重试
Composer 的缓存和 lock 文件有时会固化过期解析路径，尤其在多次尝试不同版本后：
- 清除 Composer 全局缓存：
composer clear-cache - 删除项目级
vendor/和composer.lock - 重新执行
composer install（非update），确保所有依赖按当前composer.json严格重建 - 验证是否生效：
composer show | grep -E "(swagger|openapi|lang)"查看实际加载版本
