Scout APM 的 PHP Agent 安装不必须用 Composer但强烈建议，因其仅通过 Composer 分发，本质是用户态 PSR-15 中间件，依赖自动加载和生命周期钩子。
Scout APM 的 PHP Agent 安装是否必须用 Composer？
不是必须，但强烈建议。Scout 官方 PHP Agent（scoutapp/scout-apm-php）仅通过 Composer 分发，不提供独立 .so 扩展或手动下载 zip 包。直接改 php.ini 加载扩展行不通——它本质是用户态的 PSR-15 兼容中间件 + 自动钩子注入器，依赖 Composer 的自动加载和生命周期钩子。
常见错误：试图把 scoutapm.so 编译进 PHP（它根本不存在），或把 vendor/scoutapp/... 目录硬拷到生产环境却不运行 composer install --no-dev，导致 autoload 失败、ScoutApm\ScoutApmAgent 类找不到。
- 执行
composer require scoutapp/scout-apm-php（Laravel 8+ 可省略，因 Scout 已内置适配） - 确保
vendor/autoload.php在入口文件（如public/index.php）中被最先引入 - 不要删掉
vendor/scoutapp/scout-apm-php/src/ScoutApm/Agent.php—— Laravel Scout 集成靠它启动
Laravel 中如何正确配置 SCOUT_KEY 和监控开关？
Scout APM 不读取 .env 里的 SCOUT_KEY，而是认 SCOUT_MONITOR 和 SCOUT_NAME。漏配 SCOUT_MONITOR=true 是最常见“没数据”原因——即使 key 正确，Agent 默认静默不采集。
配置项必须写在 .env 里，不能只写在 config/scout.php 中：Agent 初始化早于 Laravel Config 加载，它直读环境变量。
立即学习“PHP免费学习笔记（深入）”；
-
SCOUT_KEY=your-real-key-from-scout-dashboard（从 https://scoutapm.com/ 右上角 Account → API Keys 复制） -
SCOUT_MONITOR=true（开发环境也建议设为true，否则本地看不到 trace） -
SCOUT_NAME=my-laravel-app（建议带环境后缀，如my-laravel-app-prod，方便 Dashboard 区分） - 避免在
.env写SCOUT_ENABLED=true—— 这个键名 Scout PHP Agent 完全不识别
为什么 Laravel 请求在 Scout Dashboard 显示为 “Unknown Route”？
这是 Laravel 路由未被 Scout 正确识别的典型表现，根源在于 Scout 的路由解析依赖 Laravel 的 Illuminate\Routing\Route 实例，而某些场景下它拿不到有效 route 对象。
常见触发点：使用了自定义中间件提前返回响应（如 JWT 鉴权失败直接 return response()->json(...)）、在 Kernel.php 的 $middleware 数组里放了非标准中间件、或用了 Swoole/Swoft 等常驻内存模型但没调用 ScoutApm\ScoutApmAgent::reset()。
- 检查中间件是否在
handle()中提前return，若有，确保在 return 前调用\ScoutApm\ScoutApmAgent::getInstance()->trackRequest(); - 确认
App\Http\Kernel的$middlewareGroups['web']没混入非 HTTP 中间件（比如数据库连接池初始化类） - Swoole 场景下，在每次请求开始时加
\ScoutApm\ScoutApmAgent::getInstance()->reset();，否则旧 trace 数据会污染新请求
Scout APM 报错 “Unable to connect to ScoutAPM server” 怎么查？
这个错误不是网络连不上外网，而是 Agent 尝试连接本地 Unix socket 或 fallback 到 UDP 时失败。默认行为是先连 /tmp/scoutapm.sock，失败后改用 127.0.0.1:6590 UDP 发送数据。但很多 Docker 环境或无 root 权限的 shared hosting 根本没有 /tmp 写权限，或防火墙禁了 UDP 6590。
解决方式不是开防火墙，而是强制走 HTTP 回调——虽然性能略低，但 100% 可控。
- 在
.env加SCOUT_CORE_AGENT_SOCKET=false（注意不是SCOUT_SOCKET=false） - 确保能访问
https://agent.scoutapp.com（可 curl 测：curl -I https://agent.scoutapp.com） - 如果用 Cloudflare 或企业代理，需放行
agent.scoutapp.com的 SNI 和证书验证（Scout 使用 Let’s Encrypt，不接受自签名） - 别碰
SCOUT_CORE_AGENT_HOST和SCOUT_CORE_AGENT_PORT—— 它们只对本地 agent 进程有效，PHP Agent 不读这两个
SCOUT_MONITOR 环境变量缺失，以及 Swoole 环境下忘记 reset()。 
