Download the PHP package goletter/hyperf-exception-notify without Composer

hyperf-exception-notify

Hyperf 异常通知组件：线上出现异常时，自动把异常信息、请求参数、堆栈推送到 钉钉 / 企业微信 / 飞书 群机器人，或写入日志。

• HTTP 请求异常、命令行异常自动上报，业务代码也可手动上报
• 同一个异常短时间内只推一次，不刷屏
• 默认异步队列推送，不拖慢接口
• 自动对密码、token、Authorization 等敏感字段打码

环境要求

• PHP >= 8.2
• Hyperf >= 3.1
• Redis（用于限流）
• hyperf/async-queue 消费进程（异步推送时需要）

一、安装

发布后生成配置文件 config/autoload/exception_notify.php。

二、三步接入（以钉钉为例）

1. 创建群机器人

钉钉群 → 群设置 → 机器人 → 添加「自定义」机器人，安全设置任选：

• 加签：复制 SEC 开头的密钥，填到 EXCEPTION_NOTIFY_DINGTALK_SECRET
• 自定义关键词：例如填 异常，同时填到 EXCEPTION_NOTIFY_DINGTALK_KEYWORD（若标题或正文里已包含该词，不会再追加到末尾）

复制 Webhook 地址里 access_token= 后面的部分，填到 EXCEPTION_NOTIFY_DINGTALK_TOKEN。

2. 配置 .env

默认只在 APP_ENV 为 production / prod 时推送。本地调试见「七、本地测试」。

3. 注册异常处理器

config/autoload/exceptions.php，放在第一个：

Hyperf 按顺序执行异常处理器，前面的处理器一旦调用 stopPropagation()，后面的就不会执行。ExceptionNotifyHandler 只负责上报，不修改响应、不阻止后续处理器，放在第一个才能保证每个异常都经过它。

完成。命令行（php bin/hyperf.php xxx）执行失败也会自动上报，无需额外配置。

三、各平台配置

可以同时推多个平台：EXCEPTION_NOTIFY_CHANNELS=dingTalk,weWork,log。没填 token 的平台会被自动跳过。

• token：Webhook 地址中的 key。钉钉是 access_token= 后面的值；企业微信是 key= 后面的值；飞书是 /hook/ 后面的值。
• 超长截断：实际按上限的 90% 截断，结尾显示 ...。企业微信上限较小，Post 参数和堆栈经常被截断。
• 关键词：钉钉、飞书设置了关键词安全校验时必须配置 _KEYWORD。正文里已包含该词时不会再追加；不想在末尾出现「异常」时，可把关键词写进 EXCEPTION_NOTIFY_REPORT_TITLE，或改用加签（_SECRET）并清空 _KEYWORD。
• @人（钉钉）：在配置文件 channels.dingTalk 中设置 atMobiles、atDingtalkIds 或 isAtAll。

四、通知内容示例

json { "goods_id": 1024, "password": "**" }

0 /opt/www/app/Controller/OrderController.php(42): App\Service\OrderService->create(Array)

9 {main}

`

• 命令行异常没有请求信息时，URL、Post、Query 等部分不显示。
• 堆栈会过滤掉 vendor 目录，只保留业务代码，最多 15 行。
• Post / Query 每块最多约 1500 字符。
• 飞书按纯文本发送；钉钉 / 企微按 Markdown 发送。

五、配置说明

所有配置都在 config/autoload/exception_notify.php，大部分可以用环境变量覆盖。

开关与范围

常见的不需要上报的异常：

推送方式

• 异步推送需要队列消费进程在运行，否则消息会积压在队列里。
• 队列本身不可用（如推送到 Redis 失败）时，会自动改为同步发送。

限流

「同一异常」指异常类、文件、行号、消息完全相同。消息里带变量（如订单号）时，每条都会被视为不同异常。

敏感字段打码

对 Post、Query、Header 生效，不区分大小写，支持 * 通配符，嵌套数组也会处理。可按业务追加，例如 'id_card'、'*mobile*'。

六、手动上报

帮助函数

依赖注入

手动上报同样受 enabled、env、dont_report、限流约束。

上报队列任务、定时任务的异常

默认只自动上报 HTTP 请求和命令行的异常。异步队列任务、定时任务执行失败时，可以加一个监听器：

七、本地测试

.env 临时改为：

加一个测试路由：

访问后群里应收到消息。测试完记得把配置改回来。

收不到消息时按顺序检查：

1. APP_ENV 是否在 EXCEPTION_NOTIFY_ENV 中
2. EXCEPTION_NOTIFY_CHANNELS 是否包含该平台，token 是否已填写
3. 异常是否在 dont_report 中，或者是否被其它异常处理器提前 stopPropagation()（处理器要放第一个）
4. 是否被限流：同一异常在 decay_seconds 内已推送过
5. 异步模式下队列消费进程是否在运行
6. 机器人安全设置：关键词是否一致、加签密钥是否正确、IP 白名单是否包含服务器出口 IP
7. 查看控制台日志中的 Exception notify failed 错误信息

八、进阶

事件

每次推送前后会分发事件，可用于统计或审计：

采集器

配置项 collector 决定采集哪些信息：

注意：markdown 格式只展示 Application / Exception Basic / Request Basic / Post / Query / Trace 等内容。其它采集器（包括自定义采集器）的数据只在 format=json 时出现。

自定义采集器：

需要拿到异常对象时，实现 ExceptionAwareContract 并使用 ExceptionAwareTrait，通过 $this->exception 访问。

消息处理管道（sanitizers）

每个渠道的 sanitizers 会在发送前依次处理消息内容，参数写在冒号后面，多个参数用逗号分隔：

可用的处理器：LengthLimitSanitizer、AppendContentSanitizer、PrependContentSanitizer、StrReplaceSanitizer、TrimSanitizer、ToMarkdownSanitizer、ToHtmlSanitizer、UrlEncodeSanitizer、FixPrettyJsonSanitizer、VarOutputSanitizer。

截断要放在追加关键词之前，否则关键词可能被截掉，导致机器人拒收。

九、升级注意（相对旧版）

1. 不再默认推送全部渠道，只推 EXCEPTION_NOTIFY_CHANNELS / report_channels 中的渠道
2. 默认环境改为 production,prod，本地默认不推送
3. 修复 WeWork 驱动方法名、渠道名、配置 key（exception_notify）、pipes 改名为 sanitizers
4. 推送默认走异步队列，请确保队列消费进程在运行
5. composer.json 中 ConfigProvider 命名空间已修正为 Goletter\HyperfExceptionNotify\ConfigProvider
6. 新增 mask_fields 配置；钉钉 sanitizers 顺序改为「先截断、再追加关键词」
7. ExceptionNotifyHandler 建议放在异常处理器列表的第一个

重新发布配置后，请对照合并旧的 exception_notify.php。