必须用composer create-project安装CodeIgniter4，禁用手动下载或git clone；需PHP≥8.1、Composer≥2.2，配置阿里云镜像，使用appstarter模板，设置.env为development环境并运行php spark serve启动。
要在本地快速搭建一个可运行的CodeIgniter4开发环境，必须避开手动下载ZIP包或git clone框架核心这种错误路径——官方已明确不支持、不维护此类安装方式，直接导致Class not found、路由加载失败、autoloader缺失等不可逆问题。
确认PHP与Composer版本前提
CI4.5起强制要求PHP ≥ 8.1，CI4.6.1稳定版推荐PHP 8.2或8.3；Composer必须≥2.2（CI4.4+硬性要求）。在终端执行php -v和composer -V验证，低于则先升级。
缺mbstring、curl、xml、zip扩展会导致create-project中途报错退出，用php -m检查，Windows下在php.ini中取消对应extension前的分号，Linux用apt install php-mbstring等补全。
【PHP track_errors = On必须从php.ini中彻底删除】否则Composer安装过程会在“Writing lock file”阶段静默失败，且无明确报错提示。
配置阿里云Composer中文镜像
方法一：全局配置（仅限个人开发机）
执行完整命令：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。注意三要素缺一不可：repo.packagist（不能多s）、type为composer、URL末尾带/。
方法二：项目级配置（推荐，尤其宝塔、Docker、CI/CD环境）
新建空目录→cd进去→执行composer init -n生成空composer.json→再运行composer config repo.packagist composer https://mirrors.aliyun.com/composer/。该方式写入当前目录composer.json的repositories字段，完全规避用户权限与配置文件路径错位问题。
验证是否生效：运行composer config -g repo.packagist，输出必须是{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。若为null或显示packagist.org地址，说明配置失败，需重跑带type的完整命令。
执行create-project安装稳定版
第一步：进入你计划存放项目的父目录，例如D:\www或/home/user/www
第二步：运行命令 → composer create-project codeigniter4/appstarter myapp --prefer-dist --no-interaction
其中myapp是你的项目文件夹名，可任意替换；--prefer-dist跳过源码克隆加速安装，--no-interaction避免交互式提问。
第三步：等待完成，终端出现“Created project in myapp”即成功。此时目录结构已完整生成：writable/有写权限、public/为Web入口、.env.example已就位、vendor/autoload.php自动构建完毕。
这一步操作起来很简单，但必须用appstarter模板，不能用codeigniter4/framework——后者只是框架库，不包含路由、CLI、基础控制器等运行必需组件，装完无法启动。
启用开发环境并启动服务
进入项目根目录：cd myapp
复制环境配置文件：copy .env.example .env（Windows）或cp .env.example .env（macOS/Linux）
编辑.env文件，修改三处关键项：
① 取消注释并设app.baseURL = "http://localhost:8080"（与后续spark serve端口一致）
② 设CI_ENVIRONMENT = development（不改则全程静默错误、日志不写、调试器失效）
③ 若暂不连库，database.default.hostname等字段可留空，但不能删除整行或注释掉
启动内置服务器：php spark serve。服务监听http://localhost:8080，页面显示“Welcome to CodeIgniter4”即安装完成。
