CakePHP本地项目路由配置：子目录设根路径的全域路由方案

一、核心问题原因 #

你当前的访问路径localhost/projectName/controller/action被CakePHP误判为：控制器名为projectName，导致"找不到控制器"的错误——框架默认把URL的第一个路径段当作控制器名，不知道projectName是项目的子目录前缀。

二、推荐方案：配置服务器指向项目webroot（规范做法） #

这是最稳妥的解决方式，从根源上让localhost/projectName成为项目根：

Apache配置 #

修改httpd.conf或虚拟主机配置文件，将项目的webroot目录设为DocumentRoot：

<VirtualHost *:80>
    DocumentRoot "/本地项目路径/projectName/webroot"
    ServerName localhost.projectName
    <Directory "/本地项目路径/projectName/webroot">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

然后在本地hosts文件添加127.0.0.1 localhost.projectName，之后直接访问localhost.projectName/controller/action即可，无需额外路由修改。

Nginx配置 #

在nginx.conf中添加对应server块：

server {
    listen 80;
    server_name localhost.projectName;
    root /本地项目路径/projectName/webroot;
    index index.php;

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

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

同样修改hosts文件后，即可正常访问。

三、临时方案：仅通过路由适配子目录前缀 #

如果无法修改服务器配置，可在config/routes.php中添加全域路由规则，跳过projectName前缀解析：

// 优先匹配带projectName前缀的所有控制器/动作请求
$routes->connect(
    '/projectName/:controller/:action/*',
    [],
    ['pass' => ['controller', 'action']]
);

// 匹配项目根路径（localhost/projectName）指向首页
$routes->connect(
    '/projectName',
    ['controller' => 'Pages', 'action' => 'display', 'home']
);

// 保留原有默认路由（放在前缀规则之后）
$routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
$routes->fallbacks(DashedRoute::class);

配置后，所有localhost/projectName/xxx/yyy格式的请求会自动将xxx识别为控制器、yyy识别为动作，不再把projectName当作控制器。

注意：这种路由适配只是临时 workaround，后续可能出现静态资源加载、URL生成异常等问题，长期建议用服务器配置的方式解决。

内容的提问来源于stack exchange，提问作者J.B.J.