laravel 11 文档生成需调整策略注册时机、禁用 kernel 中间件反射、强制 responsefactory 构造响应、并修正缓存配置为 dateinterval 类型，否则将导致路由漏扫、认证标签失效、响应结构丢失及元数据不刷新。
Laravel 9 和 Laravel 11 的文档生成策略表面相似，实则底层逻辑已发生关键演进：核心差异不在注释写法，而在于策略加载机制、元数据解析优先级、以及对框架生命周期的依赖方式。直接复用 Laravel 9 的 apidoc 配置到 Laravel 11 项目，大概率导致路由漏扫、认证标签失效、或响应结构无法提取。
策略注册时机从“静态配置”转向“运行时绑定”
Laravel 9 中，config/apidoc.php 的 strategies 数组在命令启动前就完成加载；Laravel 11 则要求部分策略（尤其是涉及中间件上下文或请求生命周期的）必须在 bootstrap/app.php 的服务注册阶段动态注入。
- Laravel 9：所有策略类在
Generator.php初始化时统一实例化，不感知 HTTP 栈状态 - Laravel 11：新增
RequestContextStrategy类，需在withRouting()后显式挂载，否则@authenticated或@middleware标签将被跳过 - 常见表现：Laravel 11 下未调整策略注册位置，生成的文档中“需要认证”标识消失，但控制台无报错
元数据提取依赖 Kernel 层重构，旧注释可能被忽略
Laravel 11 彻底移除 app/Http/Kernel.php 中的中间件数组，改由 bootstrap/app.php 的闭包管理。而主流 API 文档生成器（如 scribe 或 laravel-api-docs）仍通过反射读取 Kernel 获取路由中间件信息以推断权限模型。
- 若项目升级后保留旧版
Kernel.php文件（即使未使用），部分生成器会错误解析为“无中间件”，导致@group或@middleware注释失效 - Laravel 11 推荐做法：删除
Kernel.php中所有中间件声明，改用$middleware->web(...)方式注册，并在config/apidoc.php中启用'use_kernel_for_middleware' => false - 验证方法：运行
php artisan apidoc:generate --dry-run，检查输出中是否列出预期的中间件链
响应结构提取默认启用 Schema 推导，但需适配 Laravel 11 的响应工厂变化
Laravel 9 默认使用控制器返回值反射 + @response 注释双路径提取响应；Laravel 11 强制要求响应内容必须经过 ResponseFactory 构造（如 response()->json(...)），否则 GetFromResponseTag 策略将跳过该路由。
- 旧写法（Laravel 9 兼容）：
return ['data' => $user];—— 仍可被提取 - 新约束（Laravel 11 推荐）：
return response()->json(['data' => $user]);—— 否则@responseField可能不生效 - 若使用自定义响应宏（如
Response::macro('api')），需在bootstrap/app.php中提前注册，否则策略无法识别返回类型
缓存与并发策略行为变更影响文档生成稳定性
Laravel 11 默认启用 cache.expiration_time 的强类型校验，且文档生成器内部大量使用 Cache::remember 缓存路由分析结果。若未同步更新缓存配置，会导致多次执行 apidoc:generate 时元数据不刷新。
- Laravel 9 允许：
'expiration_time' => '1 hour' - Laravel 11 必须：
'expiration_time' => \DateInterval::createFromDateString('1 hour') - 未修正后果：首次生成正常，二次执行时仍读取旧缓存，新增路由/参数不显示，且无 warning 提示
- 临时绕过：运行命令时加
--no-cache参数，但非长期方案
