最稳方式是用 composer create-project 安装 CakePHP，它自动处理依赖、vendor、配置和权限；需 PHP ≥ 8.1，注意镜像源、ROOT 路径、APP_NAME 命名空间一致性、bin/cake 可执行性及升级时同步更新所有 cakephp/* 包。
直接用 composer create-project 装 CakePHP 最稳
别去手动下载 ZIP 或 clone 仓库再折腾 autoload，create-project 是官方唯一推荐方式，它会自动处理依赖、生成 vendor、初始化配置和权限检查。你只需要确保 Composer 已全局可用且 PHP 版本 ≥ 8.1（CakePHP 5.x 要求）。
常见错误现象：Could not find package cakephp/app —— 大概率是镜像源失效或网络被干扰；Permission denied: vendor/bin/cake —— Windows 下没开执行权限，Linux/macOS 下没给 chmod +x。
- 运行命令：
composer create-project cakephp/app my_app_name（my_app_name替换为你想要的目录名） - 加
--prefer-dist强制走压缩包，比--prefer-source快且干净 - 如果国内访问慢，先切镜像：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（注意：该镜像已停，建议改用阿里云：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/）
装完跑不起来？重点检查 APP_NAME 和 ROOT 路径
CakePHP 启动时依赖两个硬编码路径常量：ROOT 指向项目根目录（含 src/、config/），APP_NAME 必须与 src/Application.php 类名一致。很多“白屏”或 Class 'App\Application' not found 错误都源于此。
使用场景：你重命名了项目目录、复制了别人代码、或用 IDE 自动重构过命名空间但漏改常量。
立即学习“PHP免费学习笔记（深入）”；
- 确认
webroot/index.php开头的define('ROOT', dirname(__DIR__));指向正确（即上一级是项目根，不是webroot自身） - 检查
src/Application.php的命名空间是否为App，类名是否为Application，且文件名大小写完全匹配（Linux 下敏感） -
APP_NAME默认是'App'，除非你改过config/app_local.php里的'app' => ['namespace' => 'MyApp']，那就要同步改类名和命名空间
cake bake 命令报错？先确认 bin/cake 可执行且 PHP 解析正常
cake bake 不是独立二进制，而是 bin/cake 这个 PHP 脚本。它失败通常不是 Bake 插件问题，而是环境链路断了：PHP CLI 版本不对、缺少扩展（如 mbstring、intl）、或脚本头部 #!/usr/bin/env php 在 Windows 下无效。
性能影响：本地开发启用了 debug_kit 插件但没装好，会导致每次请求多加载 20+ 类，cake bake 响应延迟明显。
- 先试
php bin/cake.php（Windows）或php bin/cake（Linux/macOS），看是否输出帮助信息 - 检查
php -m | grep -E 'mbstring|intl|pdo'，缺哪个就装哪个（Ubuntu：sudo apt install php-mbstring php-intl php-pdo） - Mac 上如果用 Homebrew PHP，确保
which php和php -v显示的是同一版本，避免系统自带 PHP 干扰
升级 CakePHP 时别直接 composer update
composer update cakephp/core 看似精准，但 CakePHP 各组件版本强耦合（cakephp/database 必须和 cakephp/core 同主版本），盲目更新单包大概率导致 Call to undefined method 或 ArgumentCountError。
兼容性影响：从 4.x 升 5.x 是重大变更，Authorization 中间件默认行为、FormHelper 渲染逻辑、DatabaseLog 配置结构全变了，光靠 Composer 更新不可能自动适配。
- 升级前必须读对应版本的
UPGRADE.md（在 GitHub 仓库根目录） - 执行
composer update "cakephp/*"（带引号防 shell 展开），确保所有子包同步升 - 升级后立刻跑
php bin/cake.php test，别等上线才发现AuthenticationComponent构造函数参数变了
最常被忽略的是 config/bootstrap.php 里手动 require 的插件路径 —— 升级后如果插件本身没同步更新，这里就会静默失败，日志里只有一行 Plugin not loaded，查半天发现是插件的 bootstrap.php 里用了已被移除的 EventManager 静态方法。
