常见问题与排错

一、安装相关

访问 /install/ 提示「已安装」

删除 install/install.lock 后重新访问即可。重装前请务必备份数据库。

数据库连接失败

• 确认 MySQL 服务已启动、端口未被占用

• 确认账号有建库权限

• MySQL 8.0 请确认已创建对应账号并授权，caching_sha2_password 认证方式在部分 PHP 版本下需要改用 mysql_native_password

• 主机填写 localhost 失败时，换成 127.0.0.1

安装到一半卡住

看 runtime/log/ 下当天的日志。常见原因是某个 CREATE TABLE 因表已存在而失败，删除对应表或清空数据库后重试。

二、页面打不开

除首页外全部 404

伪静态规则没生效。检查：

1. Nginx / Apache 是否加载了 rewrite 模块

1. .htaccess 是否被允许（Apache 需 AllowOverride All）

1. 后台 → SEO 设置 → 地址规则是否与服务器规则匹配

所有子页面都渲染成首页

典型的路由前缀匹配问题：语言前缀路由（<lang> 这种单变量路由）注册在了具体路由之前，把深层地址全吞掉了。

正确做法：具体路由在前、单变量兜底路由在最后，并对单段语言路由加 completeMatch(true)。

模板报「模板文件不存在」

• 传给引擎的模板名必须以 / 开头，否则会拼接控制器目录名

• 检查 theme/<当前主题>/ 下是否真有该文件

• 主题目录名与后台「模板管理」中记录的名称是否一致

图标全部空白

不要使用 am-icon-* 类名 —— Amaze UI 的字体路径是坏的。请统一使用 FontAwesome 6：<i class="fa-solid fa-house"></i>。

三、后台相关

列表全是空的

优先级从高到低排查：

1. 站点上下文失效：会话里的 admin_site_id 指向了已删除的站点 → 整个后台按不存在的 site_id 过滤。此时切换或重新选择站点即可恢复。

1. 数据语言：后台列表按「数据语言」过滤（?data_lang=），切到某个还没数据的语言会显示空列表。

1. 真的没数据：确认筛选条件、时间范围。

权限节点 / 栏目树只显示一行

树形列表套了分页。树形模式必须一次性取全量再交给 cms_tree() 渲染。

开关关掉之后保存不生效

浏览器对未勾选的 checkbox 不提交该字段，服务端只看到「键不存在」，无法区分「用户关掉了」与「字段没渲染」。

正确实现：开关渲染成「同名 hidden=0 + 复选框 value=1」；保存端对布尔字段用 array_key_exists() 判定，缺键保持原值，绝不写 ?? 0。

改了代码 / 清了缓存却不生效

多应用模式下 runtime_path() 会被切到 runtime/<应用名>/。如果自定义缓存用了它，会出现「后台写一份、命令行读另一份」的情况。自定义缓存请显式使用项目根 runtime/<你的名字>/。

另外，opus 之类的字节码缓存若开启，重启 PHP-FPM 才能生效。

列表 ID 列竖排显示

列宽自适应没生效，多为自定义了 width 过小。清掉自定义列宽（列设置里恢复默认）即可。

四、内容与模板

文档保存后前台没变化

• 检查是否命中缓存：后台 → 运维工具 → 清理缓存

• 检查内容是否处于「草稿 / 待审核」状态

• 多站点下确认前台访问的是同一个站点

列表页筛选没生效

• 模型字段是否勾选了「前台筛选」

• 筛选参数是否被伪静态规则吃掉（带查询参数时注意 ? 之后的参数是否被 rewrite 丢弃）

文章详情页样式错乱

富文本正文一般需要 {$content.content|raw} 输出，且容器要有 word-break 与图片最大宽度限制：

.article-body img { max-width: 100%; height: auto; }
.article-body { word-break: break-word; }

五、上传相关

所有本地上传都 500

检查上传逻辑是否在 move() 之后再调用 getMime() / getSize()。移动临时文件后再取元数据会抛 SplFileObject::__construct(): Failed to open stream。元数据必须在 move() 之前取。

上传图片后不显示

• 检查 public/storage/ 目录权限

• 检查伪静态是否把 /storage/... 也重写到了 index.php

• 用 curl 直接请求图片地址看返回码

用 curl 上传时请求挂死

Windows 下 curl -F "file=@/d/xxx.jpg" 这种 MSYS 风格路径会被静默改写。改用 -F "file=@D:/xxx.jpg"。

六、支付相关

签名校验未通过

逐项核对：

1. 用的是支付对接密钥，不是登录密码或软件密钥

1. 参数按 ASCII 升序排列

1. sign、sign_type、a、c、m、s 与空值已排除

1. 回调 URL 里的 & 没有被转成 &

1. 没有对参数做 trim、金额格式化或二次 URL 解码

1. 末尾是直接拼接密钥，不是 &key=密钥

可用文档里的测试向量自检，正确结果应为 beddd35092c3afea54c5218de0872502。

提示「回调地址(return_url)不能为空」

新版接口要求页面支付与 API 下单都必须传 return_url。补齐即可。

已付款但订单还是待支付

• 确认 notify_url 是公网 HTTPS 且路由不会 301/302

• 后台 → 支付日志，看是否收到回调、验签是否通过

• 若回调确实没到，用「订单查询」接口主动补单（后台订单列表有「补单」按钮）

• 查询 act=order 时 status=1 即已支付成功

提示「当前商户无通道可用」

检查套餐是否有效、所选 type 是否存在已启用通道、通道限额与轮询配置。

提示「商户余额不足无法发起支付」

套餐存在费率且手续费余额不足，需先在商户中心充值手续费余额。

七、日志位置

上线前请把 php.ini 的 error_log 移出 Web 根目录，或由 Nginx 屏蔽 .log 文件，避免错误日志被直接下载。