高频问题速查表。每条给出「先看什么」与对应章节;更细的原理请进对应文档。
本页导航
安装
| 问题 | 处理 |
|---|
/install/ 403 | 伪静态 deny 规则把安装目录也拦了;装完再锁死,见安装 |
500 Unknown column 'c.words' | 老库缺列,ALTER TABLE ye_contents ADD COLUMN words INT UNSIGNED NOT NULL DEFAULT 0; 并回填 |
| 前台文章 404、后台正常 | 伪静态没生效,按Nginx 配置修正并重载 |
| 上传附件失败 | uploads/ 属主/权限,见目录权限 |
| 数据库连接失败 | 先用 mysql 客户端实测账号,再核对 config.inc.php 常量 |
| 装完不知道做什么 | 快速开始 |
主题与首页
| 问题 | 处理 |
|---|
| 换了主题首页没变 | 删 var/home-static/index.html(含 /en/)重新烘焙,并清页缓存 |
模板不存在 / 首页空白 | 主题缺 views/layout.php;内核会回落 yecha 并写日志,后台切回默认主题 |
| 改了 CSS 不生效 | 用 View::asset() 输出带 ?v=<mtime> 的 URL;别手写固定版本号 |
| 暗色模式文字看不清 | 补 html.dark 分支的面板/表格/代码块配色,见主题开发 |
| 侧栏顺序想调 | 后台「页面布局」,或 theme.sidebar_mode,见使用手册 |
后台与登录
| 问题 | 处理 |
|---|
| 登录后立刻跳回登录页 | 检查 fastcgi_param HTTPS on、site.url 与实际域名,清浏览器 Cookie |
| 保存设置 500 | 临时开 DEBUG 看具体错误;php -l 改动文件;确认迁移已执行 |
| 表单提交被拒 | 写操作必须带 Csrf::field() 并在处理端 Csrf::check() |
| 某个后台模块不见了 | 内置插件 notes / poly 停用时会从导航隐藏;第三方插件看 plugin.<id>.enabled |
| 忘记管理员密码 | 用 tools/admin-pass.php 或后台用户模块重置(先备份库) |
内容与多语
| 问题 | 处理 |
|---|
| 文章 URL 404 | slug 是否撞了 Router::RESERVED;状态是否 publish;deleted_at 是否被误设 |
| 删了文章,分类数字没变 | ye_metas.count 是预计算列,删除后要重算 |
/en/xxx.html 显示中文 | 译文不存在或非 publish,基准语言回退是预期行为,见多语言 |
| 点链接跳回中文 | 链接漏语言前缀,统一用 ui_lp() / Poly::termUrl() |
| 分类名在英文页是中文 | 补 ye_metas.names_i18n,见术语多语 |
| AI 翻译后仍是中文 | 1.2.3 语种校验会拦下并报错;人工修订后勾 manual_override |
/ja/theme 404 | 插件页在其他语言前缀下的既有行为,官网目前只开放中文与 /en,见URL 规则 |
| 正文里的 HTML 被当文本显示 | 正文先转义再渲染,不塞 HTML;特殊版式做主题视图或内核渲染器,见内容规范 |
插件与市场
| 问题 | 处理 |
|---|
| 启用插件报错 | 看迁移是否失败;migrations/ 必须幂等,失败信息在后台直接给出 |
| 停用后数据没了 | 停用只停注册、数据保留;只有卸载 purge=1 才会删表与配置 |
| 云市场装不上 | 只接受 https + SHA-256 校验;检查包结构、plugin.php / theme.json、php -l |
| 自定义路由不生效 | 优先用 pages 清单;Hooks::run('route') 当前内核没有统一触发,见Hooks 现状 |
/mall、/site、/ai 404 | 对应插件未启用时内核分支直接回落 404 |
缓存与升级
| 问题 | 处理 |
|---|
| 改了内容前台没变 | 页缓存 / 区块缓存 / 首页静态件三处逐个清,见运维:缓存 |
/changelog 没更新 | 它是数据库内容页(id 对应 slug=changelog),改 CHANGELOG.md 不会同步;发布时两份都要写 |
| 升级后 500 | 检查待执行迁移 php tools/upgrade.php --component core --dry-run,必要时按回滚恢复 |
| 升级后主题/插件数量对不上 | 目录与清单是否被覆盖;同名主题覆盖前先备份 |
| 回滚后新内容丢了 | 数据库回滚会覆盖回滚点之后的内容;执行前先单独导出新增内容 |
SEO 与 URL
| 问题 | 处理 |
|---|
| 越界页码返回空页 200 | 1.x 已统一改为 404;判据在 Router::pageBeyond(),不要在多处重写 |
| canonical 指到自己 | 检查分页器与总页数是否同源;非法页码不要静默折成第 1 页 |
| sitemap 少页面 | 页面需 type='page'、status='publish'、deleted_at IS NULL |
/docs 与 /docs.html 都能开 | 二者等价(干净 URL 特例);对外统一用一种,避免重复收录 |
/feed 内容不对 | 只取已发布且未软删的 post;检查 published_at |
性能
| 问题 | 处理 |
|---|
| 首页偶发很慢 | 先确认 stats.posts_total 是否存在、Front::postsTotal() 是否走 O(1) 快路径 |
| 分类/标签深翻页 2~10s | 检查 ye_meta_page_bounds 快路径是否命中;1.2.4 起 tw 也已接入 |
| 列表页突然全表扫描 | EXPLAIN 看 ORDER BY 是否用上覆盖索引;术语计数别退回实时子查询 |
| 后台点了「覆盖翻译」站变慢 | 1.2.2 起已是单请求单语言 + 并发锁 + 自动续链;若仍异常,检查是否跑了旧版代码 |
| 慢查询反复出现同一指纹 | 按 instrument → measure → isolate → fix → re-measure 逐项隔离,见运维:性能 |
还不行?
- 先看
var/log/php-error.log、PHP-FPM 慢日志与 MySQL 慢日志,拿到具体报错/指纹再动手。 - 在论坛发帖,附上:版本号、
php -l 结果、复现 URL、相关日志片段(不要贴密钥)。 - 提交 issue 时按
RELEASE.md 的口径写清根因、判据与验收,便于复现。