Laminas Framework路由异常问题排查与解决方案咨询

核心问题 #

1. 如何让(G)和(H)被Laminas统一处理，渲染自定义的'404 Page Not Found'页面？
2. (C)和(D)返回404 Not found是否正常？还是应渲染index.phtml？

各URI访问表现 #

• (A) www.domain.com：渲染自定义index.phtml，正常
• (B) www.domain.com/：渲染自定义index.phtml，正常
• (C) www.domain.com/index.php：渲染自定义404，存疑
• (D) www.domain.com/index.php/：渲染自定义404，存疑
• (E) www.domain.com/dog：渲染自定义404，正常
• (F) www.domain.com/dog/：渲染自定义404，正常
• (G) www.domain.com/dog.php：返回PHP-FPM的"File Not Found"，异常
• (H) www.domain.com/dog.php/：渲染自定义404，正常

环境配置信息 #

Nginx配置 #

index index.php;

server {
    listen 80;
    listen  [::]:80;

    server_name www.domain.com;
    root        /var/www/public;

    location / {
            try_files $uri $uri/ /index.php;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass docker-php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Laminas目录结构 #

- website/public/index.php  # 应用入口
- website/module/Application/view/application/index.phtml  # 自定义首页
- module/Application/view/error/404.phtml # 自定义404页面
- dog、dog.php不存在

补充日志 #

• (G)请求未到达Laminas，日志返回"Primary script unknown"
• (H)请求正常路由到Laminas并返回自定义404

问题解答 #

问题1：统一处理(G)和(H)返回自定义404 #

问题根源是Nginx的.php$规则会拦截dog.php请求，直接交给PHP-FPM处理，但该文件不存在，所以返回PHP-FPM原生错误。

解决方法（修改Nginx配置）

推荐用try_files替代原有逻辑，确保脚本不存在时转发到Laminas入口：

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass docker-php:9000;
    fastcgi_index index.php;
    # 先检查文件是否存在，不存在则转发到index.php
    try_files $fastcgi_script_name /index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

修改后，dog.php会被转发到Laminas，由路由系统处理并返回自定义404，和(H)表现统一。

问题2：(C)和(D)返回404是否正常？ #

当前表现不正常，直接访问index.php应该渲染首页index.phtml。

原因与修复

Laminas默认路由会把index.php当作路由参数而非入口文件识别，可通过以下两种方式修复：

方式1：Nginx层面优化

修改location /的try_files规则，确保index.php请求正确传递参数：

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

方式2：Laminas路由配置

在module/Application/config/module.config.php的路由配置中，增加index.php的匹配规则：

'router' => [
    'routes' => [
        'home' => [
            'type' => Laminas\Router\Http\Literal::class,
            'options' => [
                'route'    => '/',
                'defaults' => [
                    'controller' => Application\Controller\IndexController::class,
                    'action'     => 'index',
                ],
            ],
            'may_terminate' => true,
            'child_routes' => [
                'index_php' => [
                    'type' => Laminas\Router\Http\Literal::class,
                    'options' => [
                        'route'    => '/index.php',
                        'defaults' => [
                            'controller' => Application\Controller\IndexController::class,
                            'action'     => 'index',
                        ],
                    ],
                ],
            ],
        ],
    ],
],

对于index.php/这类请求，若希望返回首页，可额外增加正则路由匹配，或通过Nginx重写规则将index.php/重定向到/。

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