推荐使用 sentry/sentry-laravel 而非 sentry/sentry，因其自动集成 laravel 异常捕获、日志通道与上下文注入；dsn 必须含协议和路径，否则静默失效；仅未捕获异常自动上报，手动捕获需调用 captureexception()；环境需严格配置 enabled 和 environment，采样率按业务重要性设定；前后端链路追踪依赖 trace header 透传与 cors 配置。
安装 Sentry PHP SDK 并配置 Laravel 适配器
官方推荐用 sentry/sentry-laravel，不是直接装 sentry/sentry。前者封装了 Laravel 的异常捕获机制、日志通道集成和上下文自动注入（比如当前用户、请求 ID、路由名），后者得自己手动 hook report() 方法，容易漏。
执行：
composer require sentry/sentry-laravel然后运行
php artisan sentry:publish --dsn=https://xxx@o123.ingest.sentry.io/456。注意 DSN 必须带协议和路径，不能只填域名或 ID —— 否则初始化失败但无报错，Sentry\init() 静默跳过，监控就彻底失效。
常见错误现象：php artisan tinker 中调用 Sentry\captureException(new \Exception('test')) 没反应，或 Sentry 后台收不到事件。大概率是 DSN 格式不对，或 .env 里写成了 SENTRY_LARAVEL_DSN=xxx 却没在 config/sentry.php 中启用 enabled 开关（默认是 true，但某些部署会覆盖为 false）。
Laravel 异常上报触发时机与手动捕获边界
SDK 默认只上报未捕获异常（即抛到顶层的 Exception 或 Error），不会上报 try/catch 里的异常，也不会上报 Log::error() 这类日志 —— 即使你绑定了 Sentry 日志通道，也得显式调用 Sentry\captureException() 或 Sentry\captureMessage() 才会上报。
使用场景举例：
- API 接口里
try/catch处理业务异常后想告警（比如支付回调验签失败），需手动Sentry\captureException($e) - 队列任务中发生可重试异常（如 HTTP 调用超时），不想影响重试逻辑但要记录，用
Sentry\captureException($e, ['extra' => ['job' => get_class($this)]]) - 不想上报 404 或 403 这类预期 HTTP 状态码异常？检查
config/sentry.php中的ignore_exceptions数组，Laravel 自带的NotFoundHttpException默认已包含，但自定义的PermissionDeniedException得手动加
环境隔离与采样率控制（避免测试流量刷爆 quota）
Sentry 按事件数计费，本地开发和测试环境必须关掉，否则跑个 phpunit 就可能耗尽当月额度。关键配置在 config/sentry.php 的 enabled 和 environment 字段：
enabled 建议设为：
'enabled' => app()->environment('production', 'staging')而不是 !app()->environment('local') —— 因为有些 CI 环境是 testing，它既不是 local 也不是 production，容易误开。
采样率（sample_rate）别乱调。设成 0.1 表示只上报 10% 的错误事件，适合高流量生产环境；但对低频核心服务（如支付网关），建议保持 1.0，否则偶发问题根本捞不到现场数据。
容易踩的坑：在 .env 里写 SENTRY_ENVIRONMENT=dev，却没同步改 config/sentry.php 中的 environment 键值（它默认读 APP_ENV），结果所有事件都标成 production，排查时分不清环境。
前端 JS 错误如何和 Laravel 后端关联？
单页应用（SPA）里用户操作触发 API 报错，光看后端 Sentry 事件看不出是哪个页面、哪个用户行为引发的。需要在前端初始化 Sentry 时传入 traces_sample_rate，并在 API 请求头里带上 X-Sentry-Trace 和 baggage，后端 SDK 才能自动建立前后端 transaction 关联。
实操建议：
- 前端初始化加
tracesSampleRate: 1.0（开发期全量），并确保integrations包含BrowserTracing - Laravel 发起的 Guzzle 请求，用中间件自动注入 trace header：
$client->request('GET', '/api/user', [ 'headers' => array_merge($headers, Sentry\getTraceparentHeader()) ]); - 别依赖
user.id做关联 —— 它只用于用户去重统计，真正链路追踪靠的是trace_id和span_id，这些由 Sentry SDK 自动透传
复杂点在于跨域和微服务调用：如果前端域名和 API 域名不同，需确认 Access-Control-Expose-Headers 包含 X-Sentry-Trace，否则浏览器 JS 拿不到 header，链路就断了。
