CodeIgniter 4 必须通过 composer create-project codeigniter4/appstarter 安装，不可手动解压或 git clone；需匹配 PHP 版本（CI4.7.0 要求 ≥8.1），并验证 mbstring 等扩展、关闭 track_errors、设 .env 为 development、用 php spark serve 启动。
CodeIgniter 不是“随便下个 ZIP 就能跑”的框架，尤其 CI4 系统对安装方式、PHP 版本和依赖配置有明确硬性要求。选错来源或版本，轻则报 Class not found，重则整个项目无法启动。关键不是“哪个最新”，而是“哪个适配你的环境+开发目标”。
CI3 与 CI4：本质区别决定起点
CI3（如 3.1.9）适合维护老项目、低配服务器（PHP 5.6+）、或需要快速上手不碰 Composer 的场景；它结构扁平、文档成熟、无需自动加载配置，直接解压改 base_url 就能跑。CI4（当前稳定版是 4.7.0）则是现代 PHP 开发路线：强制 PSR-4 自动加载、模块化目录、内置 Spark 命令行工具、支持 PHP 8.2/8.3，但必须用 composer create-project 安装，禁用手动下载或 git clone。
官方唯一推荐的 CI4 来源：appstarter 模板
CI4 核心框架（codeigniter4/framework）不带应用骨架，不能直接运行。官方唯一支持且预配置完整的起点是：codeigniter4/appstarter。它已包含 .env、routes、基础控制器、Spark 集成和开发环境默认配置。其他 GitHub 分支、ZIP 包、第三方镜像站打包版均非官方维护，易缺失 autoloader 或路由注册逻辑。
- 正确命令：
composer create-project codeigniter4/appstarter myapp --prefer-dist --no-interaction - 执行前确认当前目录为空，且不在已有 composer 项目内
- 不要用
git clone后自己 composer install —— 会跳过 appstarter 的 post-create-project-cmd 脚本，导致 .env 未生成、key 未生成、目录权限未初始化
版本选择：看 PHP 和开发阶段
截至 2026 年 8 月，CI4.7.0 是最新稳定版，要求 PHP ≥ 8.1；若你本地是 PHP 8.0，应降级使用 CI4.6.1（官方明确兼容 PHP 8.0）；若还在用 PHP 7.4，只能退回 CI3 系列（如 3.1.13），CI4 全系已不再支持 PHP 7.x。
- 新项目开发：直接选 CI4.7.0 + PHP 8.2（推荐）
- 团队协作或 CI/CD 环境：用项目级 Composer 镜像配置，避免全局设置冲突
- 教学或演示用途：CI4.6.1 更稳妥，文档覆盖全，异常提示更友好
避坑重点：三个“必须做”和一个“必须删”
很多失败不是因为不会写代码，而是卡在环境准备环节：
-
必须验证 PHP 扩展：mbstring、curl、xml、zip 缺一不可，用
php -m | grep -E "mbstring|curl|xml|zip"检查 - 必须删掉 php.ini 中的 track_errors = On：它会让 Composer 在写 lock 文件时静默失败，无任何提示
-
必须设 .env 为 development：安装后打开
myapp/.env，把CI_ENVIRONMENT = production改成development，否则错误不显示 - 必须用 php spark serve 启动：不要直接放 Apache 目录下访问 —— CI4 默认路由和重写规则依赖 Spark 内置服务器，Apache/Nginx 需额外配置才可用
