第20章 Flarum 常见问题排查与解决指南
版本：2.x 排查问题
如果 Flarum 安装失败或运行不符合预期，首先请再次确认你的环境是否满足系统要求。如果缺少 Flarum 运行所需的条件，需要先补齐这些再谈其他。
接下来，花几分钟在支持论坛和issue tracker上搜索一下。说不定已经有人报告过这个问题，修复方案可能已经可用，或者正在路上。如果你仔细搜索后仍然一无所获，那就该动手排查了。
第 0 步：开启调试模式
生产环境请跳过这些调试工具很有用，但可能暴露不该公开的信息。
在测试或开发环境中使用没有问题，但如果你不确定自己在做什么，在生产环境中请跳过这一步。
继续之前，先开启 Flarum 的调试工具。用文本编辑器打开 config.php，把 debug 的值改为 true 并保存。这样 Flarum 会显示详细的错误信息，帮你了解问题出在哪里。
如果你一直看到空白页，而上面的修改没有帮助，请尝试在 php.ini 配置文件中把 display_errors 设为 On。
第 1 步：常见修复方法
很多问题都可以通过以下方式解决：
- 清除浏览器缓存
- 用
php flarum cache:clear清除后端缓存 - 用
php flarum migrate确保数据库已更新 - 确保管理后台中的邮件配置正确：无效的邮件配置会导致注册、重置密码、更改邮箱和发送通知时出错
- 检查 config.php 是否正确。比如确认使用的 url 是否正确（https 与 http 的区别、大小写在这里都很重要！）
- 另一个可能的罪魁祸首是自定义页头、自定义页脚或自定义 LESS。如果问题出在前端，可以先在管理后台的「外观」页面暂时移除这些内容试试
另外，查看 php flarum info 的输出，确认没有明显异常的地方。
第 2 步：复现问题
尝试让问题再次出现，并仔细观察它发生时你在做什么。它是每次都出现，还是偶尔出现？试着改动一个你认为可能相关的设置，或者改变操作的顺序，看看问题是否只在某些条件下出现，而在其他条件下不出现。
如果你最近添加或更新了某个扩展，先暂时禁用它，看看问题是否随之消失。同时确认所有扩展都与你当前使用的 Flarum 版本兼容——过期的扩展可能引发各种问题。
排查过程中，你可能会灵光一现，找到问题原因并自行解决。即便没有，你也多半会收集到一些有价值的线索，等你提交 bug 报告时，这些线索能帮我们更快弄清楚发生了什么。
第 3 步：收集信息
如果你觉得自己解决不了这个问题，那就该认真收集数据了。请到以下几个地方查找错误信息或其他相关线索：
- 页面上的实际报错信息
- 浏览器控制台（Chrome：更多工具 -> 开发者工具 -> 控制台）
- 服务器错误日志（如 /var/log/nginx/error.log）
- PHP-FPM 错误日志（如 /var/log/php8.x-fpm.log）
- Flarum 自身的日志（storage/logs）
把所有报错信息复制到一个文本文件里，并简单记录错误发生的时间、当时你在做什么等。务必写下你观察到的规律：什么情况下问题会出现、什么情况下不会。同时尽量详细地补充服务器环境信息：操作系统版本、Web 服务器版本、PHP 版本及其运行方式等等。
第 4 步：准备报告
收集完所有能找到的信息后，就可以提交 bug 报告了。请按照「报告 Bug」中的说明操作。
如果提交报告后你又发现了关于这个问题的新情况，请在原帖底部补充相关内容。即使你已自行解决了问题，也建议提交一份报告，因为其他用户可能也会受益于你的解决方案。如果你找到了临时解决办法，请务必一并说明。
