自定义首页（pagehome）使用说明

插件目录：plugins/pagehome

插件标识：pagehome 作者：kuakeba.cn 版本：1.1.1

适用框架：Zsens Admin（ThinkPHP 6 风格）

可选依赖：社区插件 community（仅「社区首页」「指定单页」两种模式需要）

一、插件简介

「自定义首页」负责接管站点根路径 /，让主域名直接输出首页内容，而不是先 302 跳到 /community.html。

解决的问题：

• 访问主域名时地址栏不再出现 community.html 之类的尾巴；
• 首页只有一份可访问地址，避免同一内容被搜索引擎重复收录；
• 首页内容来源可后台切换，不改代码、不改宿主文件。

插件不建数据表、不注册后台菜单，只在插件管理的「配置」里维护开关与参数。

二、工作原理

2.1 请求链路

GET /  →  宿主路由注册的 / 规则  →  插件注册的路由中间件（Home）
       →  命中条件：插件启用 + GET + 路径为 / + 非社区内容域名
       →  执行 plugins\pagehome\controller\Index::home()
       →  按「首页来源」直接输出内容（或按配置跳转）

未命中时（非根路径、非 GET、插件未启用、渲染异常），中间件直接放行，完全交回宿主原有逻辑，不影响其他页面。

2.2 为什么用中间件

宿主 route/app.php 会先注册 / 规则，插件后注册的同名路由无法覆盖；同时在宿主控制器里做扩展点需要改宿主文件。1.1.1 起改为在插件内注册路由中间件，在控制器执行前接管根路径，因此：

• 宿主文件 app/controller/Index.php 保持原样，零改动；
• 插件停用后立即恢复宿主默认行为；
• 升级宿主程序不会被覆盖。

2.3 不会接管的情况

以下根路径仍按原逻辑处理：

三、安装与启用

1. 将 pagehome 文件夹放入站点根目录的 plugins/ 下；
2. 后台 → 插件管理 → 找到「自定义首页」→ 安装；
3. 安装后进入「配置」，按需选择「首页来源」并保存；
4. 确保插件处于启用状态。

安装与卸载会自动清理游客整页缓存，避免继续输出旧首页。

插件目录内没有数据表，卸载不会删除任何内容；仅恢复 / 的默认跳转行为。

四、配置项说明

后台 → 插件管理 → 自定义首页 → 配置。

4.1 三种首页来源

4.2 回退规则

• 「指定社区单页」所选单页不存在或未发布 → 回退渲染社区首页；
• 「跳转指定地址」未填写有效地址 → 回退渲染社区首页；
• 社区插件未安装或未启用 → 跳转后台登录入口，保证 / 不会 404；
• 渲染过程异常 → 交回宿主默认逻辑。

五、安装后的验证

在服务器上执行（把域名换成自己的）：

curl -I https://www.example.com/

预期结果：

其他页面回归检查：

curl -I https://www.example.com/community.html   # 仍应 200
curl -I https://www.example.com/topic/1.html     # 仍应 200
curl -I https://www.example.com/admin            # 仍应正常跳转登录
curl -I https://www.example.com/no-such-page     # 仍应 404

六、常见问题

6.1 插件已启用，访问 / 仍然跳 community.html

按顺序排查：

1. 插件版本是否 1.1.1 及以上。1.1.0 及更早版本依赖宿主扩展点，而宿主检查的插件名是 homepage，与实际包名 pagehome 不一致，扩展点永远不会命中；
2. 插件是否真正启用。后台插件列表状态需为「已启用」，且配置里「启用自定义首页」为开；
3. 启动缓存是否过期。删除 runtime/plugin_boot.php，再清理 runtime/cache、runtime/temp，重载 PHP（清 OPcache）；
4. 是否还有其他 301/302。检查宝塔站点伪静态、CDN、Nginx 配置里是否有根路径重写规则。

6.2 首页正常了，但点 Logo / 「首页」又出现 community.html

这是主题模板里写死的广场地址，不是插件问题。以 duanju 主题为例，需要把首页入口改成 /：

详情页「更多推荐」指向的是广场列表，不是首页入口，保留 /community.html 即可。

修改主题模板后必须删除 runtime/theme_front/duanju（或在后台重新保存一次主题），让合并模板重建，否则页面仍用旧缓存。

6.3 站点使用内容域名（如 video.example.com）

这类域名的 / 由社区插件直接输出对应内容模型，插件会主动跳过，不会覆盖。仅主域名 / 受影响。

6.4 首页带查询参数会怎样

根路径匹配只看路径，不看查询串。/?from=xxx 仍会被接管；跳转模式下可通过「保留查询参数」决定是否携带。

6.5 开启后 CDN / 整页缓存仍返回旧页面

插件安装、卸载时会清理游客整页缓存；手动调整配置后如仍见旧页面，请在后台清理缓存，并刷新 CDN 缓存。

6.6 插件停用后会怎样

停用即恢复宿主默认行为：/ 通常 302 跳转社区首页。已收录的根地址不受影响，只是地址栏会再次出现 community.html。

七、目录结构

plugins/pagehome/
├── plugin.json                插件元信息
├── PagehomePlugin.php         插件入口（配置项、默认值、安装/卸载钩子）
├── routes.php                 前台路由中间件注册
├── controller/
│   └── Index.php              首页渲染（三种来源与回退逻辑）
└── middleware/
    └── Home.php               根路径接管与放行判断

八、注意事项

1. 不要修改宿主文件。本插件通过中间件实现，app/controller/Index.php、route/app.php 均保持原样；
2. 插件 1.1.1 使用路由中间件，需宿主支持 app()->middleware->route()（Zsens Admin 3.0 默认支持）；
3. 站点部署在子目录时，根路径为子目录下的 /，链接统一使用 / 的主题改动需按实际部署路径调整；
4. 多域名站点若将内容域名解析到同一站点，请确认内容域名已在社区「内容模型」中正确绑定，否则插件会按主域名处理其根路径。

九、更新记录

1.1.1

• 改为插件内路由中间件接管 /，不再依赖宿主扩展点，宿主文件零改动；
• 修复宿主扩展点检查插件名 homepage 与实际包名 pagehome 不一致导致插件启用后 / 仍 302 到 /community.html 的问题；
• 新增内容域名根路径跳过逻辑，避免覆盖社区聚合页。

1.0.0

• 支持社区首页、指定单页、跳转地址三种首页来源；
• 支持 301 / 302 跳转、保留查询参数；
• 安装 / 卸载自动清理游客整页缓存。