必须使用 JSON 日志格式并配置 log_format: json，再通过 log_fields 注入经 json_encode 转义的 $_SERVER 变量，才能安全添加 user_id、request_id 等结构化字段。
日志格式必须用 JSON 才能加自定义字段
FrankenPHP 默认用 Apache 风格文本日志（access.log），这种格式没法嵌入结构化字段。想加 user_id、request_id 或 trace_id，第一步就得切到 JSON 日志——它靠 log_format + json 指令驱动，不是靠 PHP 层打点。
在 frankenphp.yaml 里配：
http: log_format: json access_log: /var/log/frankenphp/access.json
不设 log_format: json，后面所有字段都白搭。
用 log_fields 注入 PHP 变量或常量
FrankenPHP 支持在 JSON 日志里直接插入 PHP 脚本返回的值，靠 log_fields 配置项。它只认 $_SERVER、$_ENV 和你显式塞进 $_SERVER 的东西。
立即学习“PHP免费学习笔记（深入）”；
常见做法是：在入口 PHP（如 public/index.php）开头写：
$_SERVER['X_REQUEST_ID'] = bin2hex(random_bytes(8)); $_SERVER['X_USER_ID'] = $_COOKIE['user_id'] ?? 'anonymous';
然后在 frankenphp.yaml 中引用：
http:
log_format: json
access_log: /var/log/frankenphp/access.json
log_fields:
request_id: "$_SERVER[X_REQUEST_ID]"
user_id: "$_SERVER[X_USER_ID]"
app_version: "1.2.0"
-
log_fields的 key 是日志里的字段名，value 是字符串字面量或$_SERVER键名（带双引号和美元符） - 不支持函数调用，比如
"date('c')"或"getenv('APP_ENV')"会原样输出字符串，不会执行 - 字段值为空时（比如
$_SERVER不存在该键），对应 JSON 字段为null，不是省略
别在 PHP 里用 error_log() 补字段
有人试过在控制器里调 error_log(json_encode([...])) 想“补”日志，这完全绕开了 FrankenPHP 的日志管道。结果是：两份日志（一份结构化 JSON，一份杂乱的 error.log），字段对不上，还可能因并发写入损坏 JSON 格式。
真正要扩展字段，只有两条路：
- 走
log_fields+$_SERVER注入（推荐，轻量、统一、可审计） - 用
log_format自定义模板（仅限 Nginx 兼容模式，且不支持动态 PHP 值）
后者配置复杂，且 FrankenPHP 的 SAPI 模式下不生效，容易白忙活。
字段值含特殊字符时 JSON 会损坏
log_fields 不做 JSON 转义——如果 $_SERVER['X_USER_ID'] 是 alice"admin，最终日志会变成：{"user_id":"alice"admin", ...}，破坏整个 JSON 行。
安全做法是：所有进 log_fields 的值，必须提前清理：
$_SERVER['X_USER_ID'] = json_encode($_COOKIE['user_id'] ?? 'anonymous', JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); // 然后在 log_fields 里写：user_id: "$_SERVER[X_USER_ID]"
注意：这里用了 json_encode 包一层，确保引号、反斜杠、控制字符全被转义。FrankenPHP 不帮你做这事，漏了就等于日志不可解析。
实际部署时，JSON 日志行损坏会导致日志采集器（如 Filebeat、fluentd）丢整行，排查时发现字段“偶尔消失”，大概率是这个原因。
