最稳妥的CakePHP安装方式是composer create-project，它自动拉取完整骨架、安装依赖并生成必要目录结构；手动require核心包会导致缺失关键文件而无法运行。
用 composer create-project 安装 CakePHP 最新版
直接运行 composer create-project 是最稳妥的初始化方式，它会自动拉取完整骨架、安装依赖、生成必要目录结构，避免手动复制或漏配。不建议用 composer require cakephp/cakephp 往空项目里硬塞核心包——那样缺 src/、templates/、bin/cake.php 等关键文件，后续跑不起来。
执行以下命令（以 CakePHP 5.x 为例）：
composer create-project --prefer-dist cakephp/app my_cake_app
说明：
-
--prefer-dist强制走压缩包安装，比 clone git 仓库快且干净 -
cakephp/app是官方维护的全功能应用模板，含 ORM、缓存、邮件等预配置 -
my_cake_app是项目目录名，可按需修改 - 若需指定版本（如固定用 4.4 LTS），加
@4.4：cakephp/app@4.4
安装后必须立即执行的三件事
新项目不是 composer install 完就完事了。以下操作漏掉任一环节，访问首页大概率报错或显示空白页：
立即学习“PHP免费学习笔记（深入）”；
- 设置
APP_NAME和SECURITY_SALT：编辑config/app_local.php，确保'salt' => env('SECURITY_SALT', '...')对应的环境变量已设（或直接填入 32 位随机字符串） - 生成数据库配置：复制
config/app_local.php.default为config/app_local.php，并填入'Datasources' => ['default' => [...]]中的 host/user/password/database - 设好 webroot 权限：Web 服务器（如 nginx/Apache）必须以
webroot/为文档根目录，不能指向项目根；否则index.php不被路由，CSS/JS 404，调试工具栏也不加载
常见报错与对应修复点
安装后访问 http://localhost 报错？先看错误类型再动手：
-
Parse error: syntax error, unexpected token "string"→ PHP 版本太低。CakePHP 5 要求 PHP 8.1+，CakePHP 4.4 最低需 PHP 7.4。用php -v确认，别信系统包管理器默认装的旧版 -
Class 'Cake\Http\ServerRequestFactory' not found→vendor/autoload.php没被正确引入。检查webroot/index.php开头是否包含require dirname(dirname(__FILE__)) . '/vendor/autoload.php'; - 空白页无报错但调试栏不显示 → 关闭了调试模式。确认
config/app_local.php中'debug' => filter_var(env('DEBUG', true), FILTER_VALIDATE_BOOLEAN)的环境变量DEBUG=1已生效（可通过echo getenv('DEBUG');测试）
部署到生产环境前的关键清理
开发时 debug = true 没问题，但上线必须关掉调试并清缓存，否则暴露路径、SQL、敏感配置：
- 设置环境变量
DEBUG=0（不要改代码里的debug => true，用环境变量控制） - 删掉
tmp/cache/models/和tmp/cache/persistent/下所有文件（或运行bin/cake cache clear_all） - 确认
APP_NAME和SECURITY_SALT在生产环境有独立值，绝不能和开发环境共用 - 禁用
debug_kit插件：从config/bootstrap.php中注释或删除Plugin::load('DebugKit')行
权限和路径问题在部署时高频出现，尤其当运维用 rsync 同步、没保留 tmp/ 目录的写权限，或 webroot 没设对——这些细节比框架语法更常卡住上线节奏。
