CodeIgniter 4 要跑起来，必须满足 PHP ≥ 8.1、启用 mbstring/curl/json/xml/zip 扩展、确保 .env 文件为 UTF-8 无 BOM 且换行符为 LF、设置 CI_ENVIRONMENT = development、Web 服务器根目录指向 public/ 并启用 mod_rewrite 或配置 Nginx 重写规则。
CodeIgniter 4 要跑起来，不是装完 composer create-project codeigniter4/appstarter 就完事的——80% 的人卡在环境配置这一步，尤其是 PHP 版本、扩展和时区设置上。
PHP 版本与扩展必须匹配 CI4 最低要求
CI4.5+ 已正式放弃对 PHP 7.x 的支持，最低要求是 PHP 8.1。用 php -v 检查后如果显示 8.0 或更低，直接报错：「Your PHP version is too old」。
必须启用的扩展有：mbstring、curl、json、xml、zip（用于 spark 命令行工具）。Windows 用户常漏掉 php_mbstring.dll 和 php_opcache.dll，需在 php.ini 中取消注释这两行：
extension=mbstring extension=opcache
Linux/macOS 用户可通过 php -m | grep -E "mbstring|curl|json" 快速验证。
.env 文件权限与内容格式极易出错
CI4 启动时会尝试读取项目根目录下的 .env 文件，但如果你用 Windows 记事本保存过它，极大概率混入 BOM 头或 DOS 换行符（\r\n），导致 DotEnv::load() 解析失败，报错信息为：ParseError: syntax error, unexpected '='。
正确做法：
- 用 VS Code、Notepad++ 或 Sublime Text 打开，编码选
UTF-8 without BOM - 换行符统一设为
LF（Unix 风格） -
APP_ENV和CI_ENVIRONMENT必须一致，推荐都设为development - 数据库密码含特殊字符（如
@、/、:）时，整个值要用单引号包裹：database.default.password = 'p@ss/w0rd'
Apache/Nginx 配置不兼容会导致路由 404
CI4 默认关闭 index.php 入口文件，靠重写规则把请求转给它。但 Apache 的 .htaccess 在某些主机或 WAMP/XAMPP 环境下被禁用；Nginx 则根本没默认重写逻辑。
Apache 用户检查：httpd.conf 中是否启用了 mod_rewrite，且 AllowOverride All 已应用到项目目录；否则所有非首页请求都会 404。
Nginx 用户必须手动加这段配置到 server 块内：
location / {
try_files $uri $uri/ /index.php?$query_string;
}
注意：$query_string 不能写成 $args，否则 POST 数据丢失；也不能漏掉末尾分号。
spark 命令无法执行的三个隐藏原因
php spark 是 CI4 的核心 CLI 工具，但很多人执行时报错：Class 'CodeIgniter\CLI\CommandRunner' not found 或直接提示「command not found」。
常见原因：
- 当前目录不是 CI4 项目根目录（即没有
spark文件和app/目录） - PHP CLI 使用的是系统默认版本（如 7.4），而非你配好的 8.1+；用
which php和php -v分别确认 -
vendor/codeigniter4/framework下的src/CLI/类路径未被自动加载——运行一次composer dump-autoload -o可修复
真正容易被忽略的是：Windows 用户若用 Git Bash 运行 php spark，可能因路径解析异常失败，建议改用 PowerShell 或 CMD。
