ThinkPHP 8.0正确配置日志通道与级别方法

配置过 ThinkPHP 8.0 日志的开发者应该都遇到过这些困惑——明明代码里写了 Log::debug()，结果日志文件中却没有任何记录；或者 Log::info() 输出了大量无价值信息。问题通常不在业务逻辑本身，而是日志配置的细节没有把握到位。下面将常见误区与正确配置方法逐一说明。

config/log.php 中 level 必须使用数组格式，不可用字符串

许多开发者习惯写成 'level' => 'error' 或 'level' => 'debug,info,error'——但框架只识别数组类型。这类配置会被直接忽略，导致日志走默认行为（通常是 ['error', 'warning', 'info']）。带来的后果就是：Log::debug() 完全不生效，而 Log::info() 却在生产环境意外地持续输出。

• 'level' => ['debug', 'info', 'warning', 'error'] 是开发环境最常用的配置方式
• 'level' => ['error', 'critical', 'alert', 'emergency'] 是生产环境应严格限制的级别
• 空数组 [] 代表关闭当前通道所有日志功能，请谨慎使用
• 级别名称必须统一使用小写，'Error' 或 'INFO' 将被直接跳过，且不会给出任何提示，静默失效

自定义通道必须在 config/log.php 的 channels 中显式注册

例如，你想为支付模块单独创建一个日志通道，调用了 Log::channel('pay')->info('xxx')，却发现对应的日志文件没有生成。极大概率是因为 'pay' 这个通道根本没有在 config/log.php 的 'channels' 数组中声明过。框架只在启动时读取一次配置，运行时通过 Log::extend() 动态注册的通道在 CLI、FPM 或 Swoole 环境下极其不稳定——多请求复用进程时通道可能会直接丢失。

• 通道名称统一使用小写，避免与内置的 'default'、'error' 名称冲突
• 'type' 的值必须首字母大写：'File' ✅，'file' ❌（书写错误不会报错，但配置整体失效）
• 'path' 必须以 / 结尾，例如 runtime_path() . 'log/pay/'，否则路径拼接会出错
• 确保目标目录已存在且 PHP 进程拥有写入权限，否则日志会静默丢失——不会报错，但浪费大量排查时间

apart_level 与 level 是两套独立逻辑，请勿混淆使用

'apart_level' => ['sql'] 这个配置不受 level 控制，但它强依赖 app_debug = true 的设定。很多人设置了 apart_level 却发现 sql.log 一直没有内容——实际上是因为生产环境 APP_DEBUG=false，SQL 日志根本未被触发。需要清晰理解这两套逻辑：

• level 是过滤器：决定哪些级别“可以进入该通道”
• apart_level 是分流开关：将指定级别强行导出到独立文件中（它会绕过 level 的过滤）
• sql 级别仅在调试模式下生效，而 emergency、alert 等标准级别才走 level 判断逻辑
• 修改 apart_level 后，必须清空 runtime/cache/ 目录，否则旧缓存可能导致新配置不生效——这是最容易忽略的细节

通道级别的 level 配置会优先于全局 level

全局配置了 'level' => ['error']，但某个特定通道单独配置了 'level' => ['debug', 'info']——那么这个通道确实会记录 Log::debug() 的日志，即使其他通道完全无法接收。这套机制正是实现“支付日志记录 info 级别、错误日志只接收 error 级别”这一需求的关键。

• 未定义 level 的通道会自动继承全局配置
• 通道级别的 level 只影响该通道自身，不影响其他通道或整个日志分发逻辑
• 不要使用 Log::setLevel() 动态修改级别——它仅作用于默认通道，且对已经初始化的通道完全无效，写了等于白写
• 推荐按环境适配的写法：'level' => env('APP_DEBUG', false) ? ['debug','info','warning','error'] : ['warning','error']

最后提醒一句：在实际配置生效之前，务必执行 php think clear:log 清除缓存。路径权限、大小写规范、数组结构——这三个方面最容易遗漏检查。很多时候问题并非出在代码逻辑，而是配置中的这三个细节没有核对到位。与其反复折腾，不如从一开始就确保配置准确无误。