夸克影院主题（kuakebacn）使用说明

版本：1.0.55｜ 作者：kuakeba.cn ｜ 宿主：社区（community）

暗黑影院风格主题：纯黑背景、#dc2626 红色强调、Geist 字体、胶囊按钮与卡片悬停动效，源自 aipan-thinkphp 视觉语言。

⚠️ 重要：安装会清空社区数据

首次安装 / 重装本主题时，会自动清空社区的原有分类、文章及关联数据（回复、点赞、收藏、付费、举报、版主、关注等 10 张表），并把自增 ID 回归 1，便于「夸克影视采集」在干净序列上重新建库。

• 升级（更新）主题不会清空，数据保留。
• 需要强制重清时：后台「应用中心 → 夸克影院主题 → 卸载」→「安装」。
• 卸载后再安装会重新清空，操作前请先备份数据库。

一、安装与启用

1. 把 themes/kuakebacn 目录整体上传到项目 themes/ 下。
2. 后台「应用中心 → 模板主题 → 夸克影院主题 → 安装」，然后「启用」。
3. 主题依赖「社区」（community）宿主插件，需先安装并启用。

同一站点（host）同一时间只允许启用一个主题；切换主题会自动停用其它同 host 主题。

启用确认

点击「启用」会先弹出确认框：

本主题具有专属限制，启用后会清空已有分类和文章，请悉知！

• 点「确认」：清空已有分类与文章后正式启用。
• 点「取消」：不做任何改动，主题保持未启用。
• 已启用状态再次点击启用不会重复清空。

主题配置入口

启用后，后台左侧「插件列表」下会自动出现「主题配置」菜单：

• 点击直达本主题的配置弹窗（等同「应用中心 → 模板主题 → 夸克影院主题 → 配置」）。
• 停用主题或切换到其它主题时，该菜单自动移除。
• 若菜单未出现，重新启用一次主题即可重新写入。

二、页面结构

顶部影片菜单样式与首页导航一致：默认灰色，选中项为红色。

三、界面截图

前台首页（轮播大图 + 影片列表）


前台影片栏目（Top250）


前台影片详情


前台文章详情


后台「模板主题」列表


后台主题配置弹窗


四、配置项

后台「应用中心 → 夸克影院主题 → 配置」，按用途分组：

站点信息

SEO 关键词 / 描述

搜索引擎站长验证

填写各平台「站点验证」提供的 content 值，前台 head 会自动输出对应 meta：

首页幻灯片

示例：

46|https://example.com/hero-a.jpg
45|
44|

• 第一行：文章 46，使用指定大图
• 后两行：文章 45 / 44，无图时自动使用文章的海报（thumb_url / 正文首图 / kb-hero-img 横版大图）
• 随机轮播只选有横版大图的文章（竖版海报放大模糊），显式配置的文章无图时会回退海报以保证生效

统计 / 单页 / 备案

五、SEO 能力（内置，自动生效）

• <title> 按「页面标题 - 副标题 - 站点名」规则拼装，避免空后缀产生孤立分隔符
• 每页输出 keywords（有条件）、description、rel=canonical（自动清理 utm_*/spm/from 等追踪参数，非有效分页归一）
• robots / googlebot（index,follow,max-image-preview:large,...）、百度 applicable-device、360/IE renderer+X-UA-Compatible
• Open Graph + Twitter Card（类型、标题、描述、图片）
• JSON-LD 结构化数据：WebSite+SearchAction+Organization、列表页 ItemList、详情页 Movie/WebPage、BreadcrumbList
• 分页 rel=prev / rel=next（仅有效分页输出）
• 全站唯一 <h1>，标题层级规范（轮播标题 h2、区块标题 h1、卡片标题 h2）
• 可见面包屑导航（aria-label 语义化）

首页地址规范化（主域名直出）

避免首页被搜索引擎按「主域名 /」和「/community.html」两个地址重复收录：

依赖与边界

• 主域名直出依赖名为 homepage 的已启用插件（提供 home() 方法）；未启用时 / 会回退为跳转 /community.html。
• 本主题对上述规范化全部在主题层完成，未改动 plugins/community 插件与宿主核心。因此升级 community 插件不会影响这部分逻辑。
• 若要在整站层面（含 PHP 端跳转落地页，如登录成功回跳、删帖后跳转）彻底去尾巴，需由 community 插件自身支持或在其配置中调整首页路由，本主题不代为实现。
• 老地址 /community.html 仍可正常访问（无死循环），保证既有外链不失效。

六、更新与部署

1. 覆盖上传 themes/kuakebacn 到服务器。
2. 后台「应用中心 → 夸克影院主题 → 更新」。
3. 若直接覆盖未走后台更新，请手动清理缓存：

  - 删除 runtime/theme_front/kuakebacn/

  - 清空 runtime/temp/、runtime/cache/

  - 重启 PHP（清理 OPcache），并同步 static/theme.css 到 public/static/kuakebacn/theme.css

主题静态资源会随启用/更新自动同步到 public/static/kuakebacn/，前台以该目录为最终生效文件。

七、常见问题

1. 主题启用了但前台样式没变？

检查 public/static/kuakebacn/theme.css 是否与 themes/kuakebacn/static/theme.css 一致；若不一致重新同步并清 runtime/theme_front/kuakebacn。

2. 首页 502 / 访问异常？

本地测试常见原因：hosts 未指向 127.0.0.1，且系统代理（Clash 类）未对本地域名放行，请求被代理转发导致 502。请在 hosts 加入 127.0.0.1 admin.zz，并在代理客户端把本地域名设为 DIRECT。

3. 升级主题后想从 ID 1 重新建库？

主题升级不清数据。需强制重清时：卸载主题 → 重新安装（首次安装自动清空并回归 ID1），然后再运行「夸克影视采集」。

4. 首页轮播不显示 / 显示旧文章？

检查配置 herotopicids 引用的文章 ID 是否仍存在（清库后 ID 会变化）；文章需为「已发布」状态。随机模式仅展示带横版大图的文章。

5. 访问首页时地址栏出现 community.html 尾巴？

本主题已把站内首页链接统一指向 /。若仍出现尾巴，依次检查：

• homepage 插件是否已安装并启用（/ 由它直出首页，未启用时会回退为跳转 /community.html）；
• 是否直接访问了老地址 /community.html（该地址仍可访问，属预期行为，页面内链接不会再指向它）；
• 清缓存：删 runtime/theme_front/kuakebacn/ 与 runtime/temp/。

6. 升级 community 插件后尾巴会复现吗？

不会。本主题的首页地址规范化全部在主题层实现（模板链接、底部 tabbar 预处理、排行榜入口字面量），未改动 plugins/community 插件，升级插件不影响这部分。

需要注意的只是相反方向：community 插件自身发起的 PHP 端跳转（登录成功回跳、删帖后跳转等）仍会落到 /community.html，这属于插件行为，主题不代为实现。

版本历史

版本号规范：统一三段式 1.0.NN，第三段固定保留两位（如 1.0.27、1.0.28），依次递增不跳号。