推荐用sentry-sdk替代raven，需pip安装≥1.0版，在settings.py顶部初始化并配置DSN、DjangoIntegration等；DEBUG=True时默认不报错；非HTTP异常需手动捕获；Celery需加CeleryIntegration；验证时注意环境、网络及Nginx拦截。
安装sentry-sdk并初始化Django项目
直接用 sentry-sdk 替代老的 raven，这是当前唯一推荐方式。老 SDK 已停更，且不兼容 Django 3.2+ 和 Python 3.9+。
- 运行
pip install sentry-sdk，确保版本 ≥ 1.0（建议用最新稳定版） - 在
settings.py最顶部（早于任何 Django 模块导入）插入初始化代码，否则中间件、日志处理器可能漏报 -
SENTRY_DSN必须从 Sentry 项目设置页复制完整 URL（含 secret key 部分），格式形如https://xxx@o123.ingest.sentry.io/456
示例初始化位置（settings.py 开头）：
import sentry_sdk from sentry_sdk.integrations.django import DjangoIntegration <p>sentry_sdk.init( dsn="<your_dsn_here>", integrations=[DjangoIntegration()], traces_sample_rate=0.1, send_default_pii=True, )
配置Django中间件和日志处理器
默认情况下 sentry-sdk 自动注册 Django 中间件和日志捕获，但你得确认没手动禁用或覆盖关键配置。
- 检查
INSTALLED_APPS中没有残留raven.contrib.django.raven_compat—— 它会与sentry-sdk冲突，导致 500 错误不上传 -
LOGGING配置里若自定义了handlers或rootlogger，需显式添加sentryhandler，否则logger.error()不触发上报 - Django 的
DEBUG = True时，sentry-sdk默认不发送事件（避免本地调试污染线上数据），上线前务必设为False
补全日志 handler 示例（加到 LOGGING 字典中）：
立即学习“Python免费学习笔记（深入）”；
'handlers': {
'sentry': {
'level': 'ERROR',
'class': 'sentry_sdk.integrations.logging.SentryHandler',
},
},
'root': {
'level': 'WARNING',
'handlers': ['sentry'],
}捕获非HTTP异常和异步任务错误
Django 请求生命周期外的异常（比如管理命令、定时任务、Celery worker）默认不会被自动捕获，必须手动 wrap 或显式调用 sentry_sdk.capture_exception()。
- Celery 任务需启用
sentry_sdk.integrations.celery.CeleryIntegration()，并确保它出现在integrations列表中 - 自定义管理命令（
python manage.py mycmd）应在handle()方法开头加sentry_sdk.push_scope()+try/except，否则未处理异常直接退出，Sentry 来不及上报 - 使用
threading或asyncio时，子线程/协程中抛出的异常不会继承主线程的 Sentry 上下文，需在子线程内重新 init 或手动 capture
Celery 集成示例（仍写在 settings.py 初始化处）：
from sentry_sdk.integrations.celery import CeleryIntegration
sentry_sdk.init(
# ... 其他参数
integrations=[DjangoIntegration(), CeleryIntegration()],
)验证上报是否生效及常见静默失败点
最常遇到的是“配完了却没看到事件”——多数不是配置错，而是触发条件没满足或环境挡住了。
- 执行
python manage.py shell，然后输入raise Exception("test sentry")：如果 DEBUG=True，不会上报；设为 False 后再试，或加with sentry_sdk.configure_scope() as scope: scope.set_tag("test", "true")强制发一次 - 检查 Sentry 项目设置里的
Environments过滤器，是否误设了environment: production却没在 SDK 中传environment="production" - Nginx 或负载均衡器拦截了 5xx 响应（比如返回自定义错误页），Django 实际没走到异常处理流程，Sentry 就收不到；此时需在 Nginx 日志中查原始状态码，或改用
before_send回调做兜底
加 environment 示例（推荐）：
sentry_sdk.init(
# ...
environment="production", # 或 "staging"、"local"
)环境变量名、网络代理、DNS 解析失败都可能导致静默丢包，上线后第一件事是看 Sentry 的 Project Settings → Client Keys (DSN) 页面右上角的 “Last event received” 时间戳。
