CodeIgniter路由分组定义方法

本文深入解析了CodeIgniter 4中路由分组（$routes->group()）的核心用法与常见陷阱：强调其必须通过闭包调用而非赋值，路径前缀不带斜杠且支持嵌套叠加，所有过滤器、命名空间和HTTP方法限定都需在闭包内显式设置，完全不兼容CI3的路由语法——任何照搬旧写法的行为都会导致404、路由不注册或致命错误；掌握这些关键差异，能帮你避开升级和开发中最频繁的路由失效问题，写出清晰、可维护、符合CI4设计哲学的路由结构。

CI4 中的 $routes->group() 必须用闭包，不能直接赋值

很多人照着 CI3 的写法在 CI4 里写 $routes->group('admin') = function() {...}，结果路由完全不生效——因为 CI4 的 group() 是一个方法调用，返回的是一个可链式操作的路由实例，不是变量赋值目标。它必须紧跟闭包，且闭包参数必须接收 $routes 实例本身。

常见错误现象：404、访问 /admin/users 时进不到控制器、php spark routes 命令不显示该组下任何路由。

• 正确写法：$routes->group('admin', function($routes) { $routes->get('users', 'Admin\Users::index'); });
• 闭包内不能再用 $routes = service('routes') 或重新获取实例，否则会脱离当前分组上下文
• 路径前缀自动拼接，group('api/v1') + get('users') → 实际匹配 /api/v1/users

路由分组嵌套时，前缀是叠加的，不是覆盖的

CI4 允许 group() 嵌套，但新手常误以为内层 group('v2') 会“重置”路径，实际是字符串拼接。比如 group('api') 内再 group('v2')，最终前缀是 api/v2，不是单独的 v2。

使用场景：为不同 API 版本或权限域（如 admin、api、public）隔离路由逻辑，避免重复写前缀。

• 嵌套示例：$routes->group('api', function($routes) { $routes->group('v1', function($routes) { $routes->get('posts', 'Api\V1\Posts::index'); }); }); → 匹配 /api/v1/posts
• 注意斜杠：每个 group() 的字符串**不带开头或结尾斜杠**，框架自动处理，写成 group('/api/') 会导致双斜杠或匹配失败
• 嵌套过深（>3 层）会让调试变困难，建议用命名空间+控制器前缀替代部分嵌套

$routes->group() 不支持 HTTP 方法限定，需在内部显式指定

你不能写 $routes->group('api', ['filter' => 'auth'])->post('login', ...) 这类带选项的 group 调用——CI4 的 group() 方法只接受字符串前缀和闭包，所有过滤器、HTTP 方法限制、命名空间等都得在闭包内部逐条设置。

性能影响：分组本身无运行时开销，但若在 group 内反复调用 $routes->setNamespace() 或 $routes->setFilter()，要注意作用域是否符合预期（它们只对后续定义的路由生效，不影响已定义的）。

• 正确加 filter：$routes->group('admin', function($routes) { $routes->setFilter('role:admin'); $routes->get('dashboard', 'Admin\Dashboard::index'); });
• 错误写法：$routes->group('admin', ['filter' => 'role:admin'], function($routes) {...}) —— 第二个参数会被忽略
• 命名空间要手动设：$routes->setNamespace('App\Controllers\Admin')，否则默认仍是 App\Controllers

CI3 和 CI4 的分组语法差异极大，混用必报错

CI3 根本没有 $routes->group()，它的“分组”靠手写前缀（如 $route['admin/users'] = 'admin/users'）或第三方扩展实现。如果你从 CI3 升级上来，看到文档里有 group 就直接抄，大概率整个路由文件加载失败，或触发 Fatal error: Call to undefined method CodeIgniter\\Routing\\RouteCollection::group()。

容易踩的坑：升级后保留旧版 routes.php 文件，又新建了 CI4 风格的 Routes.php，但没删旧文件；或者在 CI4 项目里误用了 CI3 的 $route 数组写法。

• CI4 路由文件路径是 app/Config/Routes.php，内容必须以 开头，且第一行通常是 use CodeIgniter\\Routing\\RouteCollection;
• CI4 改完路由后必须清缓存：php spark cache:clear 或删 writable/cache 下对应文件，否则新分组不生效
• CI3 的 application/config/routes.php 在 CI4 中被完全忽略，哪怕它还存在

复杂点在于：分组只是路径前缀和作用域的封装，它不改变路由匹配优先级，也不自动处理子域名或协议切换。真要按后台/前台分离、多租户或子域名路由，得配合自定义路由类或中间件，而不是依赖 group()。

到这里，我们也就讲完了《CodeIgniter路由分组定义方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！