octane、pest 和 sanctum 在 laravel 11 中均需手动初始化：必须执行 octane:install、pest:install 和 sanctum:install 迁移，否则功能静默失效；各自有严格依赖条件，如 frankenphp 二进制路径、pest 入口文件加载、sanctum 的 cookie 域名与中间件配置。
Octane、Pest 和 Sanctum 在 Laravel 11 中不是“开箱即用就高性能/零配置就安全”的模块，它们各自有明确的适用边界和必须手动处理的初始化环节。跳过 octane:install、忽略 sanctum:install 的迁移或漏掉 Pest 的 pest --init，后续所有功能都会静默失效。
Octane 启动失败：常见报错与 FrankPHP 适配要点
运行 php artisan octane:start 报 command not found: frankenphp 或 Failed to start FrankenPHP server，本质是二进制未就位或权限/路径不对。Laravel 11 默认不预装 FrankenPHP，即使你指定了 --server=frankenphp，也必须先执行 octane:install 才会下载并设为可执行。
- 使用 Sail 时，
./vendor/bin/sail artisan octane:install --server=frankenphp必须在./vendor/bin/sail up之后执行，否则容器内无写入权限 - FrankenPHP 二进制默认放在
storage/frankenphp，但 Docker 容器中需确保该路径可写且挂载正确；若改用自定义路径（如/usr/local/bin/frankenphp），需同步更新SUPERVISOR_PHP_COMMAND中的调用路径 - 启动后访问 443 端口失败？检查
docker-compose.yml是否已显式映射- '443:443'，且frankenphp配置中启用了 HTTPS（仅靠端口映射不够）
Pest 测试无法识别 it 或 test 函数
直接写 it('loads home page', function () { ... }); 却提示 Call to undefined function it()，说明 Pest 运行时环境未加载其 DSL。Laravel 11 不再自动注册 Pest 全局函数，必须完成初始化。
- 首次使用前务必运行
php artisan pest:install（而非仅composer require pestphp/pest --dev） - 该命令会生成
tests/Pest.php入口文件，并在phpunit.xml中注入bootstrap="tests/Pest.php"；若手动删过该文件，Pest 就退化成普通 PHPUnit - 在 IDE 中仍标红？确认 PHP 解释器已加载
tests/Pest.php，IntelliJ/PHPStorm 需右键该文件 → “Load File into Script Context”
Sanctum SPA 认证跨域请求始终 401
前端发 POST /login 成功返回 200，但后续带 X-XSRF-TOKEN 的请求全被拒，问题不在令牌本身，而在 Laravel 11 的中间件顺序和 Cookie 策略收紧。
-
app/Http/Middleware/VerifyCsrfToken.php中的$except数组只豁免路径，不豁免跨域请求；SPA 认证依赖web中间件组里的StartSession和EncryptCookies，必须确保路由定义在routes/web.php且未被api中间件覆盖 - Laravel 11 默认启用
SameSite=Lax，若前端域名与后端不完全一致（如http://localhost:5173vshttp://localhost），需在config/session.php中显式设'same_site' => 'None'并开启'secure' => true（HTTPS 环境下才生效） - 前端 fetch 请求必须带
credentials: 'include'，且响应头中Access-Control-Allow-Credentials: true与Access-Control-Allow-Origin不能为*（必须指定确切域名）
Octane 的内存常驻模型会让任何全局变量、静态属性或未重置的单例状态在请求间残留；Pest 的并行执行可能暴露数据库事务隔离问题；Sanctum 的 Cookie 认证极度依赖域名、协议、路径三者严格匹配——这些不是文档末尾的“注意事项”，而是上线前必须逐项验证的硬性条件。
