今天我在 reddit 上看到 Sentry 的推广，想到 19 年我第一次在公司自研产品b2b2c上使用 Sentry 的经历，后面在其他项目上多次使用Sentry，今天就顺手分享一下在 Laravel 项目中接入 Sentry 的实践心得。

现代项目往往涉及 Web、移动端和小程序，错误追踪和日志集中化显得尤其重要，Sentry 在这方面真的挺香的。

安装与基础配置

Laravel 后端集成 Sentry 很直观，官方提供了 SDK。最简单的安装方式是通过 Composer：

composer require sentry/sentry-laravel

然后在 config/app.php 注册服务提供者（Laravel 5.x）：

Sentry\Laravel\ServiceProvider::class,

或者在 Laravel 6+ 可以直接使用自动发现。配置文件可以发布出来：

php artisan vendor:publish --provider="Sentry\Laravel\ServiceProvider"

会生成 config/sentry.php，里面可以设置 DSN、环境、采样率等。比如：

return ['dsn' => env('SENTRY_DSN'),'environment' => env('APP_ENV', 'production'),'traces_sample_rate' => 0.2,
];

前端 Vue 使用官方 JS SDK：

npm install @sentry/vue @sentry/tracing

初始化示例：

import * asSentryfrom"@sentry/vue";
import { Integrations } from"@sentry/tracing";Sentry.init({app,
dsn: process.env.VUE_APP_SENTRY_DSN,
integrations: [newIntegrations.BrowserTracing()],
tracesSampleRate: 0.2,
});

移动端 iOS/Android 可用官方 SDK 或第三方桥接库，注意需要在 info.plist 或 AndroidManifest 中声明权限。

微信小程序比较特殊，需要在 微信公众平台配置域名白名单，否则 SDK 无法向 Sentry 发送数据。具体是把 Sentry 的上报域名加入 request 合法域名即可。

环境区分与配置优化

在 Laravel 中，可以通过 .env 文件区分环境：

SENTRY_DSN_DEV=https://xxx@sentry.io/123
SENTRY_DSN_PROD=https://yyy@sentry.io/456
APP_ENV=dev

然后在 config/sentry.php 中根据环境选择 DSN：

'dsn' => env('APP_ENV') === 'prod' ? env('SENTRY_DSN_PROD') : env('SENTRY_DSN_DEV'),

这样开发、预发和生产环境的事件不会互相干扰。同时可以调整 traces_sample_rate 或日志等级，避免开发环境刷屏。

捕获异常与忽略策略

Laravel 默认会捕获异常并发送到 Sentry，但有些非致命错误不需要打扰，例如第三方包的警告。可以在 before_send 钩子中过滤：

Sentry\configureScope(function (Sentry\State\Scope $scope): void {$scope->addEventProcessor(function (array $event) {if (isset($event['exception']) && str_contains($event['exception']['values'][0]['type'], 'SomeNonCriticalException')) {return null; // 忽略}return $event;});
});

同时也可以手动捕获异常：

try {// 业务逻辑
} catch (\Exception $e) {Sentry\captureException($e);
}

前端 Vue、移动端或小程序同理，可以根据 error.message 或 URL 过滤不必要的事件。

与队列和日志结合

Laravel 队列任务出错时，如果没有捕获，异常可能被吞掉。推荐在 Handler 或队列 Job 中统一处理：

public function failed(Exception $exception)
{Sentry\captureException($exception);
}

结合日志系统也很方便，Sentry 可以作为自定义日志通道：

'channels' => ['sentry' => ['driver' => 'sentry',],
],

这样 Log::channel('sentry')->error('Something happened') 就能发送到 Sentry，同时保留本地日志。

跨平台注意事项

1. 1. Vue 前端：一定要配置 source map，这样 Sentry 才能显示真实的行号和文件。

2. 2. iOS/Android：建议在 release 版本开启符号化上传，这样崩溃栈才可读。

3. 3. 微信小程序：除了域名白名单，还要考虑 network timeout，避免 SDK 堵塞前端逻辑。

小技巧是前端可以捕获全局未处理异常，统一发送：

window.addEventListener('error', event => {Sentry.captureException(event.error);
});

Sentry 平台部署

除了 SDK 集成，很多人关心 Sentry 本身的平台选型。Sentry 提供两种模式：SaaS 和 独立部署。

SaaS 版本就是官方托管的服务，你只需要注册账号、配置 DSN，就能马上收集错误，省去运维烦恼，升级和安全都由官方负责。适合绝大多数中小型项目或者希望快速落地的团队。

独立部署则可以把 Sentry 安装在自己的服务器上，完全控制数据、网络访问和存储策略。部署难度稍高，需要配置 PostgreSQL、Redis、Kafka 等依赖，也需要处理版本升级和备份策略，但对数据隐私要求高或者企业内网项目，这几乎是唯一选择。不过，官方提供了Docker镜像可以直接使用。

实际上，在企业里经常看到混合使用：研发环境或小型项目走 SaaS，核心业务走自建，既灵活又安全。Laravel 项目接入时，只要 DSN 对应正确，代码层面无需额外改动，平台切换非常顺畅。

实用技巧与优化

• • 批量忽略低优先级错误，比如 404 或第三方脚本错误。

• • 调整采样率降低重复告警，例如 traces_sample_rate: 0.1。

• • 配合 release 标签区分不同版本，便于追踪回归问题：

Sentry\configureScope(function (Sentry\State\Scope $scope): void {$scope->setTag('release', config('app.version'));
});

• • 队列和日志结合，保证即便异步任务失败，也能可靠上报。

写在最后

从 SDK 集成到平台部署，其实 Sentry 的魅力就在于统一、多端、可扩展。多环境、多平台、队列日志结合后，你会发现错误的可见性大大提高，排查问题也不再是盲人摸象的状态。19 年 BBC 的经历到现在依然印象深刻，Sentry 帮我节省了无数调试时间。今天分享出来，希望对大家 Laravel 项目的多平台错误监控有所启发。

写作不易，希望您动动发财的小手，帮忙一键三连(点赞、推荐、关注)，您的鼓励，就是我写作的动力！