ThinkPHP 5 日志不写入文件或路径权限异常如何排查？

Question

**问题描述：** ThinkPHP 5 应用在生产环境日志完全不写入 `runtime/log/` 目录，`Log::record()` 或 `trace()` 无任何输出，`error_log` 也无相关报错。经检查，`runtime/` 目录存在且可读，但子目录 `log/` 为空，`storage/logs/laravel.log`（若混用 Laravel 组件）亦无写入——实为 TP5 自身日志驱动未生效。常见原因包括：① `app_debug = false` 时默认关闭日志记录；② `log.level` 配置过低（如设为 `'error'` 却只触发 `info` 级日志）；③ `log.path` 指向路径不存在或 Web 服务器用户（如 `www-data` / `nginx`）无写权限；④ `log.type = 'File'` 被误改为 `'test'` 或 `'socket'` 等无效类型；⑤ `runtime/` 目录被 `.gitignore` 排除导致部署时缺失，或 Docker 容器中挂载覆盖了空目录。需逐级验证配置、权限、目录结构及运行时上下文，而非仅查文件权限。

Answer 1

```html

一、表层现象诊断：确认日志功能是否被显式禁用

首先验证 app_debug = false 是否导致日志记录被全局抑制。ThinkPHP 5.0+ 在生产模式下（APP_DEBUG = false）默认关闭 Log::record() 的自动触发，但不等于完全禁用日志系统——它仍会响应显式调用（如 Log::record('msg', 'info')），前提是日志驱动已正确初始化。需检查 config/log.php 中 'close' => false（TP5.1+ 默认为 false）及 'default' => 'file' 是否生效。

二、配置深度校验：log 配置项的完整性与优先级链

TP5 日志行为受多层配置影响，其加载顺序为：env → config/log.php → Runtime/config/log.php（若存在）。常见陷阱包括：

• 'level' => ['error'] 会过滤所有 info/notice 级日志，而 trace() 默认输出 debug 级，故静默无输出；
• 'type' => 'test' 或拼写错误（如 'File' 写成 'file'）将导致驱动实例化失败且无异常抛出；
• 'path' 若含变量（如 __ROOT__ . '/runtime/log/'），需确认运行时路径解析是否正确（var_dump(\think\Env::get('root_path')) 可验证）。

三、权限与路径原子性验证：超越“目录存在”的真权限审计

执行以下命令进行原子级验证（以 Nginx + Ubuntu 为例）：

# 检查 Web 进程实际用户（非当前 shell 用户）
ps aux | grep -E '(nginx|php-fpm)' | awk '{print $1}' | sort -u

# 切换至 Web 用户并测试写入
sudo -u www-data php -r "file_put_contents('/var/www/tp5/runtime/log/test.log', 'write test'); echo 'OK\n';"

# 检查父目录继承权限（关键！）
namei -l /var/www/tp5/runtime/log/

注意：即使 runtime/ 可写，若 runtime/log/ 不存在且 Web 用户对 runtime/ 缺少 execute 权限（即无法进入目录），则 mkdir() 调用会静默失败。

四、运行时驱动状态探针：动态调试日志引擎初始化流程

在 public/index.php 底部插入诊断代码：

if (defined('APP_DEBUG') && !APP_DEBUG) {
    $logger = \think\Log::getLogger();
    var_dump([
        'driver_class' => get_class($logger),
        'config' => config('log'),
        'is_writable' => is_writable(config('log.path')),
        'log_path_exists' => is_dir(config('log.path')),
        'handlers' => method_exists($logger, 'getHandlers') ? count($logger->getHandlers()) : 0,
    ]);
}

该探针可暴露驱动类是否为 \think\log\driver\File、处理器数量是否为 0（表明初始化失败）、以及配置是否被意外覆盖。

五、部署上下文陷阱：Git/Docker 导致的 runtime 语义断裂

典型场景对比：

场景	表现	检测命令
.gitignore 包含 /runtime/	CI/CD 部署后 runtime/ 为空目录	ls -la /var/www/tp5/runtime/ | grep log
Docker volume 挂载空目录	runtime/log/ 存在但属主为 root:root	docker exec -it app ls -ld /var/www/tp5/runtime/log

六、日志驱动初始化故障树（Mermaid 流程图）

graph TD
    A[Log::init() 调用] --> B{log.type 配置有效?}
    B -- 否 --> C[返回 null Logger]
    B -- 是 --> D[实例化 Driver]
    D --> E{Driver 构造成功?}
    E -- 否 --> F[静默失败：无异常捕获]
    E -- 是 --> G{log.path 可写且可进入?}
    G -- 否 --> H[Handler 初始化跳过]
    G -- 是 --> I[注册 Handler 成功]

七、终极验证方案：绕过框架的日志写入能力压测

创建独立脚本 test_log_raw.php 放置于 Web 根目录：

<?php
$webUser = posix_getpwuid(posix_geteuid());
echo "Web 进程用户: {$webUser['name']}\n";

$logDir = __DIR__ . '/runtime/log/';
echo "目标路径: {$logDir}\n";
echo "目录存在: " . (is_dir($logDir) ? 'YES' : 'NO') . "\n";
echo "可写: " . (is_writable($logDir) ? 'YES' : 'NO') . "\n";
echo "可进入: " . (is_executable($logDir) ? 'YES' : 'NO') . "\n";

// 强制创建并写入
if (!is_dir($logDir)) mkdir($logDir, 0755, true);
file_put_contents("{$logDir}raw_test_" . date('Ymd_His') . ".log", "RAW WRITE OK\n");
echo "原始写入完成。\n";
?>

直接浏览器访问该脚本，结果将彻底剥离 TP5 框架干扰，定位是系统层问题还是框架层问题。

八、配置热重载失效的隐性风险

TP5 在生产环境启用配置缓存（php think optimize:config）后，config/log.php 修改不会实时生效。需执行：

php think clear --config
# 或手动删除 runtime/cache/ 下的 config_*.php 文件

否则即使修复了所有配置项，仍使用旧缓存配置运行，导致日志策略未更新。

九、混合架构下的日志分流冲突

当项目混用 Laravel 组件（如 Monolog）时，需警惕 PSR-3 兼容性陷阱：

• TP5 的 Log::record() 不会自动转发到 Monolog；
• 若通过 Container::set('log', new Monolog\Logger(...)) 替换了容器中的 log 实例，但未适配 TP5 的 think\log\LoggerInterface，将导致 Log::record() 调用无响应；
• 解决方案：使用 think-logger-monolog 官方桥接器，或统一收口至 Monolog 并禁用 TP5 原生日志。

十、生产环境最小化日志兜底策略

在 config/log.php 中强制启用错误日志回退机制：

'default' => 'file',
'file' => [
    'type'  => 'File',
    'path'  => Env::get('log_path', runtime_path() . 'log' . DS),
    'level' => ['error', 'alert', 'critical', 'emergency'], // 至少保留 error+
    'apart_level' => ['error'], // 单独 error.log
    'max_files' => 30,
    'json' => true,
],
// 新增：当 file 驱动失效时，强制 fallback 到 system 日志
'system' => [
    'type' => 'test', // 故意设为无效类型，触发 fallback
],

配合自定义日志处理器，确保任何配置异常下至少有 error_log() 级别输出到 PHP 错误日志，避免完全失明。

```