config/routes.php 是唯一有效的路由配置文件位置，Hyperf 启动时硬编码加载该路径，不支持改名、挪位或自动扫描其他文件，注解路由需额外启用扫描且有方法与路径限制。
config/routes.php 是唯一有效的路由配置文件位置
Hyperf 启动时只加载 config/routes.php 这一个 PHP 文件作为显式路由定义入口。它不是可选路径，也不是约定多个文件，框架内部通过 Hyperf\HttpServer\Router\DispatcherFactory 硬编码读取该路径，不存在「自动扫描子目录」或「按命名匹配加载」机制。
常见误操作包括：在 config/autoload/ 下新建 route.php、把路由写进 config.php、或试图用 require 引入其他路由文件——这些都不会生效，也不会报错，只是静默忽略。
为什么不能改名或挪位置
config/routes.php 被写死在 Hyperf\HttpServer\Router\DispatcherFactory::loadRoutes() 的逻辑里，源码中直接调用 include BASE_PATH . '/config/routes.php'。哪怕你把文件重命名为 routes_v2.php 并手动 include，也绕不过后续的 RouteCollector 初始化流程，因为 Router 类的静态方法（如 get()、addGroup()）依赖的是同一个全局收集器实例。
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
- 修改文件名 → 启动报错：
Warning: include(.../config/routes.php): failed to open stream - 删掉该文件 → 启动不报错，但所有自定义路由失效，仅剩框架内置的
/健康检查路由 - 在其他地方调用
Router::get()（比如控制器构造函数里）→ 无效果，因路由注册必须在服务启动前完成
@Controller 和 @AutoController 不依赖 routes.php，但有硬性限制
注解式路由（@Controller、@AutoController）走的是反射扫描机制，由 Hyperf\Di\Aop\ProxyManager 在容器初始化阶段解析，不读 config/routes.php。但它们有明确约束：
-
@AutoController只支持GET和POST，且路径严格按类名小写/方法名拼接（如TestController::list()→/test/list），无法指定 HTTP 方法或中间件 -
@Controller需配合@RequestMapping使用，且必须声明prefix，否则不会注册任何路由 - 注解路由默认不启用 —— 必须确保
config/autoload/annotations.php中'scan' => ['paths' => [BASE_PATH . '/app']]已正确配置，否则扫描不到
调试路由是否生效的最快方式
别靠猜，直接用命令行验证：
- 执行
php bin/hyperf.php route:list→ 列出所有已注册路由（含注解和routes.php的） - 若为空，说明
config/routes.php没被加载，或文件内没调用任何Router::xxx()方法 - 若部分缺失，检查是否在
routes.php开头漏了use Hyperf\HttpServer\Router\Router;，PHP 8.1+ 会因命名空间错误导致整段路由代码不执行且无提示
真正容易被忽略的点是：路由注册必须在 return 之前完成，config/routes.php 是一个返回空数组的配置文件，但它的执行过程本身就是在注册路由——不是靠返回值，而是靠副作用。
