1. 问题概述

1.1 问题现象

网站部署 WordPress 子比主题并安装 Redis Cache 插件后，自定义头像功能出现异常，具体表现为：

• 用户上传/设置自定义头像后，页面仍显示默认头像；
• 刷新页面时，自定义头像短暂闪烁后立即恢复为默认头像；
• 显示几秒后，转变成破图；
• 多次重新设置头像并清除缓存，问题仍无法解决。

1.2 影响范围

• 所有使用自定义头像的网站用户；
• 适配了子比主题懒加载功能的前端页面；
• 集成 Redis Cache 插件的 WordPress 环境。

2. 问题根源分析

2.1 缓存机制兼容性冲突

子比主题依赖 WordPress 内置的 wp_cache_get/wp_cache_set 函数实现头像缓存，而 Redis Cache 插件会替换 WordPress 默认缓存机制，两者的缓存逻辑未兼容，导致头像缓存无法正确更新和读取。

2.2 懒加载逻辑设计缺陷

主题默认懒加载逻辑为：先渲染默认头像作为 src，再通过 JavaScript 加载真实头像 data-src。当缓存异常时，真实头像 URL 无法被正确获取，最终呈现“闪烁后恢复默认”的现象。

2.3 缓存清除机制不完整

用户更新头像时，主题仅清除 WordPress 内置缓存，未同步清理 Redis 插件的分组缓存，导致 Redis 中旧的头像缓存持续生效。

3. 修复前置准备

3.1 环境要求

• 服务器已部署 WordPress + 子比（zibll）主题；
• 已安装并启用 Redis Cache 插件；
• 具备服务器文件修改权限（FTP/宝塔面板/SSH）。

3.2 文件备份

修改代码前，务必备份目标文件：

/www/wwwroot/www.tyzyj.cn/wp-content/themes/zibll/inc/functions/zib-theme.php

建议将备份文件命名为 zib-theme-backup.php，避免覆盖或误删。

4. 详细修复步骤

步骤 1：定位核心文件

需修改的核心文件路径：

/www/wwwroot/www.tyzyj.cn/wp-content/themes/zibll/inc/functions/zib-theme.php

通过 FTP、宝塔面板或 SSH 工具打开该文件。

步骤 2：修改头像获取函数（zib_get_data_avatar）

操作说明

找到文件中的 zib_get_data_avatar 函数，删除原有代码，替换为以下优化后的代码（核心逻辑：取消缓存依赖 + 差异化懒加载）：

/**
 * 获取用户头像（修复Redis缓存兼容+懒加载闪烁问题）
 * @param string $user_id 用户ID
 * @param string $size 头像尺寸
 * @param string $alt 头像替代文本
 * @return string 处理后的头像HTML代码
 */
function zib_get_data_avatar($user_id = '', $size = '', $alt = '')
{
    $args = array(
        'size'   => $size,
        'height' => $size,
        'width'  => $size,
        'alt'    => $alt,
    );
    
    // 直接获取头像，不使用WordPress内置缓存，规避Redis兼容问题
    $avatar = zib_get_avatar(null, $user_id, $args);
    
    // 仅当开启头像懒加载时，执行差异化逻辑
    if (zib_is_lazy('lazy_avatar')) {
        // 获取用户自定义头像元数据
        $custom_avatar = $user_id ? zib_get_user_meta($user_id, 'custom_avatar', true) : '';
        
        if ($custom_avatar) {
            // 有自定义头像：直接替换src为真实地址，消除闪烁
            $avatar = str_replace(zib_default_avatar(), $custom_avatar, $avatar);
        } else {
            // 无自定义头像：保留懒加载逻辑，使用默认头像占位
            $avatar = str_replace(' src=', ' src="' . zib_default_avatar() . '" data-src=', $avatar);
            $avatar = str_replace(' class="', ' class="lazyload ', $avatar);
        }
    }
    return $avatar;
}

步骤 3：优化头像缓存清除钩子（user_save_custom_avatar）

操作说明

找到文件中 user_save_custom_avatar 钩子的原有代码，替换为以下代码（核心逻辑：同步清除 WordPress+Redis 缓存）：

/**
 * 头像更新时清除全量缓存（兼容Redis）
 * @param int $user_id 用户ID
 * @param int $img_id 头像图片ID
 * @param string $url 头像图片URL
 */
add_action('user_save_custom_avatar', function ($user_id, $img_id, $url) {
    // 清除WordPress内置头像缓存
    wp_cache_delete($user_id, 'user_avatar');
    
    // 若Redis Cache插件已安装，清除头像分组缓存
    if (function_exists('wp_cache_flush_group')) {
        wp_cache_flush_group('user_avatar');
    }
    
    // 预加载新头像，确保下次访问直接读取最新数据
    zib_get_data_avatar($user_id);
}, 10, 3);

步骤 4：保存并上传文件

修改完成后，保存文件并覆盖服务器上的原文件（若通过本地修改后上传，需确保文件编码为 UTF-8，避免语法错误）。

5. 修复效果验证

5.1 前端验证（核心验证）

1. 登录网站后台，进入「用户中心」→「个人资料」；
2. 上传/更换自定义头像，点击「保存」；
3. 刷新页面，观察头像是否直接显示自定义图片（无闪烁、不回退默认）；
4. 清除浏览器缓存（Ctrl+Shift+Delete），重新访问网站，验证头像仍正常显示；
5. 切换不同设备/浏览器访问，确认效果一致性。

5.2 后端代码校验

1. 检查修改后的 zib-theme.php 文件无语法错误（可通过 WordPress 后台「外观→主题编辑器」查看是否报错）；
2. 执行 Redis 缓存手动清理（可选）：通过服务器 Redis 客户端执行 FLUSHDB，验证头像仍能正常加载；
3. 查看服务器错误日志（如 /var/log/php-fpm/error.log），确认无相关报错。

6. 常见问题排查

6.1 修复后头像仍不显示

• 排查方向 1：确认文件路径是否正确（子比主题目录是否为 zibll，服务器域名是否匹配）；
• 排查方向 2：检查自定义头像 URL 是否有效（可直接复制 URL 在浏览器打开，验证图片是否存在）；
• 排查方向 3：禁用其他缓存插件（如 WP Rocket），确认无多重缓存冲突。

6.2 头像仍存在闪烁问题

• 排查方向 1：确认 zib_is_lazy('lazy_avatar') 返回 true（即懒加载功能已开启）；
• 排查方向 2：检查 custom_avatar 元数据是否正确写入（可通过 wp_user_meta 数据表查看用户对应的 custom_avatar 字段）；
• 排查方向 3：清除 CDN 缓存（若网站启用 CDN），避免旧资源缓存。

6.3 Redis 缓存未清除

• 排查方向 1：确认 wp_cache_flush_group 函数存在（Redis Cache 插件版本需≥2.0）；
• 排查方向 2：手动执行 Redis 缓存清理，

7. 注意事项

1. 主题更新风险：子比主题更新时，修改的 zib-theme.php 文件会被覆盖，需在更新后重新应用本教程的修复代码；
2. 测试环境优先：建议先在本地/测试服务器验证修复效果，再部署到生产环境；
3. 权限检查：确保服务器对 zib-theme.php 文件有读写权限（推荐权限：644）；
4. 多环境兼容：若网站使用多服务器集群，需同步更新所有节点的 zib-theme.php 文件；
5. 备份留存：将修改后的 zib-theme.php 文件留存备份，便于后续快速恢复。

8. 总结

本教程通过三个核心优化解决头像显示异常问题：

1. 取消头像获取环节的缓存依赖，规避 Redis 与 WordPress 内置缓存的兼容性冲突；
2. 差异化设计懒加载逻辑，针对“有/无自定义头像”分别处理，消除闪烁问题；
3. 完善缓存清除机制，同步清理 WordPress 和 Redis 缓存，确保头像更新即时生效。

修复后，自定义头像可稳定显示、无闪烁，且与 Redis Cache 插件完全兼容，有效提升用户体验。