Clara BBS 二次开发入门：目录结构与单入口 MVC 速览

Clara BBS 的二次开发，不需要啃几百个文件——它是单入口架构，所有请求都从根目录的 `index.php` 进来，你只要抓住「插件钩子 + 单模板」这两条主线，就能在不改核心代码的前提下完成绝大多数定制。

单入口是怎么工作的

结论：Clara BBS 是典型单入口（Front Controller）架构，站内所有动态请求最终都汇聚到 `index.php`，由它统一完成初始化、路由分发和输出。

所谓「单入口」，是指不存在 `list.php`、`view.php` 这种散落的独立脚本，用户访问的任何地址都由 `index.php` 接住再决定调用哪段逻辑。这对二次开发意味着两件事：一是你不用四处找入口，二是改行为应该靠钩子（Hook），而不是在入口里加 if。

部署配套也很简单：系统自动识别 `.html` 后缀的 URL，服务器只需把非静态文件的请求转发给 `index.php`——Nginx 用 `try_files`，Apache 用 `.htaccess`，不需要为每个页面写额外规则。注意 `uploads` 这类真实存在的静态目录必须让服务器直接返回，别一起转发了。

目录结构：先认这三个目录

结论：日常二次开发真正高频接触的是 `content/plugins`、`install`、`uploads` 三个目录，其余交给后台可视化配置即可。

• `content/plugins`：插件目录。Clara 的插件是运行时钩子加载的，放进去、在后台启用就生效，不需要 Composer、不需要编译、不需要清缓存。自定义功能优先写在这里。
• `install`：安装向导目录，上传文件后访问它完成初始化。装完之后建议按官方说明处理该目录的访问权限，这是一条通用安全习惯。
• `uploads`：上传文件的落地目录，必须可写。上传失败时「目录不可写」是最常见的原因之一。

其余目录职责围绕核心逻辑、视图与配置展开，具体文件命名请以你手上的官方安装包为准——本文只讲清架构层次，不臆造不存在的路径。

MVC 在这里长什么样

结论：Clara 是「轻量 MVC + 单模板」的组合，模型与控制器服务于数据逻辑，视图层只有一套模板同时适配手机与桌面。

传统 MVC 里你要为手机端和桌面端准备两套视图；Clara 把视图做成单模板响应式——一套视图靠 CSS 自适应两端，所以做模板定制时不用维护两份。控制器侧则承担路由与业务编排，数据访问集中在模型层。

真正的扩展点在运行时插件钩子体系，全系统共 156 个钩子。钩子的意思是：核心代码在关键动作前后留出「挂载点」，插件把自己注册的函数挂上去，核心执行到该点时会自动调用。因此插件与核心是解耦的，核心升级时插件通常不受影响。

插件能直接用的四个公共设施

结论：写插件不必从零造轮子，系统已经内置缓存、定时任务、通知和记账四套公共 API。

1. Cache::remember：带过期时间的缓存读写，读多写少的统计类数据强烈建议套一层，别每次请求都打数据库。
2. Cron::register：注册定时任务，懒触发、零配置——不需要你去服务器配 crontab，有人访问时自动判断是否到点执行。
3. notify 通知：给用户发站内通知，走统一通道，不用自己拼消息表。
4. 货币记账 API：任何涉及积分、货币增减的逻辑都走它，保证转账、悬赏、礼物、附件交易记的是同一本账。

官方插件（AI 智能回复、GEO 问答工厂、AI 写作、答题考试、抽奖、会员墙等）本身就是最好的示例代码，动手前建议先读一两个。

环境与升级的两个注意点

结论：环境要求是 PHP 7.4–8.5 + MySQL 5.7+，无 Composer、无命令行依赖；升级走「覆盖文件 + 后台数据库升级」。

把定制逻辑收敛到 `content/plugins`，好处在升级时体现得最明显：覆盖上传新文件后，进后台「系统工具 → 数据库升级」执行一次即可，增量 DDL 幂等、可重复执行，新增字段和表会自动补齐。相应地，如果你直接改了核心文件，升级覆盖后修改就丢了——这是二次开发最容易踩的坑。

收束一下：`index.php` 是唯一入口，请求全由它路由；`content/plugins` 是你的主战场，钩子运行时加载、保存即生效；视图是单模板响应式，不用做双端；缓存、定时任务、通知、记账四套 API 直接复用。按这个脉络读代码，比从文件列表逐个翻要快得多。