应为文档生成单独配置干净的中间件组，如'docs'组仅保留trustproxies、handlecors、trimstrings等无状态中间件，并在routes/api.php中临时使用route::middleware('docs')->group()，配合@authenticated注释替代真实鉴权中间件，确保scribe cli环境正常扫描与测试。
生成 Laravel API 文档时，auth:sanctum、throttle、VerifyCsrfToken 等敏感中间件若被意外加载，会导致文档页「Try it out」测试失败（401/419/429），甚至阻断整个生成流程。这不是文档工具的问题，而是环境配置与中间件作用域未隔离所致。
文档生成必须脱离真实请求生命周期
Scribe（或 L5-Swagger）运行在 CLI 环境下，不经过 HTTP 请求管道，也不启动 session、cookie 或跨域逻辑。但如果你的路由组或控制器方法绑定了需状态的中间件，Scribe 在扫描路由时仍会尝试“模拟”执行逻辑——尤其当它调用 Route::getActionName() 或反射控制器方法时，可能触发中间件注册链中的副作用。
- 不要把
auth:sanctum、throttle:60,1、verified等中间件直接写在全局$middleware数组里，否则所有路由都会被强制拦截 - 确保这些中间件只出现在
$middlewareGroups['api']或$middlewareGroups['web']中，并通过路由分组显式启用 - 检查
routes/api.php是否误用了->middleware('web')—— API 路由加 web 组会激活 CSRF 和 session，直接导致文档生成报错
为文档生成单独配置“干净”的中间件组
推荐在 app/Http/Kernel.php 中新增一个专用于文档扫描的中间件组，例如 'docs'，仅保留日志、CORS（可选）、基础解析类，剔除所有鉴权与状态类中间件：
- 在
$middlewareGroups中添加：'docs' => [ \App\Http\Middleware\TrustProxies::class, \Illuminate\Http\Middleware\HandleCors::class, \App\Http\Middleware\TrimStrings::class, ] - 在
routes/api.php顶部临时切换分组：Route::middleware('docs')->group(function () { … }); - 生成完文档后切回
api分组，不影响线上行为
注释中标记 auth 而非依赖中间件执行
Scribe 支持 @authenticated 注释自动渲染 Token 输入框，无需真实触发 auth:sanctum 中间件。只要接口本应受保护，就在方法 PHPDoc 上写这一行即可：
-
/** @authenticated */→ 文档页显示 Authorization 输入框，前端自行填 Bearer Token - 删掉路由上冗余的
->middleware('auth:sanctum')（如果该路由只是文档示例，不走真实流量） - 对真正上线的 API 路由，保持
->middleware('auth:sanctum')不变，但确保它不在docs分组中被扫描
验证是否生效：三步快速确认
执行 php artisan scribe:generate --force 后，打开 public/docs/index.html 测试任意接口：
- 点击「Try it out」→ 填入合法参数 → 点击 Execute：应返回 200/201，而非 401 或超时
- 查看浏览器 Network 面板，确认请求头不含
Cookie、X-XSRF-TOKEN，只有你手动填的Authorization: Bearer ... - 检查生成的
openapi.yaml中对应路径是否含security: [{ bearerAuth: [] }]，说明@authenticated已正确识别
