线上出问题时,靠的是调试信息、异常处理和日志三件套。官方手册《日志和错误处理》一章下设多个子类:调试模式、异常处理、日志记录、日志配置。本文逐一整理,结尾附综合小实例。参考:ThinkPHP 8 日志和错误处理。
一、调试模式与错误显示
调试开关在 config/app.php:
'app_debug' => true, // 开发环境:显示详细错误页(堆栈、请求、环境)
'app_debug' => false, // 生产环境:只显示友好错误页
- 调试模式会把文件路径、SQL、堆栈全部暴露出来,生产环境务必关闭
- 错误页面可以自定义模板(
app/exception/tpl/think_exception.tpl),换成站点风格
二、异常处理
未捕获的异常统一交给异常处理类。可以自定义它做统一响应格式:
// config/app.php
'app_exception_handle' => appExceptionHandle::class,
<?php
namespace app;
use thinkexceptionHandle;
use thinkResponse;
class ExceptionHandle extends Handle
{
// 统一渲染异常
public function render($request, Throwable $e): Response
{
// AJAX/接口请求统一返回 JSON
if ($request->isAjax()) {
return json(['code' => 0, 'msg' => $e->getMessage()], 500);
}
return parent::render($request, $e);
}
// 记录异常日志
public function report($e): void
{
parent::report($e);
}
}
业务上也可以主动抛异常:throw new hinkException('余额不足', 10001);,HTTP 状态异常用 HttpException。
三、日志记录
用 thinkfacadeLog 门面记录日志,共 8 个级别:
| 级别 | 典型用途 |
|---|---|
debug | 调试细节 |
info | 一般运行信息 |
notice | 值得注意但不算错 |
warning | 警告(磁盘将满等) |
error | 运行时错误 |
critical、alert、emergency | 严重故障到紧急故障 |
use thinkfacadeLog;
Log::record('默认 info 级别,请求结束批量写入');
Log::error('支付失败', ['order_id' => 1001]); // 带上下文
Log::write('立即写入日志', 'warning'); // 立即落盘
record()延迟写入(请求结束统一落盘,性能好);write()立即写入(关键现场不丢)- 第二个参数支持数组上下文,方便排查
四、日志配置(config/log.php)
return [
'default' => 'file',
'channels' => [
'file' => [
'type' => 'file',
'path' => runtime_path('log'), // runtime/log 按日期分目录
'file_size' => 2097152, // 单文件超 2MB 自动分割
'apart_level' => ['error'], // error 独立成文件
'json' => false, // JSON 格式(ELK 采集友好)
'realtime_write' => false, // 实时写入
],
],
];
支持多通道:不同渠道可配不同驱动(file、database 等);apart_level 把重要级别单独存放,排错先看它;json 格式配合日志采集系统使用。
五、实用技巧
- 日志按天分目录存于
runtime/log,定期清理或接采集系统 - 日志里不要记录密码、密钥等敏感信息
- 关键业务(支付、登录)用
write()立即落盘,防止进程异常丢日志 - 开发期可开启
app_trace页面 Trace 辅助调试
六、综合小实例:支付异常处理
把异常处理和日志记录串起来:
use thinkfacadeLog;
public function pay($id)
{
try {
// ...支付逻辑...
} catch (Throwable $e) {
// 记录现场:级别 + 上下文
Log::error('支付失败:' . $e->getMessage(), [
'order_id' => $id,
'trace' => $e->getTraceAsString(),
]);
return json(['code' => 0, 'msg' => '支付失败,请稍后重试'], 500);
}
return json(['code' => 1, 'msg' => '支付成功']);
}
配套生产配置:app_debug => false 关调试、apart_level => ['error'] 让错误独立成文件、异常处理类把接口错误统一成 JSON —— 一套组合拳,出问题时日志里有现场、用户端有友好提示。
七、总结
开发开 app_debug、生产必须关;异常交给自定义 ExceptionHandle 统一渲染;Log 八级别按严重程度选用,record 延迟 write 立即;config/log.php 管通道、分割、apart_level、JSON 格式;关键业务记上下文、不记敏感信息。