CodeIgniter 4 必须通过 composer create-project codeigniter4/appstarter 安装，因框架强依赖固定目录结构（如 public/、app/、writable/）和硬编码路径，手动解压ZIP、composer require codeigniter4/framework 或 git clone 均会导致 Class 'CodeIgniter\CodeIgniter' not found、spark 失效、数据库静默失败等核心问题。
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、sparkCLI 脚本和预设权限结构 -
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，所有后台逻辑都会静默失败，查日志都看不到错误。别等出问题才回头翻。
