composer autoload 失败导致类找不到，典型表现为 codeigniter 4 启动时报“class 'codeignitercodeigniter' not found”，主因是 vendor 目录不全、autoload.php 缺失或引入路径错误，需执行 composer install --no-dev --optimize-autoloader 并验证路径。
Composer autoload 失败：类找不到的典型表现
CodeIgniter 4 启动时直接报 Fatal error: Class 'CodeIgniterCodeIgniter' not found，基本就是 Composer 依赖没装全或 autoloader 没生效。这不是框架本身的问题，而是 PHP 找不到核心类的加载路径。
常见诱因包括：
— 运行 composer install 时网络中断，vendor/codeigniter4/framework 目录下缺文件
— 误删了 vendor/autoload.php 或修改了 public/index.php 中的引入路径
— 使用了非标准安装方式（比如手动下载 ZIP 包却没运行 composer dump-autoload）
实操建议：
— 进入项目根目录，执行 composer validate 确认 composer.json 语法合法
— 运行 composer install --no-dev --optimize-autoloader 强制重装生产依赖
— 检查 public/index.php 第 15 行是否仍是 require FCPATH . '../vendor/autoload.php';
服务容器注册失败：$this->session 或 $this->cache 报 null
控制器里调用 $this->session->get() 却提示 “Call to a member function get() on null”，说明对应服务没被自动注入——根本原因是服务未在 app/Config/Services.php 中正确注册或启用。
CodeIgniter 4 的服务是懒加载的，只有在首次访问 $this->xxx 时才触发容器解析。如果配置里关掉了某项服务（比如把 $config['session'] = false;），容器就不会实例化它。
实操建议：
— 打开 app/Config/Services.php，确认对应服务方法（如 session()）没有被注释或返回 null
— 检查 app/Config/Boot/services.php 是否被意外清空（该文件负责加载 Services 类）
— 若自定义了服务别名，确保 public static function alias(): array 里有对应映射，否则 $this->myService 就不会自动绑定
扩展包 require 报错：第三方库无法被识别
执行 composer require codeigniter4/restserver 后，在控制器中 use RESTController 仍报错，大概率是命名空间没对上，或者包没被自动发现。
CodeIgniter 4 默认只扫描 app/ 和 vendor/codeigniter4/framework/ 下的 PSR-4 命名空间。RestServer 这类第三方包需额外声明其命名空间映射，否则 autoloader 不知道去哪找类。
实操建议：
— 查看该包的 composer.json，确认它是否声明了 "psr-4" 映射（如 "chriskacerguis\RestServer\": "src/"）
— 若没有，手动在你项目的 composer.json 的 "autoload" → "psr-4" 下追加对应条目
— 修改后必须运行 composer dump-autoload，不能只靠 composer update
环境变量未加载：.env 文件存在但数据库配置不生效
明明写了 database.default.hostname = localhost 在 .env 里，$this->db 却连到 127.0.0.1 或报连接拒绝，说明环境变量压根没被读取——最常被忽略的是 .env 文件权限或位置错误。
CI4 只在入口文件 public/index.php 开头通过 DotEnv::createImmutable() 加载一次，且严格要求：
— 文件必须叫 .env（不能是 .env.example 或 env）
— 必须放在项目根目录（和 app/、public/ 同级）
— 不能被 web 服务器禁止访问（Apache 需确认 AllowOverride All 已启用）
实操建议：
— 运行 php spark env，看输出是否列出你设的变量值
— 如果为空，检查 public/index.php 第 12–14 行是否被注释或删改
— Linux 下注意 .env 文件权限不能是 600（web 用户读不了），建议设为 644
