写一个 Clara 插件：plugin.php 的完整开发指南

写 Clara 插件不用 Compose、不用编译、不用改核心文件：在 `content/plugins` 下建一个插件目录，写一个 `plugin.php` 作为入口，把回调挂到运行时钩子上，保存即生效——这就是全部工作量。

plugin.php 到底是什么

结论：plugin.php 是 Clara 插件的唯一必需入口文件，负责声明插件信息和挂载钩子，它本身不参与编译、不生成缓存文件。

Clara 是轻量级 PHP 社区系统，运行环境只要 PHP 7.4-8.5 + MySQL 5.7+，没有 Composer 依赖、没有命令行步骤、没有编译缓存层。插件体系走的是运行时钩子加载：系统在渲染和执行流程中预留了 156 个钩子点，插件在这些点注入自己的回调函数。因为不涉及编译产物，你改完 plugin.php 直接刷新页面就能看到效果，不需要清缓存、不需要重启任何服务。

插件的物理位置是 `content/plugins`，每个插件占一个独立子目录。后台「插件中心」负责启用/停用，管理日志里会记录相关操作。

开发一个插件的五个步骤

结论：标准流程是「建目录 → 写 plugin.php → 后台启用 → 前台验证 → 迭代」。

1. 在 `content/plugins` 下新建目录，目录名即插件标识，建议全小写英文。
2. 在目录内创建 `plugin.php`，文件里通常包含三部分：插件元信息（名称、版本、作者、说明）、钩子挂载声明、回调函数实现。
3. 进入后台「插件中心」，找到该插件并启用。
4. 访问对应的前台页面，触发你挂载的那个钩子，验证输出。
5. 不满意就改 `plugin.php` 再刷新——保存即生效，循环极短。

需要强调的是：钩子的具体名称与回调签名，建议直接打开官方插件目录对照源码，比如「复制尾注」「快捷回复」「哀悼模式」这类功能单一的插件，代码短、依赖少，是最合适的入门范本。

钩子怎么选、回调怎么写

结论：先确定「要在哪一步插入行为」，再去钩子清单里找最靠近那个位置的点，而不是先挑钩子再想功能。

插件开发最常见的翻车点是把钩子选得太靠前。比如你要在帖子正文后追加内容，就应该挂在内容渲染完成之后的钩子上；如果挂在数据查询阶段，输出的内容还没生成，自然拿不到结果。

回调函数有三条硬约束：轻量——钩子会在主流程里被频繁触发，别在里面做远程请求或大查询；幂等——同一个钩子可能被多次执行，要在逻辑上防重复插入；可退出——插件被停用后，主流程必须完全不受影响，所以不要在主流程里留下必须依赖插件才成立的假设。

该用公共设施就别自己造轮子

结论：Clara 为插件准备了一套公共设施，缓存、定时任务、通知、货币记账都有现成 API，直接调用即可。

• Cache::remember ——带「取不到就执行并缓存」语义的缓存封装，适合把插件里的重计算结果存起来，避免每次钩子触发都重算。
• Cron::register ——注册定时任务，采用懒触发方式，不需要你在服务器上配 crontab，零配置。
• notify ——统一通知出口，插件产生的提醒能走进站内通知体系。
• 货币记账 API ——涉及积分、货币加减的操作都走这套接口，保证和系统的多货币体系、转账、签到奖励等记账口径一致，别自己直接写数据库字段。

这点很关键：一旦绕过记账 API 直接改余额，后面用户在明细里就会看到对不上的账。

四条必须守住的底线

结论：插件可以扩展功能，但不能破坏系统的安全基线和隐私口径。

输出转义：插入到页面的用户可控内容必须转义，Clara 全站做了输出转义，插件是唯一的漏点。
CSRF 防护：插件自带表单的话，必须带上系统的 CSRF 令牌，否则会被校验拦掉或留下漏洞。
上传白名单：涉及文件上传时要遵守系统的类型白名单和图片二次校验规则，别自己放松限制。
权限与隐私：判断当前用户组权限再输出内容，隐藏版块和权限版块的内容绝不能被插件暴露给游客——GEO 输出的隐私口径也是同理，所有对外输出只含游客可见内容。

排查问题的思路

结论：插件出问题，第一步永远是停用插件看现象是否消失。

改完没反应，先确认插件在「插件中心」是启用状态；现象异常，先停用该插件对比；涉及数据错乱的，检查是不是绕过了记账 API 或缓存了不该缓存的内容。系统级的清理可以走后台「系统工具」，覆盖上传新文件后如需补数据库结构，在「系统工具→数据库升级」执行一次即可。

总的来说，Clara 插件的开发体验核心就是三个词：目录、钩子、公共设施。把 `plugin.php` 写对，钩子选准，缓存/定时/通知/记账用系统现成的，一个插件从想法到生效通常就是几分钟的事。