Laravel Folio 与传统 Route 混用共存渐进式迁移完整指南【免费下载链接】folioPage based routing for Laravel.项目地址: https://gitcode.com/gh_mirrors/foli/folioLaravel Folio 是 Laravel 官方的基于页面的路由Page Based Routing扩展包它让blade.php视图文件直接对应 URL。最让人放心的一点是Folio 与传统routes/web.php路由可以零冲突地混用共存——你不必一次性推翻现有路由文件而可以逐页渐进式迁移。 为什么混用共存是天然的理解 Folio 与传统 Route 共存的关键只需要知道一行源码。当你在应用里挂载 Folio 时src/FolioManager.php中的registerRoute方法会向 Laravel 路由注册器添加一条fallback兜底路由名称为laravel-folio。这意味着传统路由永远优先Laravel 的 fallback 路由只会在所有显式路由都未命中时才触发所以routes/web.php里已有的路由会自动赢得匹配不需要任何before/after调整。挂载前缀划定管辖范围src/FolioManager.php的handle方法会过滤出 URI 前缀与挂载baseUri匹配的请求才交给 Folio 处理。挂载到/admin就只管/admin开头的请求其余照常走传统路由。匹配不到自动 404src/RequestHandler.php中若在挂载目录里找不到对应视图文件会直接抛出 404不会污染其他路由。一句话总结Folio 站在传统路由的最后两者井水不犯河水这是渐进式迁移得以成立的地基。 一键安装步骤在已有的 Laravel 项目中引入 Folio 只需两步composer require laravel/folio php artisan folio:installfolio:install命令源码见src/Console/InstallCommand.php会自动完成三件事发布FolioServiceProvider到app/Providers/将服务提供者注册进bootstrap/app.phpLaravel 11或config/app.php创建resources/views/pages页面目录。此时项目同时拥有传统路由和 Folio 路由两套体系互不干扰。⚙️ 配置挂载路径与中间件发布出来的FolioServiceProvider对应stubs/FolioServiceProvider.stub模板在boot方法中挂载路径链式调用由src/PendingRoute.php提供Folio::path(resource_path(views/pages)) -middleware([* [auth]]);常用挂载方式一览Folio::path(目录)页面目录挂载到根路径默认Folio::uri(/admin)把同一目录挂载到指定 URI 前缀Folio::domain(api.example.com)限定仅匹配某个域名Folio::middleware([...])按路径模式匹配中间件中间件采用路径模式匹配src/PathBasedMiddlewareList.php*表示全部页面也可以写成/users/{id}精确到某类页面。注意src/RequestHandler.php会在中间件链首自动追加web中间件组与routes/web.php的行为保持一致。 渐进式迁移四步走第一步新区域直接用 Folio存量项目不必动老代码。把新模块如后台/admin、帮助中心/docs挂载到 Folio 目录新功能天然是页面驱动的老模块继续留在web.php。第二步页面型路由逐步搬家识别web.php中只负责返回视图的简单路由return view(...)或控制器单一 action在resources/views/pages下建出同名视图文件即可。例如pages/users/[User].blade.php即对应/users/{user}模型绑定自动完成。用php artisan folio:page别名make:folio源码见src/Console/MakeCommand.php可以快速生成页面骨架多个挂载目录时会交互让你选择。第三步动作型路由留在 web.phpPOST 表单提交、API 端点、含复杂业务逻辑的控制器方法建议继续保留传统写法。Folio 定位是视图即路由强行动作逻辑进页面文件反而违背其设计初衷。混用不是过渡的妥协而是合理的长期分工。第四步验证与上线迁移过程中随时对比两份路由清单php artisan route:list # 传统路由含 laravel-folio 兜底路由 php artisan folio:list # 仅 Folio 页面路由folio:list由src/Console/ListCommand.php实现直接继承 Laravel 的RouteListCommand支持--json、--path、--name等过滤参数格式与route:list风格一致。确认无误后再删除web.php中已搬家的旧路由。 命名路由与 URL 生成的统一混用场景最容易踩的坑是route(xxx)到底指向哪Folio 会自动为视图文件生成名称路径派生如users.index并且src/FolioServiceProvider.php中的registerUrlGenerator给 URL 生成器注册了缺失命名路由解析器resolveMissingNamedRoutesUsing查找逻辑在src/FolioRoutes.php——只要名字能被 Folio 识别route(users.show, $user)就能生成正确 URL无需关心该页面定义在 Folio 还是web.php中。⚠️ 小提醒避免 Folio 页面名称与传统路由Route::name()重名防止解析歧义。 路由缓存无缝集成生产部署常依赖route:cache。Folio 在src/FolioServiceProvider.php的cacheFolioRoutesOnRouteCache中监听命令事件执行route:cache时Folio 页面清单被持久化到bootstrap/cache/folio-routes.phpsrc/FolioRoutes.php的persist执行route:clear时同步清理。也就是说混用项目部署流程完全不需要额外步骤一次route:cache双份都有。 常见问题排查现象原因与解决Folio 页面 404URI 与挂载baseUri前缀不一致用folio:list核对实际挂载的 URI老路由失效通常不是 Folio 抢占它只走兜底检查是否 URI 拼写与页面文件路径不符会话/CSRF 异常确认中间件链含web默认已自动追加自定义挂载时别用-middleware([*[]])覆盖掉改了页面没生效生产环境执行了route:cache新增/删除页面文件后需重新route:cache或route:clear需要自定义渲染如 Inertia在FolioServiceProvider中调用Folio::renderUsing(fn ($request, $matchedView) ...)接管渲染✅ 总结Laravel Folio 与传统 Route 的混用共存之所以可靠源于三个设计兜底路由保证传统路由优先、挂载前缀隔离请求范围、命名路由与缓存体系无缝统一。按新区域先用、页面型路由搬家、动作型路由保留、双清单验证的节奏渐进迁移你可以在零停机、零冲突的前提下让整个 Laravel 项目逐步过渡到更简洁的页面式路由。【免费下载链接】folioPage based routing for Laravel.项目地址: https://gitcode.com/gh_mirrors/foli/folio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考