故障排除 ​

本页聚焦“排错步骤与定位思路”，与“常见问题”不同，这里给出更具体的排查路径。

后台白屏或无内容 ​

1. 确认访问的是 /manage/ 而不是静态文件
2. 基座未构建：在项目目录执行 bun run build
3. 开发模式：检查 config/use.dev.toml 的 vite.dev 与端口

菜单不显示 ​

1. 确认模块已注册在 config/app.toml
2. 执行 php dux menu:sync
3. 检查菜单 name 是否与权限一致

页面加载失败 ​

1. 菜单 loader 路径是否正确（例如 System/Home/index）
2. 页面是否放在 app/模块/Admin 下
3. 访问路径与 loader 映射是否一致

接口 404 或无数据 ​

1. 资源类是否添加 #[Resource]
2. 是否属于 admin 路由组
3. 是否同步了数据库（php dux db:sync）

权限导致看不到菜单或按钮 ​

1. 角色权限是否包含对应 name
2. php dux permission:list 查看权限节点
3. 菜单 name 必须与权限一致

表格列表为空 ​

1. 后端 transform() 是否返回字段
2. 列表接口是否分页（传 pageSize）
3. 前端展示尽量依赖后端输出字段

上传失败 ​

1. 检查系统配置中的上传扩展名与大小限制
2. 确认存储配置有效
3. 检查 public/ 目录下资源是否可访问

操作无效（演示模式） ​

• use.toml 中 app.example = true 会禁止非 GET 请求

缓存与路由异常 ​

• 运行 php dux app:cache 清理缓存
• 重新构建基座（如修改了 web/ 目录）

如果仍无法定位问题，优先查看 data/logs 中的错误日志。