技术 · 思考 · 实践 · 成长

首页/ThinkPHP8/正文

ThinkPHP 8 日志与错误处理完全指南:调试模式、异常处理与日志配置

ThinkPHP89 次阅读

线上出问题时,靠的是调试信息、异常处理和日志三件套。官方手册《日志和错误处理》一章下设多个子类:调试模式、异常处理、日志记录、日志配置。本文逐一整理,结尾附综合小实例。参考: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 格式;关键业务记上下文、不记敏感信息。

只要认真对待生活,终有一天,你的每一份努力,都将绚烂成花。

评论交流

0 条评论 · 支持多级回复
验证码
暂无评论,来说说你的想法吧

相关文章

继续阅读