Laravel 9路由列表存在API路由但访问返回404问题排查

AI 小北

2026-9-3

问题原因

最高概率为路由注册顺序错误，其余常见原因按发生概率排序如下：

路由匹配优先级问题：Laravel路由按注册顺序从上到下匹配，先命中的路由优先生效。如果带动态参数的api/videos/{video}路由（通常由Route::apiResource/Route::resource自动生成）注册在api/videos/random之前，请求/api/videos/random时会先命中动态路由，把字符串random当做{video}参数传入。由于默认开启路由模型绑定，框架会查询ID为random的Video记录，查询失败抛出ModelNotFoundException，最终渲染为404页面。
站点根目录配置错误：Web服务器的文档根目录没有指向Laravel项目的public目录，而是指向项目根目录，请求没有经过Laravel入口文件index.php处理，直接查找物理路径不存在返回404。
访问路径错误：Laravel加载api.php路由时默认全局添加api前缀，如果直接访问/videos/random而不是/api/videos/random，会走web.php路由匹配，无对应路由时返回404。
Public目录存在同名物理资源：如果public目录下存在api/videos/random的文件或文件夹，Web服务器会优先返回物理资源，资源不存在时直接返回404，不会转发给Laravel处理。

修复方案

针对路由顺序问题

调整路由注册顺序，将固定路径的路由放在带动态参数的路由/资源路由前面，示例代码：

// routes/api.php
use App\Http\Controllers\VideoController;
use Illuminate\Support\Facades\Route;

Route::prefix('videos')->group(function() {
    Route::controller(VideoController::class)->group(function () {
        // 固定路径路由优先注册
        Route::get('/random', 'random');
        // 后注册资源路由/动态参数路由，参数名保持为{video}和原有逻辑一致
        Route::apiResource('/', VideoController::class)->parameters(['' => 'video']);
    });
});

调整完成后执行以下命令清除路由缓存：

php artisan route:clear

再执行php artisan route:list确认api/videos/random路由排在api/videos/{video}路由上方即可。

也可以给动态参数添加数字约束，从规则上避免字符串匹配到动态路由，不受注册顺序影响：

Route::get('/{video}', 'show')->whereNumber('video');

针对站点根目录配置错误

调整Web服务器配置，将文档根目录指向Laravel项目下的public目录，重启Web服务器生效。
Nginx核心配置参考：

server {
    listen 80;
    server_name 你的站点域名;
    root /项目实际路径/public; # 必须指向public目录
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    # PHP解析相关配置省略
}

Apache核心配置参考：

<VirtualHost *:80>
    DocumentRoot "/项目实际路径/public"
    ServerName 你的站点域名
    <Directory "/项目实际路径/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

针对访问路径错误

访问时补全/api前缀，使用http://你的域名/api/videos/random访问即可。

针对Public目录同名资源问题

删除public目录下和路由路径重名的物理文件、文件夹即可。

内容的提问来源于stack exchange，提问作者A 'dumb' person