CodeIgniter 4官方已弃用ZIP包手动安装，必须用composer create-project codeigniter4/appstarter初始化完整项目结构，否则因缺失autoloader、.env、spark等导致Class not found、路由失效、空白页等错误。
CodeIgniter 官方已明确弃用 ZIP 包手动安装方式，传统部署（解压、复制、改配置）不再受支持，且极易引发 Class not found、路由失效、空白页等运行时错误。如果你手头只有 ZIP 包或旧项目结构，必须按现代标准重走初始化流程——即通过 Composer 创建完整项目结构，否则后续调试成本远高于初期调整。
为什么不能直接解压 ZIP 部署？
CI4 自 4.5 版起强制要求 PHP ≥ 8.1，并依赖 Composer 自动生成的 autoloader、服务容器注册、环境感知加载机制。手动解压缺失 vendor/autoload.php、未执行 post-autoload-dump、未生成 .env 文件及 spark 命令入口，导致：
- 控制器类无法被自动加载（Class 'App\Controllers\Home' not found）
- 数据库迁移命令 php spark migrate 失效
- 开发模式（development）无法启用，错误不显示
- URL 路由始终 fallback 到 404
正确替代路径：零配置启动本地开发环境
无需 Apache/Nginx，不用改 httpd.conf 或 .htaccess，一条命令即可跑通：
- 确保终端中 php -v 输出 ≥ 8.1，composer -V 输出 ≥ 2.2，且已启用 mbstring 和 curl 扩展
- 执行：
composer create-project codeigniter4/appstarter myapp --prefer-dist --no-interaction - 进入项目目录：
cd myapp - 复制并编辑 .env：
cp env .env && sed -i 's/# CI_ENVIRONMENT = development/CI_ENVIRONMENT = development/' .env（Linux/macOS）或手动打开 .env 取消注释并设为 development - 启动内置服务器：
php spark serve，访问 https://www.php.cn/link/cbb686245ece57c9827c4bc0d0654a8e 即可见欢迎页
若必须迁移旧 PHP 页面进 CI4 结构
不是“把 CI4 放进你的网站”，而是“把你的逻辑重构进 CI4 的 MVC 约定”：
- 原 index.php → 移入
app/Controllers/Home.php，继承 BaseController，方法命名为 index() - 原 HTML 内容 → 提取为
app/Views/home/index.php，用 = $title ?? 'Welcome' ?> 接收控制器传参 - 原数据库查询 → 封装进
app/Models/UserModel.php，使用 Query Builder 或 Entities - 所有静态资源（CSS/JS/images）统一放
public/目录，通过base_url('css/app.css')引用
常见卡点与直给解法
遇到问题别猜，按顺序检查这五项：
- .env 文件是否在项目根目录？是否取消了 CI_ENVIRONMENT 行注释？
- public/.htaccess 是否存在且内容来自 appstarter 默认版本？（Apache 必须开启 mod_rewrite）
-
baseURL 是否配置正确？ 在 .env 中设
app.baseURL = "https://www.php.cn/link/cbb686245ece57c9827c4bc0d0654a8e/"（末尾带斜杠） -
数据库连接失败？ 检查 .env 中
database.default.hostname、username、password是否填对，且 MySQL 服务正在运行 -
页面空白无报错？ 查看 PHP 错误日志（
php -i | grep error_log），或临时在 public/index.php 开头加ini_set('display_errors', 1); error_reporting(E_ALL);
