如何在 CodeIgniter 中创建自定义的 404 错误页面：从入门到精通

2026-02-13 20:17:35 0条评论 3次阅读 0人点赞

作为一个开发者，我们深知网站的用户体验（UX）至关重要。而在浏览网页时，最令人沮丧的经历莫过于点击一个链接却看到浏览器默认的枯燥错误信息，或者是那个毫无美感的 "404 Not Found"。通常情况下，这些页面是因为用户尝试访问一个不存在的链接、输入了错误的 URL，或者是因为我们重构网站时导致了链接失效而产生的。

在 CodeIgniter 这样的框架中，虽然它自带了默认的错误处理机制，但在实际的生产环境中，我们往往希望创建一个自定义的 404 页面。这不仅能保持网站风格的一致性，还能通过添加友好的提示、返回首页的按钮甚至有趣的导航来留住用户。因此，在本文中，我们将作为一个团队，深入探讨如何从零开始，在 CodeIgniter 中创建一个既美观又专业的自定义 404 错误页面，并深入讲解其背后的工作原理和最佳实践。

为什么我们需要自定义 404 页面？

在开始编写代码之前，让我们先理解为什么要这么做。一个默认的错误页面会向用户暴露技术细节（有时甚至是服务器的路径信息），这既不安全也不美观。通过自定义 404 页面，我们可以：

提升用户体验：告诉用户发生了什么，而不是显示冷冰冰的代码。
品牌一致性：即使是错误页面，也应该包含你的 Logo、导航栏和配色方案。
SEO 优化：虽然 404 页面不应被索引，但良好的内部链接结构有助于搜索引擎爬虫理解网站结构。
转化率：提供一个“返回首页”的链接，可以降低用户的跳出率。

为了实现这一目标，我们需要完成三个核心步骤：创建视图、创建控制器以及配置路由。让我们一步步来实现它。

—

第一步：创建视图

视图是用户直接看到的部分。在 CodeIgniter 中，所有的 HTML 展示层通常都放在 application/views/ 目录下。

我们需要在这个目录下创建一个名为 error404.php 的文件。标准的默认错误页面通常不包含任何 CSS 样式，看起来非常简陋。为了使我们的 404 错误页面更具吸引力，我们可以通过添加内部 CSS 或者链接外部样式表来美化它。

下面是一个包含内部 CSS 的 HTML 代码示例。这个设计虽然简单，但通过绝对定位和鲜明的配色，能够迅速抓住用户的注意力。

文件路径: application/views/error404.php




    
    页面未找到 - 404 错误
    
        /* 简单的重置样式 */
        body {
            margin: 0;
            padding: 0;
            font-family: ‘Arial‘, sans-serif;
            background-color: #2c3e50; /* 深色背景，减少刺眼感 */
            color: #ecf0f1;
            height: 100vh;
            display: flex;
            justify-content: center;
            align-items: center;
        }

        /* 错误内容容器 */
        .error-container {
            text-align: center;
            background-color: #27ae60; /* 绿色背景，代表友好的提示 */
            padding: 40px;
            border-radius: 10px;
            box-shadow: 0 10px 25px rgba(0,0,0,0.5);
            width: 100%;
            max-width: 500px;
        }

        h1 {
            font-size: 80px;
            margin: 0;
            color: #fff;
            border-bottom: 2px solid rgba(255,255,255,0.3);
            padding-bottom: 20px;
        }

        h2 {
            margin-top: 20px;
            font-size: 24px;
            color: #fff;
        }

        p {
            margin: 20px 0;
            line-height: 1.6;
        }

        /* 返回首页按钮样式 */
        .home-btn {
            display: inline-block;
            text-decoration: none;
            background-color: #fff;
            color: #27ae60;
            padding: 10px 20px;
            border-radius: 5px;
            font-weight: bold;
            transition: background-color 0.3s;
        }

        .home-btn:hover {
            background-color: #ecf0f1;
        }
    


    
        404
        哎呀，页面走丢了！
        您访问的页面似乎已被移除、重命名或暂时不可用。
        请检查 URL 是否正确，或点击下方按钮返回首页。
        
        <a href="" class="home-btn">返回首页

代码解析：

在这段代码中，我们使用了 Flexbox 布局来确保内容始终在视口中垂直水平居中。这比旧式的 INLINECODE5c0d9a8d + INLINECODE04198c13 负值方法更加现代化和稳定。此外，我们添加了一个“返回首页”的按钮，这在实际开发中非常重要，它能把迷失的用户“救”回来。注意这里我们使用了 PHP 的 base_url() 函数来动态生成首页链接，这能确保无论你的项目部署在哪个目录下，链接都是有效的。

—

第二步：创建控制器

有了好看的“外壳”，我们需要一个逻辑来控制它的显示。在 CodeIgniter 中，当页面未找到时，我们需要捕获这个请求并将其指向我们的视图。

我们需要在 INLINECODE71b2e770 目录下创建一个名为 INLINECODEf419cc79 的控制器文件。

这里有一个非常关键的技术细节：HTTP 状态码。即使我们要显示一个漂亮的页面，搜索引擎和浏览器仍然需要知道这是一个错误页面，而不是一个正常的页面。因此，我们在加载视图之前，必须显式地通过 $this->output->set_status_header(‘404‘) 将 HTTP 响应头状态设置为 404。如果不这样做，浏览器可能会认为这是一个正常的 200 OK 页面，这被称为“软 404”，对 SEO 是不利的。

让我们来看看控制器的完整代码。

文件路径: application/controllers/customError404.php

load->helper(‘url‘);
    }

    /**
     * 错误处理入口方法
     */
    public function index() {
        // 设置 HTTP 状态头为 404
        // 这非常重要，告诉客户端/搜索引擎该页面不存在
        $this->output->set_status_header(‘404‘);
        
        // 加载我们刚才创建的视图
        // 你也可以在这里传递一些数据给视图，例如记录日志
        $data[‘page_title‘] = "404 Page Not Found";
        $this->load->view(‘error404‘, $data);
    }
}

深入理解代码：

defined(‘BASEPATH‘)：这是 CodeIgniter 的安全机制，防止文件被直接访问。
$this->output->set_status_header(‘404‘)：这是本控制器的核心。如果你发现你的自定义页面在 Google Search Console 中被标记为“未找到（软 404）”，通常就是因为少了这一行代码。
扩展性思考：你可能会问，如果我想记录这些 404 错误以便后续修复链接怎么办？是的，我们可以在这里添加日志逻辑。例如：

        // 在 index() 方法中添加日志记录
        log_message(‘error‘, ‘404 错误发生: ‘ . current_url());

这样，所有的 404 访问都会被记录在 application/logs/ 目录中，方便我们排查问题。

—

第三步：配置路由

现在我们有了视图和控制器，但 CodeIgniter 还不知道什么时候应该使用它们。我们需要修改路由配置来告诉框架：“当你找不到对应的控制器或方法时，请调用 CustomError404 控制器。”

我们需要编辑位于 INLINECODE71fc175b 目录下的 INLINECODE080c7b12 文件。

步骤详解：

打开 application/config/routes.php 文件。
找到 $route[‘404_override‘] 配置项。默认情况下，它通常是被注释掉的或者是空的。
将其修改为指向我们刚才创建的控制器。

修改后的代码片段 (application/config/routes.php)：

<?php
// ... 其他配置 ...

// 关键配置：当页面未找到时，CodeIgniter 会调用这个控制器
// 注意：这里不需要加上完整的命名空间或后缀，直接写类名即可
$route['404_override'] = 'customError404'; 

// ... 其他配置 ...

常见问题解答：

Q: 我修改了路由，但是显示的还是默认的 404 页面，为什么？

* A: 请确保你的文件名 INLINECODE21842408 和类名 INLINECODEd232da6b 是完全匹配的（在 Linux 服务器上大小写敏感）。此外，确保你的控制器文件确实在 application/controllers/ 目录下。

—

进阶：实现多样化的 404 页面（JSON 支持）

在现代 Web 开发中，我们的应用通常不仅仅服务于浏览器，还需要为移动 App 或前端框架（如 Vue, React）提供 API 接口。当 API 请求的资源不存在时，返回 HTML 页面是不合适的，我们应该返回 JSON 格式的错误信息。

我们可以对控制器进行简单的优化，使其能够根据请求类型自动返回 HTML 或 JSON。

优化后的控制器代码 (application/controllers/CustomError404.php)：

load->helper(‘url‘);
    }

    public function index() {
        // 设置 404 状态头
        $this->output->set_status_header(‘404‘);

        // 检查请求是否为 AJAX 或期望 JSON
        if ($this->input->is_ajax_request() || $this->input->get_header(‘Accept‘) === ‘application/json‘) {
            // 返回 JSON 格式错误
            $this->output
                ->set_content_type(‘application/json‘)
                ->set_output(json_encode([
                    ‘status‘ => false,
                    ‘error‘ => ‘Not Found‘,
                    ‘message‘ => ‘The requested resource was not found on this server.‘,
                    ‘status_code‘ => 404
                ]));
        } else {
            // 返回 HTML 视图
            $data[‘heading‘] = "404 Page Not Found";
            $data[‘message‘] = "Sorry, we couldn‘t find the page you‘re looking for.";
            $this->load->view(‘error404‘, $data);
        }
    }
}

这个改进非常实用。通过 INLINECODE9f743584 或检查 HTTP 头 INLINECODE4785237e，我们可以智能地决定返回格式。这使得我们的自定义错误处理更加健壮，适应全栈开发的需求。

—

测试与验证

完成上述所有步骤后，我们需要验证一下我们的工作成果。

保存所有文件：确保 INLINECODE14b76f4a、INLINECODE454c2b45 和 routes.php 都已正确保存。
清除缓存（如果有的话）：如果你在使用 OPcache 或浏览器缓存，建议先清除。
模拟 404：在浏览器地址栏中输入你的网站域名后跟一个不存在的路径，例如 http://your-domain.com/some-random-page-12345。
观察结果：你应该能看到你刚才设计的绿色风格错误页面，而不是默认的白色文本错误。

总结

在本文中，我们不仅仅是在创建一个网页，更是在学习如何优雅地处理错误。我们一起完成了三件事：

设计：创建了 application/views/error404.php，利用 CSS 将枯燥的错误转变为用户友好的提示。
逻辑：构建了 application/controllers/CustomError404.php，学习了如何正确设置 HTTP 404 状态头以及如何区分 API 和 Web 请求。
配置：通过 application/config/routes.php 将自定义逻辑注入到框架的生命周期中。

此外，我们还探讨了日志记录、API 兼容性以及大小写敏感等实际开发中常见的问题。通过这些步骤，你的 CodeIgniter 应用现在拥有了一个专业级的 404 处理机制，不仅提升了用户体验，也展示了你对细节的把控能力。无论你是构建博客、企业官网还是复杂的 API 系统，这些基础知识都将助你一臂之力。

希望这篇文章对你有所帮助！现在，去为你的网站打造那个独一无二的 404 页面吧！

投稿给我们	如何建站？
vps是什么？	如何安装宝塔？
如何通过博客赚钱？	便宜wordpress托管方案
免费wordpress主题	这些都是免费方案

豆丁博客