在CodeIgniter开发中，页面访问返回404是最让人头疼却又极常见的问题。多数情况下这并不是代码逻辑出错，而是框架没有正确将URL映射到对应的控制器和方法。理解框架的路由解析机制，并对照一份实用的检查清单，可以快速终结这类无效调试。
一、CodeIgniter路由是如何工作的
当浏览器发起一个请求，比如访问 https://ipipp.com/index.php/user/profile，CodeIgniter首先会剔除index.php以及配置中定义的URL后缀，剩下的URI段为 user/profile。随后框架加载 application/config/routes.php 文件，按照数组中规则从上到下的顺序进行匹配。如果命中自定义路由，就转向指定控制器；若未命中，则尝试将第一段当作控制器名、第二段当作方法名自动映射。
当自动映射也失败时，框架会寻找 $route['default_controller'] 设定的默认控制器。如果该控制器文件缺失、类名错误或者方法被声明为私有，依然会抛出404。因此，404的本质是“URI段在路由表与文件系统两层映射中都落空”。我们在排查时，必须同时确认服务器重写层和PHP框架层是否一致。
二、路由配置检查清单
下面列出最容易导致404的配置点，建议按顺序逐一核对。每一项都附带了常见错误写法与正确示例。
1. 控制器文件与类名大小写
在Linux服务器上，文件名大小写敏感。若文件名为 User.php 但路由解析出 user，系统会找不到类。CodeIgniter要求控制器文件名首字母大写，类名同样首字母大写且继承自 CI_Controller。
错误示例：文件名为 user.php，类名为 user。正确写法如下：
<?php
// 文件位置：application/controllers/User.php
class User extends CI_Controller {
public function profile() {
echo '用户中心';
}
}
2. routes.php中的默认控制器
很多项目直接删除了默认控制器配置，或写成了不存在的类。打开 application/config/routes.php，确认以下两项：
$route['default_controller']指向真实存在的控制器$route['404_override']若设置，对应控制器也要存在
示例配置：
<?php $route['default_controller'] = 'home'; $route['404_override'] = ''; $route['translate_uri_dashes'] = FALSE;
3. 隐藏index.php的服务器重写
若想用 https://ipipp.com/user/profile 而非带 index.php 的地址，必须在Web服务器配置重写规则。Apache需在根目录放置 .htaccess，Nginx需在站点配置中写 try_files。规则缺失会令所有干净URL返回404。
Apache的 .htaccess 示例：
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 [L]
4. 自定义路由顺序与正则
路由规则自上而下匹配，通配符 (:any) 若写在具体规则之前，会拦截本应命中后者的请求。应把精确规则放前面，宽泛规则放后面。
<?php // 正确顺序 $route['user/profile'] = 'user/profile'; $route['user/(:any)'] = 'user/index/$1'; $route['(:any)'] = 'pages/show/$1';
5. URL后缀与允许字符
配置 $config['url_suffix'] 若设为 .html，访问时不带后缀也会404。同时 permitted_uri_chars 限制了URI可用字符，包含空格或特殊符号会被拒绝。
| 配置项 | 常见错误值 | 建议值 |
|---|---|---|
| url_suffix | .html（但链接未带） | 留空或统一带后缀 |
| permitted_uri_chars | 过严导致中文段失效 | a-z0-9_-~%:.+ |
三、快速自查流程
遇到404时，先打开浏览器开发者工具看请求地址是否含index.php；再查服务器重写是否生效；接着打印 $this->router->fetch_class() 确认框架解析出的类；最后核对文件存在性与大小写。按清单走一遍，绝大多数路由型404都能在十分钟内解决。
路由配置看似简单，却串联了服务器与框架两层解析。把上述清单贴在项目Wiki中，每次部署前核对一次，可显著降低线上404概率。
CodeIgniter路由配置404错误修改时间：2026-08-08 00:09:35