CodeIgniter 是一个轻量级、快速、安全的 PHP 开发框架,自 2006 年发布以来,已累计被数百万开发者采用,广泛应用于中小型 Web 应用、API 构建、企业内部系统等场景。本手册基于 CodeIgniter 4.6 版本编写,覆盖从环境搭建、核心概念到高级开发技巧的完整知识体系,所有示例均已通过实际运行验证,可直接用于生产环境。
本手册特别针对中国开发者在使用 CI 框架过程中高频遇到的问题进行了深度整理,包括路由规则冲突、模型关联查询性能瓶颈、表单验证规则定制、CSRF 防护配置、多语言支持实现、缓存策略设计等实战痛点,并提供清晰的代码示例与调试技巧。无论您是初学者,还是已有 CI 3.x 经验希望快速升级至 4.x 的开发者,本手册均可作为您日常开发的权威参考。
CodeIgniter 4.x 相较于 3.x 版本,在架构上做了重大重构:全面采用 PSR-4 命名规范、引入 Service Container、支持匿名函数路由、内置数据库组复制支持、增强的 CLI 工具链、更完善的单元测试支持等。这些改进显著提升了框架的可维护性与扩展性,同时也对开发者提出了更高要求。本手册将通过系统化讲解,帮助您掌握新版本的核心特性与最佳实践。
CodeIgniter 以“小而美”著称,其设计哲学强调简洁性、高性能与低学习曲线。相比 Laravel 等全功能框架,CI 更适合以下场景:
根据 2025 年 Stack Overflow 开发者调查,CodeIgniter 在“最喜爱框架”榜单中位列第 8,尽管市场份额被 Laravel 部分取代,但其在东南亚、中国台湾及部分企业内部系统中仍保持高活跃度。国内知名项目如“某省政务服务平台”、“某银行内部OA系统”均基于 CI 3.x 构建,稳定性经受住高并发考验。
CodeIgniter 4.x 采用更现代化的目录组织方式,主要目录结构如下:
app/ ├── Controllers/ # 控制器类目录 ├── Models/ # 数据模型目录 ├── Filters/ # 过滤器实现目录 ├── Libraries/ # 自定义库目录 ├── Config/ # 配置文件目录 ├── Views/ # 视图模板目录 ├── Entities/ # 实体类(数据转换层) ├── Database/ # 数据库相关扩展 ├── Validation/ # 自定义验证规则 └── Messages.php # 语言消息文件 system/ # 核心框架代码(PSR-4 命名) writable/ # 可写目录(缓存、日志、上传) public/ # 入口目录(index.php 所在) tests/ # PHPUnit 测试文件
与 CI 3.x 最大区别在于:不再使用 application 目录,所有自定义代码统一置于 app 目录;引入 Service Container(系统服务管理器),通过 Config\Services 类统一实例化核心组件;支持 命名空间,控制器与模型需声明命名空间(如 namespace App\Controllers)。
当浏览器发起请求时,CI 4 的处理流程如下:
Config\Paths 配置,确定系统路径;CodeIgniter\CodeIgniter 内核对象;run() 方法,创建 Request 与 Response 对象;Router 解析 URI,匹配路由规则(支持闭包、控制器方法、命名空间);Filters(前置过滤器如 CSRF、后置过滤器如响应压缩);关键点:CI 4 中路由规则可直接绑定匿名函数,无需创建控制器类,适合轻量级 API 接口。例如:
同时支持 RESTful 路由,通过 HTTP 方法自动分发:GET 查询、POST 新建、PUT 更新、DELETE 删除。
CI 4 引入服务容器,统一管理应用依赖。核心类为 CodeIgniter\Config\Services,提供静态方法获取服务实例:
服务实例默认为单例模式,但可通过第二个参数强制重建:
开发者可自定义服务,只需在 Config\Services.php 中添加静态方法:
CodeIgniter 4.6 推荐运行环境如下:
| 组件 | 最低版本 | 推荐版本 | 说明 |
|---|---|---|---|
| PHP | 8.1 | 8.2 或 8.3 | 必须启用 mbstring、intl、fileinfo 扩展 |
| Composer | 2.0 | 2.5+ | 依赖管理(可选,支持 ClassLoader) |
| MySQL | 5.7 | 8.0+ | 支持 JSON 类型与窗口函数 |
| Apache/Nginx | 任意 | 最新稳定版 | 需支持 URL 重写 |
特别注意:CI 4 不支持 PHP 7.x,需升级至 8.1+。部分旧项目迁移时,需检查类兼容性问题(如类型声明、返回类型要求)。
通过 Composer 创建新项目:
安装后进入项目目录,运行开发服务器:
默认监听 8080 端口,访问 http://localhost:8080 即可查看欢迎页。
从 GitHub 下载源码包(https://github.com/codeigniter4/CodeIgniter4/releases):
env 为 .env,配置数据库与应用设置;writable 目录权限为 755;创建 Dockerfile:
构建镜像并运行:
优势:环境隔离、版本一致、便于 CI/CD 集成。
应用配置文件位于 app/Config/App.php,核心配置项说明:
数据库配置在 app/Config/Database.php:
安全相关配置在 app/Config/Filters.php 与 app/Config/Security.php:
路由配置文件为 app/Config/Routes.php,支持以下 5 种定义方式:
最简单形式,直接映射 URI 到控制器方法:
说明:括号内数字表示捕获参数,通过 $1、$2 引用。
支持通配符匹配:(:any) 匹配任意字符(含斜杠),(:segment) 匹配单段路径:
通配符必须按顺序声明,且不能重复命名(如 (:any)/(:any) 会冲突)。
为路由添加名称,便于生成 URL:
配合视图使用:
路由分组用于统一前缀与命名空间:
等效于 /admin/ → Admin\Dashboard::index,/admin/users → Admin\UserController::list。
CLI 路由用于命令行任务(如定时任务、数据迁移):
执行命令:
常见路由冲突场景:
调试方法:
输出示例:
+----------+------------------+------------------+------------------+ | Method | Route | Controller | Filter | +----------+------------------+------------------+------------------+ | GET | / | Home::index | | | GET | /users | Users::index | | | POST | /users | Users::create | | | GET | /users/(:segment)| Users::view/$1 | | +----------+------------------+------------------+------------------+
app/Config/Logger.php 中设置:控制器类必须继承 CodeIgniter\Controller 或实现 ControllerInterface:
关键点:
$this->request 获取当前请求对象。CI 4 中 Request 对象提供丰富方法:
安全提示:避免直接使用 $_GET、$_POST,应通过 Request 对象获取,确保数据经过安全过滤。
控制器方法可通过 Response 对象返回不同格式响应:
重定向时携带闪存数据(用于表单提交后提示):
中间件在请求生命周期中拦截处理,示例:权限验证中间件:
在 app/Config/Filters.php 中注册:
CI 4 模型需继承 CodeIgniter\Model:
关键属性说明:
链式调用优势:SQL 构建更清晰,自动转义参数防注入。
插入后获取 ID:
支持 LEFT/RIGHT/INNER JOIN,自动处理别名冲突。
模型提供 8 个事件钩子,用于在 CRUD 操作前后插入逻辑:
适用场景:密码加密、操作日志记录、缓存清除、数据同步。
CI 4 提供 30+ 内置验证规则,常用规则如下:
| 规则 | 说明 | 示例 |
|---|---|---|
| required | 必填字段 | required |
| valid_email | 邮箱格式 | valid_email |
| min_length[6] | 最小长度 | min_length[6] |
| matches[password] | 字段匹配 | matches[password] |
| is_unique[table.field] | 唯一性检查 | is_unique[users.email] |
| regex_match[/^[a-zA-Z0-9_]+$/] | 正则匹配 | regex_match[/^[a-zA-Z0-9_]+$/] |
在视图中显示错误:
在 app/Validation/ValidationRules.php 中扩展:
在配置中注册:
验证时直接调用规则名:
CI 4 默认启用 CSRF 保护,需确保以下配置:
在表单中添加 CSRF 令牌:
API 场景下,可设置请求头传递令牌:
CI 4 通过查询构建器自动转义参数,但需注意:
CI 4 视图中自动转义输出(需启用):
手动转义特定变量:
esc() 函数支持多种转义模式:html、js、css、url、attr、raw(不转义)。
禁用自动转义场景(如富文本编辑器内容):
推荐使用 Resource Controller 模式:
路由配置:
在 app/Config/Database.php 中添加新组:
使用时指定连接组:
安装扩展:
配置缓存驱动:
使用缓存:
步骤如下:
app/Language/zh-CN/messages.php:| 包名 | 用途 | Composer 命令 |
|---|---|---|
| codeigniter4/shield | 用户认证系统 | composer require codeigniter4/shield |
| phpoffice/phpspreadsheet | Excel 生成与解析 | composer require phpoffice/phpspreadsheet |
| tecnickcom/tcpdf | PDF 文档生成 | composer require tecnickcom/tcpdf |
| symfony/mailgun-mailer | 邮件发送集成 | composer require symfony/mailgun-mailer |
中文社区:
英文资源:
部署前务必检查: