配置过 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 清除缓存。路径权限、大小写规范、数组结构——这三个方面最容易遗漏检查。很多时候问题并非出在代码逻辑，而是配置中的这三个细节没有核对到位。与其反复折腾，不如从一开始就确保配置准确无误。
