Webman路由404或异常的根本原因在于注册方式、约束粒度与加载时机不匹配：Route::get()默认无正则约束易被绕过，注解路由需PHP≥8.0、命名空间严格对齐且路径以/开头，route.php修改后须清缓存，多应用下glob加载顺序决定覆盖优先级。
Webman 的路由不是“写完就能用”，很多看似正确的配置在实际请求中 404 或行为异常，根本原因往往出在注册方式、约束粒度或加载时机上。核心判断是：手动路由必须显式定义；自动/注解路由必须满足硬性前提；所有路由都受 FastRoute 编译缓存影响。
Route::get() 等快捷方法为什么有时不生效
这些方法本质是 Route::add() 的封装，但默认不带正则约束，导致匹配过于宽松甚至被绕过。比如 Route::get('/user/{id}', [...]) 中的 {id} 实际等价于 ([^/]+)，能匹配 ..%2Fetc%2Fpasswd 这类路径。
- 改用
Route::add('GET', '/user/{id:\d+}', [...])显式声明数字约束，FastRoute 会在分发前直接拒绝非法值 - 高频接口务必加约束，否则无效请求会穿透到控制器，触发中间件、DB 连接甚至日志写入
- 不要依赖控制器里用
filter_var($id, FILTER_VALIDATE_INT)补救——性能和安全性都已失守
注解路由 #[Get] 不生效的三个硬伤
注解不是语法糖，它需要完整链路支持：PHP ≥8.0 + 插件安装 + 命名空间对齐 + 路径以 / 开头。缺一不可。
- 确认
webman-framework版本 ≥v2.2.0，旧版本完全忽略 PHP 属性（Attribute） - 控制器文件路径为
app/controller/UserController.php，命名空间必须是app\controller，不能是App\Controller或app/controller（少反斜杠） -
#[Get('user')]是无效的，必须写成#[Get('/user')]；类上加了#[DisableDefaultRoute]后，所有方法都得显式注解，否则 404
route.php 修改后还是 404？先看缓存
config/route.php 每次请求都会 require，但 FastRoute 的编译结果缓存在 runtime/cache/route.php。修改后不清理，新路由永远不生效。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
立即学习“PHP免费学习笔记（深入）”；
- 开发时执行
php webman route:clear清空缓存（或删掉runtime/cache/route.php文件） - 若在
route.php中调用了env()或容器方法，环境切换后缓存可能失效，建议生产环境关闭自动缓存：'route_cache' => false - 不要在
route.php里做耗时操作（如数据库查询、HTTP 请求），它在每次请求初始化阶段执行
多应用路由拆分时 glob 加载顺序很关键
用 glob("app/**/**/route.php") 自动加载各模块路由时，文件加载顺序决定了路由优先级——后加载的路由会覆盖同路径的先加载路由。
- 确保核心路由（如
/api前缀）在通用路由（如/）之前加载，否则/的fallback可能提前截断请求 - 避免不同应用定义相同路径（如都定义
/health），冲突时以最后加载的为准，调试困难 - 推荐按目录层级控制顺序，例如
app/common/route.php放最前，app/admin/route.php放最后
真正容易被忽略的是：路由不是“写完就跑”，而是要同时对齐框架版本、插件状态、命名空间、缓存机制和加载顺序。任何一个环节错位，都会让请求在到达控制器前就失败，且错误信息往往指向路径不存在，而非配置问题本身。
