Laravel Octane 需先确保 PHP ≥ 8.2、必需扩展（如 swoole 或 RoadRunner 依赖）齐全且版本兼容，再运行 octane:install 生成配置，正确设置 driver 并验证终端启动日志，同时保证 APP_KEY 生成和 storage 权限正确。
Octane 不是“装上就快”，得先确认 PHP 环境撑不撑得住
直接 composer require laravel/octane 肯定能跑通，但装完启动就报错——这是最常踩的坑。Laravel Octane 本质是让 Laravel 进程常驻内存，它不兼容传统 FPM 模式下的 PHP 扩展缺失或版本错配。
- PHP 必须 ≥ 8.2（Laravel 11+ 强制要求），
php -v先看清楚 - 必需扩展：除了常规的
mbstring、openssl、pdo，Swoole 还要swoole扩展（php --ri swoole验证），RoadRunner 则依赖系统有curl和可执行权限的 Go 环境（Octane 会自动下载.rr二进制，但没chmod +x权限就卡住） - Windows 用户注意：
ext-zip很容易被 XAMPP/MAMP 关闭，php -m | grep zip为空就手动开 php.ini 里的extension=zip
安装命令本身很简单，但 octane:install 这步决定后续能不能热重载
很多人装完 laravel/octane 就急着 php artisan octane:start，结果改代码没反应——因为没生成监听配置。真正启用热重载（--watch）的前提，是运行过 php artisan octane:install。
- 该命令会生成
config/octane.php和默认的.rr.yaml（RoadRunner）或swoole.config.php（Swoole） - 如果不运行这步，
--watch参数会被忽略，进程不会监听文件变更 - 国内网络下，
php artisan octane:install --server=roadrunner可能卡在下载rr二进制，可提前手动下载放项目根目录并chmod +x rr，再重试
driver 配置写错，启动时根本不会报错，只会默默 fallback 到 HTTP 服务
打开 config/octane.php，看到 'driver' => 'swoole' 或 'driver' => 'roadrunner'，你以为生效了？不一定。Octane 启动时只检查扩展是否存在，不校验配置值是否合法。如果填了 'driver' => 'sw00le' 这种拼写错误，它会静默用内置的 HTTP 服务器兜底——性能毫无提升，还让你误以为“已经跑了 Octane”。
- 验证方式：启动后看终端输出第一行，应含
Starting Swoole Server...或Starting RoadRunner Server...，否则就是 driver 没生效 - Swoole 用户注意：
pecl install swoole安装的是最新版，但 Laravel Octane 1.5+ 要求 Swoole ≥ 5.1.1；低于此版本会导致OctaneServiceProvider初始化失败，却只报 “Class not found”，实际是扩展 API 不兼容 - RoadRunner 用户注意：
.rr.yaml中的http.address默认是0.0.0.0:8000，若本地已占，得手动改，否则启动成功但连不上
别忘了 APP_KEY 和 storage 权限，否则欢迎页面都出不来
这是新手最容易忽略的“非 Octane 问题”，但一发生就卡死整个流程：你明明 octane:start 成功了，浏览器访问 http://localhost:8000 却返回 500 或空白页，日志里只有 file_put_contents(/path/storage/framework/cache/data/...): failed to open stream。
- 原因不是 Octane，而是 Laravel 启动时要写缓存、生成 key、读
.env——这些和 FPM 下要求完全一致 - 必须确保：
cp .env.example .env→php artisan key:generate→chmod -R 775 storage bootstrap/cache - 特别提醒：Docker 环境中，如果用
php:8.3-cli镜像，storage目录属主可能是 root，而 Octane 工作进程以 www-data 运行，权限不匹配就会静默失败
环境准备比命令多敲两次更重要，尤其是 php --ri swoole 和 ls -l storage 这两个动作，花十秒做的检查，能省两小时查为什么“明明装了 Octane 却没变快”。
