CakePHP 项目创建失败？先别急着反复重试
用 composer create-project 命令创建标准 CakePHP 项目，听起来简单直接。但新手常会遇到一个尴尬情况：默认命令拉下来的未必是最新稳定版，更棘手的是，安装过程很容易因为 PHP 版本或扩展缺失而卡壳失败。
为什么 composer create-project cakephp/app 有时会失败
是不是遇到过这样的场景？命令执行后，进度条卡在 Installing dependencies 一动不动，或者直接抛出一串错误，比如 ext-intl not installed 或 php >= 8.1.0 required。问题根源很明确：CakePHP 5.x 系列要求 PHP 版本必须在 8.1 以上，而不少本地开发环境还停留在 PHP 7.4 或 8.0。此外，intl、mbstring、xml 这三个 PHP 扩展是硬性要求，缺一不可。尤其是 intl 扩展，在 macOS 或某些 Linux 发行版中默认并未启用。
- 确认 PHP 版本：先执行
php -v看一眼。如果版本低于 8.1，就别硬着头皮尝试安装 CakePHP 5 了。 - 检查必备扩展：运行
php -m | grep -E "intl|mbstring|xml"，看看输出里是否齐全。少了哪个就安装哪个，例如在 Ubuntu 上，安装 intl 扩展只需sudo apt install php-intl。 - 快速验证的备选方案：如果只是想快速搭建环境进行验证，可以考虑创建 CakePHP 4.4（这是一个长期支持版本），命令是
composer create-project cakephp/app:^4.4。
create-project 的关键参数怎么选
直接运行 composer create-project cakephp/app 这个默认命令，它会安装最新的稳定版（目前是 5.x）。但这里有个小坑：如果你没指定目录名，Composer 会自动创建一个名为 app 的文件夹，这很容易和项目内部的子模块名称混淆。更稳妥的做法是，显式地指定项目目录并约束版本。
- 指定项目目录：
composer create-project cakephp/app my_cake_app - 锁定 CakePHP 4.4 LTS 版本：
composer create-project cakephp/app:^4.4 my_cake_app - 跳过开发依赖（生产环境推荐）：加上
--no-dev参数，例如：composer create-project cakephp/app:^4.4 my_cake_app --no-dev - 网络不佳时的加速技巧：如果下载速度慢，可以添加
--prefer-dist参数，强制 Composer 下载压缩包而不是进行完整的 Git 克隆。
创建后必须立刻做的三件事
项目骨架生成成功，这仅仅是第一步。如果不进行必要的配置，应用根本跑不起来。其中，数据库配置和文件权限问题是最容易被忽略的两个环节。
立即学习“PHP免费学习笔记（深入）”；
- 修改数据库配置：打开
config/app_local.php文件，填好'host'、'username'、'password'和'database'等关键信息。注意，别只修改app.php，因为它的配置会被app_local.php覆盖。 - 确保临时和日志目录可写：执行
chmod -R 777 tmp logs命令，为tmp/和logs/目录赋予写权限（这在开发环境下通常够用；生产环境则应设置为仅 Web 运行用户可写）。 - 运行数据库迁移前先检查连接：在执行
bin/cake.php migrations migrate之前，不妨先运行bin/cake.php database_cli来测试数据库连接。这个命令能更早地暴露配置错误，避免在迁移中途失败。
说到底，真正的麻烦往往不在创建项目这个动作本身，而在于项目创建后，运行 bin/cake.php server 启动不了，或者访问首页就报 Missing Datasource config 错误。这些问题，其实都不是 Composer 的锅，而是本地环境与 CakePHP 框架的运行要求没有对齐。多花两分钟，通过 phpinfo() 仔细核对一下扩展列表，远比反复重装项目要高效得多。
CakePHP 项目创建失败主因是PHP版本低于8.1或缺失intl、mbstring、xml扩展；应先验证环境，再用composer create-project cakephp/app:^4.4 my_cake_app --no-dev指定版本与目录并跳过dev依赖。
