故障排查指南

故障排查指南

Troubleshooting Guide

常见问题

1. 页面显示空白

可能原因:

  • PHP 错误被隐藏
  • 文件路径错误
  • 权限问题

解决方法:

  1. 检查 PHP 错误日志
  2. 启用错误显示（开发环境）：

``php iniset('displayerrors', '1'); errorreporting(EALL); ``

  1. 检查文件权限

2. 缓存问题

症状: 修改内容后页面未更新

解决方法:

  1. 清除缓存目录：_blog/src/cache/
  2. 如果使用 Redis，清除 Redis 缓存
  3. 检查缓存配置是否正确

3. Redis 连接失败

症状: 日志显示 Redis 连接错误

解决方法:

  1. 检查 Redis 服务是否运行
  2. 检查 REDISHOST</code> 和 <code>REDISPORT 配置
  3. 检查防火墙设置
  4. 系统会自动回退到文件缓存

4. Markdown 文件无法解析

可能原因:

  • 文件编码问题
  • Front Matter 格式错误
  • 文件路径包含特殊字符

解决方法:

  1. 确保文件使用 UTF-8 编码
  2. 检查 Front Matter 格式是否正确
  3. 检查文件路径是否安全

5. 标签页面显示错误

症状: tags.php 或 tag.php 报错

解决方法:

  1. 检查 Markdown 文件的 Front Matter 中 tags 格式是否正确
  2. 确保标签是数组或逗号分隔的字符串
  3. 检查文件权限

6. 评论系统不显示

可能原因:

  • Giscus 未配置
  • 配置错误

解决方法:

  1. 检查 _blog/config.php 或 .env 中的 Giscus 配置
  2. 访问 https://giscus.app 验证配置
  3. 检查浏览器控制台是否有错误

7. 站点地图无法访问

症状: sitemap.php 返回 404

解决方法:

  1. 检查文件是否存在
  2. 检查 Web 服务器配置
  3. 确保 PHP 可以执行

8. 性能问题

症状: 页面加载缓慢

解决方法:

  1. 启用缓存（检查 CACHE_ENABLED）
  2. 使用 Redis 缓存（如果可用）
  3. 检查 CDN 资源加载
  4. 优化 Markdown 文件大小

调试技巧

启用调试模式

在 .env 文件中设置：

DEBUG=true
APP_ENV=development

查看缓存统计

$cache = new CacheService();
$stats = $cache->getStats();
var_dump($stats);

检查路径验证

$validator = new PathValidator(BLOG_ROOT);
$isValid = $validator->validateMarkdownFile($filePath);

日志位置

  • PHP 错误日志：根据 PHP 配置
  • 访问日志：Web 服务器日志
  • 缓存日志：无（缓存操作静默失败）

获取帮助

如果问题仍然存在：

  1. 检查 GitHub Issues
  2. 查看文档
  3. 提交 Issue（包含错误信息和环境信息）
← 返回目录