Laminas框架控制器路由失效，访问/api/resource/*返回404求助

DevOps 小满

2026-7-9

在Laminas框架中添加控制器与路由后出现404问题

我正尝试在Laminas框架中添加新控制器及对应路由，已将RoleApi\ConfigProvider::class注入到config.php中，但访问所有/api/resource/*路径均返回404错误。

我的模块结构如下（附图片）：

ConfigProvider代码如下：

<?php

declare(strict_types=1);

namespace RoleApi;


use Laminas\Router\Http\Segment;
use Laminas\ServiceManager\Factory\InvokableFactory;
use RoleApi\Application\Controller\ResourceController;

/**
 * The configuration provider for the RoleApi module
 *
 * @see https://docs.laminas.dev/laminas-component-installer/
 */
class ConfigProvider
{
    /**
     * Returns the configuration array
     *
     * To add a bit of a structure, each section is defined in a separate
     * method which returns an array with its configuration.
     */
    public function __invoke(): array
    {
        return [
            'dependencies' => $this->getDependencies(),
            'templates' => $this->getTemplates(),
            'controllers' => $this->getControllers(),
            'router' => $this->getRouter(),
        ];
    }

    /**
     * Returns the container dependencies
     */
    public function getDependencies(): array
    {
        return [
            'invokables' => [
            ],
            'factories' => [
            ],
        ];
    }

    /**
     * Returns the templates configuration
     */
    public function getTemplates(): array
    {
        return [
            'paths' => [
            ],
        ];
    }

    public function getControllers(): array
    {
        return [
            'factories' => [
                ResourceController::class => InvokableFactory::class,
            ],
        ];
    }

    public function getRouter(): array
    {
        return [
            'routes' => [
                'resource' => [
                    'type' => Segment::class,
                    'options' => [
                        'route' => '/api/resource[/:action[/:id]]',
                        'constraints' => [
                            'action' => '[a-zA-Z][a-zA-Z0-9_-]*',
                            'id' => '[0-9]+',
                        ],
                        'defaults' => [
                            'controller' => ResourceController::class,
                            'action' => 'index',
                        ],
                    ],
                ],
            ]
        ];
    }
}

请问我哪里操作有误？

排查与解决步骤

确认控制器继承关系：ResourceController必须继承Laminas\Mvc\Controller\AbstractActionController（RESTful控制器则继承AbstractRestfulController），否则Laminas无法识别为有效控制器，直接导致路由匹配失败。
校验控制器文件路径与命名空间：确保ResourceController.php文件在RoleApi/Application/Controller/目录下，类名、命名空间与代码完全一致，Linux环境下注意大小写敏感问题。
验证配置是否合并成功：在public/index.php中临时添加代码，打印合并后的应用配置，确认controllers.factories和router.routes中包含你的配置：
```
$app = \Laminas\Mvc\Application::init(require 'config/application.config.php');
var_dump($app->getServiceManager()->get('Config'));
exit;
```
检查是否存在RoleApi\Application\Controller\ResourceController的工厂配置，以及resource路由是否存在。
检查路由优先级与冲突：如果有其他路由也匹配/api/resource/*，会优先匹配其他路由导致404。可以给当前路由添加priority参数提高优先级：
```
'resource' => [
    'type' => Segment::class,
    'priority' => 100, // 数值越高优先级越高
    'options' => [
        // 现有路由配置
    ],
],
```
确认模块已注册：检查config/modules.config.php或config/application.config.php中的modules数组，是否添加了RoleApi模块，未注册的模块其ConfigProvider不会被加载。
测试基础路由：先访问/api/resource（不带action和id），如果仍返回404，说明路由未被加载；如果能访问，再检查action和id是否符合约束规则（action必须以字母开头，id必须是纯数字）。

内容的提问来源于stack exchange，提问作者Cawa

Laminas框架控制器路由失效，访问/api/resource/*返回404求助

排查与解决步骤 #

排查与解决步骤