让前端调试更顺手，在PHP日志里打印上下文数据

从一次“前端甩锅”说起

“这个接口返回的数据不对，你后端看看日志？”
“日志里啥也没有，你前端先 console.log 一下？”

这种对话在前端和后端协作中太常见了。很多时候，问题出在请求参数、请求头、用户状态等“上下文数据”上——前端看到的是浏览器里的报错，后端看到的是 PHP 日志里孤零零的异常信息。两边信息不对称，调试效率自然低。

如果 PHP 日志里能顺手把关键的上下文数据打出来，前端同学在浏览器里看 Network 面板时，就能直接对照后端日志，快速定位是传参问题、还是后端逻辑问题，甚至省去一次“在吗？帮我打个日志”的沟通成本。

别只写 error_log，要打印“元信息”

很多 PHP 项目里，日志就是一行 `error_log($message)`，打出来只有一句话。比如：

[Tue Jan 21 10:00:00 2025] Undefined index: user_id in /var/www/html/api.php on line 42

你看到这个，能知道是哪个用户、哪个接口、哪个请求触发的吗？完全不知道。前端后端各查各的，最后可能发现是某个 App 版本传来的参数格式变了，但日志里没有版本号，无从查起。

所以，我们需要在日志里注入“请求上下文”。最简单的做法，是在入口文件或中间件里，把当前请求的 method、URI、GET/POST 参数、请求头（特别是 User-Agent、Authorization）、用户 ID（如果有）、以及一个唯一的 request_id 拼成一个数组，和异常信息一起打出来。

function log_context($message, $extra = []) {
    $context = [
        'time'     => date('Y-m-d H:i:s'),
        'method'   => $_SERVER['REQUEST_METHOD'] ?? 'CLI',
        'uri'      => $_SERVER['REQUEST_URI'] ?? '',
        'query'    => $_GET,
        'body'     => $_POST,
        'headers'  => getallheaders(),
        'user_id'  => $_SESSION['user_id'] ?? $_COOKIE['uid'] ?? null,
        'trace'    => debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 5),
    ];
    $merged = array_merge($context, $extra, ['message' => $message]);
    error_log(json_encode($merged, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
}

这样打出来的日志，前端同学一看就知道：哦，原来我传的 `user_id` 是字符串 `"123"`，而接口要求 int，后端 `===` 比较失败。问题一目了然。

给每个请求加个 request_id，前端日志也能串起来

如果你觉得把所有上下文都塞进错误日志太杂乱，可以只塞一个 `request_id`。在 PHP 入口处生成一个基于时间戳和随机数的 ID，存入 `$_SERVER['request_id']`，然后在所有日志中带上它。同时，响应头里也返回这个 ID（比如 `X-Request-ID`）。前端在控制台或 Network 面板看到这个响应头，把 ID 发给后端，后端直接 grep 日志就完事了。

// 入口文件开头
$request_id = md5(uniqid(mt_rand(), true));
$_SERVER['REQUEST_ID'] = $request_id;
header('X-Request-ID: ' . $request_id);

之后你的日志函数里默认加入 `request_id`，这样即使不打完整上下文，也能通过 ID 关联到同一个请求的所有日志。这种思路在生产环境也很有用，但本地开发时，我把完整上下文打印出来更直观。

结合前端工具：直接在 Response 里塞调试信息

这里有个更“野”但很好用的方法：在 PHP 开发环境里，把上下文数据直接以 JSON 形式塞进响应头的自定义字段，比如 `X-Debug-Context`。前端在浏览器 Network 面板里点开请求，看一眼响应头就拿到了后端的所有上下文，连日志都不用翻。

if (getenv('APP_DEBUG') === 'true') {
    header('X-Debug-Context: ' . base64_encode(json_encode($context)));
}

前端同学可以写个小的 Chrome 扩展或油猴脚本，自动解码显示。不过我不太推荐在生产环境这样做，安全性不好。但本地联调时，这个方式简直丝滑——前端改参数、点一下请求、响应头里立刻告诉你后端接收到了什么，等于实时双向调试。

调试日志的“三要三不要”

要打参数，但不要打印密码、token 值（脱敏处理，`substr` 或掩码）。
要带时间戳，但不要用 `date()` 每行重复拼接——用 monolog 或统一 logger，格式化一次。
要设计成可按级别过滤，比如开发时打印 `debug`，生产只打印 `error`，但千万不要在线上开启完整上下文日志，否则日志文件一天几个 GB 很正常。

让前后端协作从“猜”变成“看”

前端调试最耗时的不是写代码，而是和后端扯皮。你在前端写了两小时代码，发现接口返回 500，你只能看到“500 Internal Server Error”。你问后端，后端说“我这没报错”。你让他加日志，他加完告诉你“你参数不对”。你说“参数我打印了没错啊”。循环往复。

如果从项目一开始就约定：PHP 日志里必须包含 `request_id`、`uri`、`params`、`headers` 这几个字段，前端在打包环境里也可以看到响应头里的 `X-Request-ID`，然后直接去日志平台搜。问题定位从“几小时”缩短到“几分钟”。这不是什么高深技术，只是一个简单的习惯——但很多团队没做到。

从今天起，在你项目的入口文件里加上那几行代码。下一次前端再喊你“接口有问题”时，你可以优雅地回复：“日志里有完整的请求上下文，你看一眼 `X-Request-ID` 对应那条，找找哪里和你预期不符。”

让调试更顺手的，从来不是更复杂的工具，而是更透明的信息。