CodeIgniter安装步骤详解

CodeIgniter 4 的安装绝非简单下载或引入即可，其核心机制深度绑定于严格的目录结构与预设配置，唯有通过 `composer create-project codeigniter4/appstarter` 这一官方唯一支持的方式才能正确初始化——任何手动解压、`composer require framework` 或 `git clone` 都将导致 `Class 'CodeIgniter\CodeIgniter' not found`、`spark` 命令失效、数据库静默失败等致命问题；本文直击安装痛点，详解环境准备、镜像加速、权限配置、`.env` 与 `App.php` 关键设置及常见启动故障排查，帮你避开90%新手踩坑雷区，一步到位跑通首个 CI4 应用。

CodeIgniter 4 必须用 composer create-project codeigniter4/appstarter 安装，其他方式基本会失败——不是“能不能跑”，而是 spark 命令不可用、Class 'CodeIgniter\CodeIgniter' not found、数据库静默连不上这些核心问题会立刻出现。

为什么 composer require codeigniter4/framework 一定不行

CI4 不是一个能“require 进来”的库，而是一个强依赖固定目录结构的应用骨架。只拉 codeigniter4/framework 包，项目里就没有 public/ 入口、没有 app/Config/、没有 writable/ 目录，public/index.php 第一行就找不到 ../vendor/autoload.php，直接报错。

• appstarter 是唯一受支持的初始化模板，含完整路由、.env.example、spark CLI 脚本和预设权限结构
• framework 包仅用于已有 CI4 项目升级内核，不能新建项目
• 手动解压 ZIP 或复制 vendor 文件夹，会导致自动加载路径断裂，$db = \Config\Database::connect() 会静默返回 null

composer create-project 执行时必须注意的三件事

命令本身简单，但环境不对或路径错一步，后续全卡住：

• 当前终端目录必须是空文件夹（不是 htdocs 下某个子目录，更不能是已存在的项目根）
• 执行前确认 PHP 版本 ≥ 8.1（CI4.5+ 已弃用 7.4），且启用了 mbstring、intl、curl 扩展（php -m | grep -E "mbstring|intl"）
• 国内用户务必先配阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，否则大概率超时或卡在 installing dependencies

php spark serve 启动失败的常见原因

安装完进目录跑 php spark serve，看到 Welcome 页面才算通。如果报错，优先检查这几处：

• 是否在项目根目录执行？不是 public/，也不是 app/ —— 必须是含 spark 文件和 vendor/ 的那一层
• public/index.php 第 14 行左右是否为 require FCPATH . '../vendor/autoload.php';？如果项目被放进子路径（如 /var/www/html/myapp/），这个相对路径必须真实存在
• .env 文件是否重命名正确（不是 env 或 .env.example）、权限是否可读（Apache/Nginx 用户需有读权限，上传后属主是 root 就读不了）
• 改过 .env 后有没有重启服务？.env 只在启动时加载一次，改了不重启等于没改

.env 和 app/Config/App.php 必须改的配置项

这两处不调，页面可能显示，但功能残缺：

• .env 中必须取消注释并设值：CI_ENVIRONMENT = development（上线前切 production），database.default.hostname、database.default.username、database.default.password、database.default.database 不能为空
• SQLite 用户注意：路径必须写绝对路径，比如 database.default.database = /var/www/myproject/writable/database.db，相对路径在 CLI 模式下极大概率找不到
• app/Config/App.php 中的 $baseURL 必须设为实际访问地址，例如 http://localhost:8080/ 或 https://myapp.test/；若通过子目录访问（如 http://localhost/ci4/），就得写成 http://localhost/ci4/，否则 CSRF token、asset 链接、重定向全部失效

最常被跳过的其实是 writable/ 目录权限和 .env 的属主问题——Web 服务器用户（如 www-data）没权限写日志、缓存、session，所有后台逻辑都会静默失败，查日志都看不到错误。别等出问题才回头翻。

到这里，我们也就讲完了《CodeIgniter安装步骤详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于CodeIgniter的知识点！