常见问题

高频问题速查表。每条给出「先看什么」与对应章节;更细的原理请进对应文档。

本页导航

安装

问题处理
/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 404slug 是否撞了 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

问题处理
越界页码返回空页 2001.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 逐项隔离,见运维:性能

还不行?

  1. 先看 var/log/php-error.log、PHP-FPM 慢日志与 MySQL 慢日志,拿到具体报错/指纹再动手。
  2. 在论坛发帖,附上:版本号、php -l 结果、复现 URL、相关日志片段(不要贴密钥)。
  3. 提交 issue 时按 RELEASE.md 的口径写清根因、判据与验收,便于复现。