本文面向 CodeIgniter 4 新手，系统讲解为何访问 /home 报 404、如何正确定义路由、以及关键配置要点（如 public/ 目录设置、BaseURL、路由优先级），帮助开发者快速打通 URL 到控制器的调用链。
本文面向 codeigniter 4 新手，系统讲解为何访问 `/home` 报 404、如何正确定义路由、以及关键配置要点（如 `public/` 目录设置、baseurl、路由优先级），帮助开发者快速打通 url 到控制器的调用链。
在 CodeIgniter 4 中，控制器不会自动根据类名或文件名暴露为可访问的 URL 路径——这与 CI3 的“自动路由”不同，CI4 默认禁用自动路由（$routes->setAutoRoute(false)），强调显式、安全、可控的路由定义。因此，即使你已创建 app/Controllers/Home.php 并包含 index() 方法，若未在 app/Config/Routes.php 中明确定义对应路由，访问 /home 必然返回：
404 - File Not Found Can't find a route for 'get: home'.
✅ 正确配置基础路由
打开 app/Config/Routes.php，在默认路由组中添加你的路径映射。例如，要让 http://localhost/home 访问 Home::index()，需写入：
// app/Config/Routes.php
$routes->get('/home', 'Home::index');
⚠️ 注意：
- 路径 /home 是 URL 路径（浏览器地址栏输入的部分），不是控制器文件名；
- 'Home::index' 是 控制器类名 + 方法名，大小写必须严格匹配（类名 Home 首字母大写，方法 index 小写）；
- 使用 $routes->get() 表示仅响应 GET 请求；如需支持 POST 等，可单独添加 $routes->post('/home', 'Home::store')。
你也可以将根路径 / 指向 Home 控制器：
$routes->get('/', 'Home::index'); // 访问 http://localhost/ 即触发 Home::index()
? 关键配置检查清单（新手易错点）
| 项目 | 正确配置示例 | 常见错误 |
|---|---|---|
| Web 根目录 | XAMPP 的 httpd.conf 指向 htdocs/crm/public/ ✅ | 指向 htdocs/crm/ 或 htdocs/crm/app/ ❌（会导致安全风险或 404） |
| App Base URL | app/Config/App.php 中： public $baseURL = 'http://localhost/'; |
写成 'http://localhost/crm/public/' 或留空 → 资源加载失败 |
| 环境模式 | 确保 .env 中 CI_ENVIRONMENT = development（便于调试） | 生产环境未配置日志或关闭错误显示，掩盖真实问题 |
| 路由顺序 | 自定义路由写在 $routes->setDefaultController('Home'); 之前 | 将通配符路由（如 (:any)）放在最前 → 拦截所有请求，静态路由失效 |
? 不要依赖“自动路由”
CI4 默认关闭自动路由（查看 Routes.php 中是否有 $routes->setAutoRoute(false);）。即使启用（true），它也仅匹配 /controller/method 格式（如 /home/index），且不推荐用于生产环境（存在安全隐患和不可控行为）。因此，始终建议显式声明路由，例如：
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
// 推荐：清晰、安全、可维护
$routes->get('/about', 'Page::about');
$routes->get('/contact', 'Page::contact');
$routes->post('/subscribe', 'Newsletter::store');
✅ 验证与调试技巧
-
查看当前有效路由：运行 CLI 命令（确保在项目根目录）：
php spark routes
输出将列出所有已注册路由，确认 /home 是否出现在其中。
-
检查命名空间与类结构：
app/Controllers/Home.php 必须严格如下：<?php namespace App\Controllers; // ✅ 不可省略，不可写错 use CodeIgniter\Controller; class Home extends BaseController { public function index() { return view('welcome_message'); } } -
清除缓存（开发阶段）：
CI4 会缓存路由配置，修改 Routes.php 后执行：php spark cache:clear
? 总结
/home 404 的根本原因不是环境配置错误，而是 缺少显式路由声明。CodeIgniter 4 的设计哲学是“约定优于配置，但配置必须明确”——没有魔法，只有清晰的契约。只要确保：
✅ public/ 是 Web 根目录
✅ App.php 的 $baseURL 正确指向域名根
✅ Routes.php 中定义了 get('/home', 'Home::index')
✅ 控制器类位于 App\Controllers 命名空间且继承 BaseController
即可稳定访问。掌握这一机制，是你迈出 CI4 开发坚实的第一步。
