排错手册

排错时先判断问题属于路由、模板、数据库、缓存、权限、资源还是环境配置。

一、路由存在但访问 404

检查顺序：

1. 路由列表中是否存在目标路由。
2. 模块或插件是否启用。
3. ServiceProvider 是否加载。
4. 当前主题是否有对应模板。
5. 是否需要默认主题模板回退。
6. 是否存在缓存未清理。

路由存在不代表页面一定能渲染，模板缺失也可能导致访问失败。

二、模板不生效

检查：

• 后台栏目配置的模板文件名。
• 当前主题目录是否存在该模板。
• 是否清理模板缓存。
• 是否把模板写成 Blade。
• 是否写死了固定主题路径。

前台页面布局差异优先通过主题模板和后台配置解决。

三、后台菜单不显示

检查：

• 模块或插件 manifest 是否声明菜单。
• 是否执行同步。
• 菜单权限是否存在。
• 当前管理员角色是否拥有权限。
• 后台菜单缓存是否清理。
• 插件是否启用。

四、资源 404

检查：

• 资源是否已经发布到 public。
• 模板里是否使用正确资源标签。
• 是否写死了默认主题路径。
• Web 根目录是否指向项目 public。
• 浏览器缓存是否还在读取旧版本。

五、数据库导入失败

常见原因：

• 目标库版本不匹配。
• 表前缀不一致。
• 表结构缺字段。
• SQL 文件被错误转码。
• 二进制或十六进制数据导出格式异常。
• 导入目标库不是当前站点使用的库。

处理时先定位错误行和表名，再判断是结构问题还是数据问题。

六、外链栏目不跳转

检查：

• 栏目类型是否为外链。
• 外链地址是否完整。
• 前台导航是否使用统一栏目 URL。
• 栏目元数据缓存是否清理。
• 主题是否自己拼接栏目路径。

七、插件启用无效

检查：

• 插件目录和 plugin.json 是否正确。
• ServiceProvider 是否注册。
• 依赖模块是否启用。
• 资源是否发布。
• 权限和菜单是否同步。
• 插件运行时缓存是否清理。

八、排错记录

每次线上排错建议记录：

• 问题 URL。
• 当前代码版本。
• 当前数据库版本。
• 关键错误日志。
• 已执行的清理和同步命令。
• 最终原因和修复文件。