直接运行 composer require nikic/fast-route 即可安装,无需额外仓库或 dev 分支;它不依赖 PSR-7,纯函数式路由匹配,体积小、无冗余依赖。

FastRoute 怎么通过 Composer 安装
直接运行 composer require nikic/fast-route 就行,不需要额外仓库或 dev 分支。它不依赖 PSR-7 或 HTTP 抽象层,纯函数式路由匹配,所以安装后体积小、无冗余依赖。
常见错误现象:Class 'FastRoute\simpleDispatcher' not found —— 注意函数名是 simpleDispatcher(小写 s),不是 SimpleDispatcher;另外别漏掉 use 声明或自动加载未触发(比如没在 vendor/autoload.php 后 require)。
- 安装后检查
vendor/nikic/fast-route/src是否存在,确认文件已拉取 - 如果项目用了 Composer 的 classmap 或 psr-4 自定义配置,确保没意外覆盖或忽略
FastRoute\命名空间 - PHP 版本需 ≥ 7.4(8.0+ 更稳),低于 7.4 可能因返回类型声明报错
怎么用 simpleDispatcher 配置高性能路由
simpleDispatcher 是 FastRoute 最轻量也最快的入口,适合绝大多数 REST API 或前端控制器场景。它把路由定义和分发逻辑拆开,定义阶段可缓存,分发阶段几乎零开销。
关键点在于:路由定义只执行一次(如放在容器启动或 bootstrap 中),而 dispatch() 调用本身是纯数组查找 + 正则匹配,没有反射、没有对象创建。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 不要每次请求都调用
simpleDispatcher—— 它返回的是一个闭包,但内部会重复解析路由表;应缓存返回的 dispatcher 实例 - 使用
GROUP或addRoute时,HTTP 方法必须大写('GET'、'POST'),小写会匹配失败且不报错 - 路径参数如
/user/{id:\d+}中的正则必须写完整,{id}默认等价于{id:[^/]+},但不校验数字,容易引发类型错误
use FastRoute\simpleDispatcher;
$dispatcher = simpleDispatcher(function (FastRoute\RouteCollector $r) {
$r->addRoute('GET', '/api/users', 'UserController::list');
$r->addRoute('GET', '/api/users/{id:\d+}', 'UserController::get');
});
// 每次请求中复用 $dispatcher
$httpMethod = $_SERVER['REQUEST_METHOD'];
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$routeInfo = $dispatcher->dispatch($httpMethod, $uri);
为什么 dispatch() 返回值要手动处理
dispatch() 不执行 handler,只返回一个三元数组,比如 [FastRoute\Dispatcher::FOUND, ['UserController::get', 'id' => '123'], []]。这是性能取舍:避免自动 call_user_func_array 或反射调用带来的开销。
容易踩的坑是直接 echo 或 return 这个数组,结果页面输出一串数字和字符串——因为没判断 Dispatcher::FOUND 状态就往下走。
- 必须先判断第一个元素是否为
FastRoute\Dispatcher::FOUND,否则可能是NOT_FOUND或METHOD_NOT_ALLOWED - 第二个元素是 handler(字符串或数组),第三个是参数映射;handler 是原始字符串,不会自动解析命名空间,得自己做
is_callable判断或加前缀 - 如果用类方法字符串如
'UserController::get',确保类已加载,否则call_user_func会 fatal error
缓存路由定义提升冷启动性能
开发时路由变频繁,可以不用缓存;但上线后,把 simpleDispatcher 的路由定义过程结果序列化保存,下次直接反序列化,能省掉 80%+ 的路由编译时间。
FastRoute 原生支持缓存:传入 FastRoute\cachedDispatcher 并指定缓存路径即可,底层用 serialize + 文件存储,不依赖 Redis 或 APCu。
- 缓存文件路径必须可写,且注意 Web 进程与 CLI 进程权限一致(比如部署脚本生成缓存,但 PHP-FPM 用户无法读)
- 修改路由后需清空缓存文件,否则新路由不生效;建议在部署流程里加
rm -f cache/routes.php - 缓存文件内容含 PHP 字节码结构,不要手动编辑;出问题时删掉重生成比调试更快
$dispatcher = cachedDispatcher(function (FastRoute\RouteCollector $r) {
$r->addRoute('GET', '/', 'HomeHandler');
}, [
'cacheFile' => __DIR__ . '/cache/routes.php',
]);
FastRoute 的高性能不是靠黑科技,而是靠不做多余的事:不抽象请求、不封装响应、不自动加载类、不验证参数类型。一旦你开始往里面塞中间件、自动 DI 注入、或试图兼容 Laravel 的路由语法,那它就不再是 FastRoute 了。


















