日志配置详解

日志系统的所有配置集中在 config/log.php 文件中，本页详细说明每个配置项的作用和使用方式。

完整配置示例

php

<?php
// config/log.php

declare (strict_types=1);

use Viswoole\Log\Drives\File;

return [
    // ========== 基础设置 ==========

    // 默认使用的日志通道名称
    'default' => 'file',

    // ========== 级别路由 ==========

    // 将特定日志级别路由到指定通道
    // 键名为级别名，值为通道名（字符串或数组）
    'type_channel' => [
        // 'error' => 'error_channel',
        // 'sql' => 'sql_channel',
    ],

    // ========== 跟踪设置 ==========

    // 是否记录日志调用来源（文件路径:行号）
    // 开启后会在 context 中注入 _trace_source 字段
    'trace_source' => true,

    // ========== 控制台输出 ==========

    // 是否同时将日志输出到控制台
    // 开发环境建议开启，生产环境建议关闭
    'console' => false,

    // ========== 通道定义 ==========

    // 日志通道列表，键名为通道名称
    'channels' => [
        'file' => File::class,
    ],
];

配置项详细说明

default

类型: string
默认值: 'file'
说明: 指定默认使用的日志通道名称，必须与 channels 中的某个键名匹配

php

'default' => env('LOG_CHANNEL', 'file'),

type_channel

类型: array<string, string|string[]>
默认值: []
说明: 按日志级别将日志路由到指定的通道

配置规则:

php

'type_channel' => [
    // 单通道路由
    'error' => 'error_file',

    // 多通道路由（同一条日志写入多个通道）
    'critical' => ['error_file', 'alert_service'],

    // 支持的路由级别：
    // emergency, alert, critical, error, warning, notice, info, debug, sql, task
]

路由优先级: 当某级别在 type_channel 中配置了通道时，优先使用该通道；否则回退到 default 通道。

trace_source

类型: bool
默认值: false
说明: 是否在日志中记录调用来源（源码默认 false，框架自带 config/log.php 中显式设为 true）

开启效果 (true):

json

{
  "timestamp": "2024-01-01T12:00:00+08:00",
  "level": "info",
  "message": "用户登录",
  "context": {},
  "source": "/app/Controller/AuthController.php:45"
}

关闭效果 (false):

json

{
  "timestamp": "2024-01-01T12:00:00+08:00",
  "level": "info",
  "message": "用户登录",
  "context": {},
  "source": "not record"
}

性能提示: 开启 trace_source 会使用 debug_backtrace() 回溯调用栈，高频场景下可能产生少量性能开销。

console

类型: bool
默认值: true
说明: 是否将日志同步输出到控制台终端（源码默认 true，框架自带 config/log.php 中显式设为 false）

适用场景:

开发环境调试：设为 true，实时查看日志
生产环境：设为 false，避免污染标准输出

控制台输出效果:

text

[2024-01-01T12:00:00+08:00][info]: 用户登录 {} in AuthController.php:45    ← 绿色（info级别）
[2024-01-01T12:00:01+08:00][error]: 数据库连接失败 {...} in Database.php:22  ← 红色（error级别）

channels

类型: array<string, DriveInterface|string|array>
说明: 定义所有可用的日志通道

支持的配置格式:

格式一：字符串（驱动类名）

php

'channels' => [
    'file' => \Viswoole\Log\Drives\File::class,
]

框架会自动实例化该类（无参构造）。

格式二：数组（带选项）

php

'channels' => [
    'file' => [
        'driver' => \Viswoole\Log\Drives\File::class,
        'options' => [
            'storageDays' => 7,
            'maxFiles' => 30,
            'fileSize' => 10485760,
            'dateFormat' => 'c',
            'logFormat' => '[%timestamp][%level]: %message %context in %source',
            'json' => true,
            'json_flags' => JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
            'log_dir' => BASE_PATH . '/runtime/logs',
        ]
    ],
]

格式三：驱动实例

php

'channels' => [
    'custom' => new \App\Log\CustomLogDriver($config),
]

File 驱动专属配置

当通道使用 Viswoole\Log\Drives\File 驱动时，options 支持以下参数：

参数	类型	默认值	说明
`storageDays`	int	`7`	日志保留天数，超期的日期目录会被自动删除
`maxFiles`	int	`30`	单个日志级别下最大文件数量，超出后删除最早的文件
`fileSize`	int	`10485760` (10MB)	单个日志文件最大字节数，超出后自动切割新文件
`dateFormat`	string	`'c'`	时间戳格式，PHP date() 格式字符；传 `'timestamp'` 则保留原始时间戳
`logFormat`	string	见下方	日志文本格式规则
`json`	bool	`true`	是否以 JSON 格式存储日志
`json_flags`	int	`JSON_UNESCAPED_UNICODE \| JSON_UNESCAPED_SLASHES`	JSON 编码标志位
`log_dir`	string	`BASE_PATH.'/runtime/logs'`	日志文件根目录

logFormat 占位符

当 json 设为 false 时，logFormat 支持以下占位符：

占位符	说明	示例值
`%timestamp`	时间戳	`2024-01-01T12:00:00+08:00`
`%level`	日志级别	`info`
`%message`	日志消息	`用户登录`
`%context`	上下文数据（JSON 编码）	`{"user_id":100}`
`%source`	调用来源	`AuthController.php:45`

格式示例:

php

// 默认格式
'logFormat' => '[%timestamp][%level]: %message %context in %source'

// 输出: [2024-01-01T12:00:00+08:00][info]: 用户登录 {"user_id":100} in AuthController.php:45

// 简洁格式
'logFormat' => '%level | %message'

// 输出: info | 用户登录

// 自定义分隔符
'logFormat' => '%timestamp | [%level] %message'

环境变量集成

推荐使用环境变量管理敏感配置：

php

// config/log.php
return [
    'default' => env('LOG_CHANNEL', 'file'),
    'trace_source' => env('LOG_TRACE_SOURCE', true),
    'console' => env('APP_DEBUG', false),  // 开发环境自动开启
    'type_channel' => [],
    'channels' => [
        'file' => [
            'driver' => File::class,
            'options' => [
                'storageDays' => (int)env('LOG_STORAGE_DAYS', 7),
                'log_dir' => env('LOG_DIR', BASE_PATH . '/runtime/logs'),
            ]
        ],
    ],
];

对应的 .env 文件：

ini

# 日志配置
LOG_CHANNEL=file
LOG_TRACE_SOURCE=true
LOG_STORAGE_DAYS=7
LOG_DIR=/var/log/app

配置最佳实践

开发环境

php

// config/log.php (开发环境)
return [
    'default' => 'file',
    'type_channel' => [],
    'trace_source' => true,
    'console' => true,           // 控制台实时查看
    'channels' => [
        'file' => [
            'driver' => File::class,
            'options' => [
                'storageDays' => 3,       // 短保留期
                'fileSize' => 5242880,    // 5MB 便于查看
                'json' => true,
            ]
        ],
    ],
];

生产环境

php

// config/log.php (生产环境)
return [
    'default' => 'file',
    'type_channel' => [
        'error' => 'error',             // 错误日志单独存储
        'critical' => 'error',
    ],
    'trace_source' => true,
    'console' => false,                 // 关闭控制台输出
    'channels' => [
        'file' => [
            'driver' => File::class,
            'options' => [
                'storageDays' => 30,     // 长保留期
                'maxFiles' => 100,       // 允许更多文件
                'fileSize' => 52428800,  // 50MB 减少文件数
                'json' => true,          // 结构化便于分析
            ]
        ],
        'error' => [
            'driver' => File::class,
            'options' => [
                'storageDays' => 90,     // 错误日志保留更久
                'log_dir' => BASE_PATH . '/runtime/logs/error',
            ]
        ],
    ],
];