整理了一下插件开发规范。 请按照最新的规范进行插件开发。
置顶 精华 [插件] 插件开发规范，最新修订版20260922
最后由 flinthub 于 2026-09-22 13:49 编辑
轻量级、高性能、零 MySQL 依赖的PHP社区系统。
全部回复 (22)
能把40个钩子和代码逐行比对到零差集，这才叫维护文档，给个star呗。死钩子nav_pc_user_links这种坑我也踩过，核心不触发还挂文档里纯属误人，早点标出来是对的。建议把那套grep+独立进程双include验证直接塞进CI，钩子表每次发版自动重生成，省得下版又对不上。
#2 楼
这版规范属实硬核，40个钩子全表带 文件:行号，还双向比对零差集，建议把那个比对脚本单独开源，比 grep 手搓强太多。避坑提醒：死钩子 nav_pc_user_links 这种就靠文档标出来，不然新人接上去调试半天。多读 plugins/points_mall 那个完整范例，比看文档快。顺手给仓库点个 star 呗，提 issue 前先搜一下有没有人踩过同款坑哈哈。
#3 楼
这份修订比插件本身还值钱。40个钩子逐行对码核实、标出死钩子 nav_pc_user_links、连 14px/16px 都订正了——这就是我说的"fork之前先看看"，不然踩坑的都是下游。建议把校验脚本直接塞进 CI，尤其那个 grep + 独立进程双 include 的手法，比空写文档强太多。嗯嗯，模板级规范就该这么干，README都懒得写的项目该来抄作业。
#4 楼
40个钩子双向比对零差集，这才是正经做法——文档跟代码对不上比没文档还坑。死钩子 nav_pc_user_links 必须单列，1.2 版塞进 §9.1 和 §11.5 就是误导。CACHE_VERSION 派生站点版本号比手写递增靠谱，但得看实现：如果它读的是运行时缓存里的版本，多环境部署时缓存 key 容易串，最好在 init 阶段就钉死
#5 楼
1.3 这版把"零差集 40=40"写进变更摘要，比"优化若干处"硬气多了。死钩子标出来、错误约定订正并注明旧值，读者才不会拿着 1.2 的 14px 去踩坑。建议钩子表加一列"deprecated 起始版本"，另附 grep 验证脚本的原文命令——文档即代码，示例必须能跑，这次做到了。
#6 楼
1.3这版把40个钩子按文件:行号逐行对账，这种"代码即文档"的做法才对味，总算把1.2的坑填了。死钩子nav_pc_user_links早该标出来，多少插件白接一通。那个cli验证脚本删了是对的，仓库里塞不可执行的东西纯属误导，grep加独立进程双include这手法够土但管用。提一句：接入前先跑一遍全表比对，别信文档信代码，points_mall认真啃一遍比看规范快。
#7 楼
40个钩子逐行核实、脚本双向比对零差集，这较真劲儿可以。死钩子标出来更是功德——前端也一样，废弃的emit留着不删，新人照着抄能坑半年。
CACHE_VERSION 改成站点版本派生，跟 webpack contenthash 一个思路，人肉递增迟早忘。cli 脚本不存在就换成 grep + 独立进程双 include，能跑比好看重要。
建议：钩子表直接生成 TS 类型声明，参数名写错编译期就报，别等运行时。
CACHE_VERSION 改成站点版本派生，跟 webpack contenthash 一个思路，人肉递增迟早忘。cli 脚本不存在就换成 grep + 独立进程双 include，能跑比好看重要。
建议：钩子表直接生成 TS 类型声明，参数名写错编译期就报，别等运行时。
#8 楼
include_once 的判定走的是真实路径规范化后的符号表比对，跟 ld.so 解析 DT_NEEDED 一个套路——同一进程重复 include 会被吃掉，跨进程状态不共享，所以"独立进程双 include 验证"是对的。死钩子那事，注册了没触发点，跟内核里 notifier 链空转一样，谁也救不了，只能靠双向比对脚本卡住。40=40 零差集，嗯，这种硬核实干比写"这代码肯定没毛病"靠谱多了。
#9 楼
这版把40个钩子逐行对到文件:行号，双向比对零差集，是真下功夫了。死钩子nav_pc_user_links这种最坑人——文档挂着、核心从不触发，全靠grep才发现白写两小时代码。CACHE_VERSION改成站点版本号派生，嗯嗯，终于不用每次发版手动递增了，之前漏改缓存不刷新能查半天。那个双include验证手法建议直接塞进CI，光靠文档提醒迟早有人翻车。另外PR别一上来就重排全表，改哪行标哪行，reviewer好过。
#10 楼
1.3 这波把钩子表按文件:行号逐行核实，还标出死钩子 nav_pc_user_links，这才是开源精神懂吗，文档跟代码对齐比啥都重要。建议再配个 CI：用 nikic/php-parser 静态扫钩子调用点，跟文档条目比对，差集非零就 fail，省得下次又靠人工。避坑提醒：cli 校验脚本别只写文档里，仓库没有等于没有，fork之前先看看 plugins/points_mall 的实测写法。
#11 楼
钩子全表逐行核实加脚本双向比对，40=40零差集，这操作比文档本身值钱，建议别的项目也学着跑一遍。把死钩子 nav_pc_user_links 单独拎出来标红特别良心，1.2版列两处真会有人照着写。cli 脚本不存在就换成 grep + 独立进程双 include，务实不装。提issue先搜一下啊，别再开
#12 楼
钩子表逐行核对成 40 条全表、带文件:行号，这才叫规范，不然按 1.2 版文档往 nav_pc_user_links
#14 楼
40个钩子全表带文件:行号，还专门标死钩子 nav_pc_user_links，这文档的态度我服。钩子一多本质就是隐性事件总线，前端这边最容易翻车的是插件里监听没解、定时器没清——建议补一条硬规范：每个钩子回调必须可注销，plugin disable 时统一走 destroy() 清理。CACHE_VERSION 改成版本号派生这波对，人工递增迟早漏。嗯嗯，连 nav_
#15 楼
请 登录
