CakePHP路由匹配失败的根本原因是Router::connect()严格按定义顺序匹配，固定路由必须置于泛用路由之前；正则约束不影响优先级，需手动排序；修改后需清缓存生效。

正则路由匹配失败、动态路由意外覆盖固定路由，根本原因不是写法错，而是 Router 匹配顺序和优先级没理清。

Router::connect() 的匹配顺序就是执行顺序

CakePHP 的 Router::connect() 不会自动按“精确度”排序，它严格按 routes.php 中定义的先后顺序逐条尝试匹配。一旦某条规则命中，就停止后续匹配——后面的规则哪怕更具体也完全不生效。

• 错误写法：把泛用路由（如 '/:controller/:action/*'）写在前面，后面再写 '/admin/login'，结果 /admin/login 被前一条捕获，永远进不到 AdminController::login()
• 正确做法：所有固定路径（'/login'、'/api/v1/users'）、带明确字面量的路由，必须放在泛用路由（含 :id、:slug、*）之前
• 调试技巧：临时在 routes.php 开头加 debug(Router::routes());，看实际加载顺序是否符合预期

正则约束（options 参数）只过滤，不提升优先级

给 Router::connect() 第三个参数传 ['id' => '[0-9]+']，只是告诉 Router：“如果 URL 里这个位置是数字才匹配”，但它不会让这条路由比没约束的同路径规则更早被选中。

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 常见误区：以为 Router::connect('/article/:id', [...], ['id' => '\d+']) 会优先于 Router::connect('/article/:slug', [...]) —— 实际上谁写在前面谁赢
• 真正起作用的是路径模板本身：更长、字面量更多、通配符更少的路径天然更“具体”，但 CakePHP 不做自动推断，你得手动排位
• 注意：正则中的 ^ 和 $ 会被 Router 自动加上，别自己写，否则报错或失效

如何安全地插入一条高优先级路由

想临时加一个紧急重定向或特殊处理，又怕破坏现有顺序？别直接塞到文件末尾，用 Router::scope() + 显式前置声明更可控。

立即学习“PHP免费学习笔记（深入）”；

• 推荐写法：在 routes.php 最顶部立即写一个独立 scope，比如针对维护页或灰度路径：

  Router::scope('/', function (RouteBuilder $routes) {
      $routes->connect('/maintenance', ['controller' => 'Pages', 'action' => 'maintenance']);
      $routes->redirect('/old-api/*', '/api/v2/$1', ['status' => 301]);
  });
  

• 这样能确保这些规则绝对在默认路由、插件路由、以及后续 scope 之前加载
• 避免混用 Router::connect() 和 $routes->connect() 在同一 scope 内——前者是静态调用，后者走 builder 流程，行为不一致，容易漏掉匹配

最常被忽略的一点：修改 routes.php 后，开发环境可能缓存旧路由表。运行 bin/cake cache clear_all 才能真正生效，光刷新页面没用。