WordPress自定义插件开发：轻量插件的结构、钩子与发布
一、什么时候该自己写插件
WordPress里所有自定义行为都要挂到钩子上。小到改个发件人邮箱，大到加个自定义字段，都能用几十行PHP解决。问题在于很多人第一反应是去插件库搜。
判断该装插件还是自己写：如果需求只是”改一个固定行为”，比如改默认发件人、加一段自定义JS、改摘要长度，自己写插件比装第三方更干净。插件选型的通用框架见WordPress独立站技术栈。
反直觉点在于，functions.php越写越长不是熟练，是在给下次换主题埋雷。主题更新或更换时functions.php会被覆盖，代码全没。正确做法是把自定义逻辑搬进独立插件，主题只管外观。
命名上也要讲规矩。插件目录名用前缀加功能，比如crater-inquiry-source，避免和官方插件重名。函数名同样加前缀，crater_register_source，防止和别的插件函数冲突。
函数命名冲突是WordPress插件最常见的致命错误。两个插件都写了function register_source()，后加载的那个直接白屏。所有自定义函数必须加唯一前缀。
| 需求规模 | 建议形态 | 文件数 |
|---|---|---|
| 1至3个小改动 | 单文件插件 | 1个php |
| 3至5个相关功能 | 单文件插件+常量 | 1个php |
| 5个以上独立功能 | 目录结构插件 | 主文件+includes+assets |
| 需后台设置页 | 目录结构插件 | 加admin-page.php |
二、单文件插件的最小结构
一个能跑的WordPress插件，最少只需要一个php文件，开头一段插件头注释，告诉WP这是个插件。文件放在wp-content/plugins/下，后台就能看到。
插件头注释固定格式：Plugin Name、Description、Version、Author这几项。没有这段注释，WP不会把它识别为插件。
场景示例一：改默认发件人邮箱，整个插件就10行。挂上wp_mail_from和wp_mail_from_name两个filter，把默认wordpress@改成noreply@example.com。不需要任何设置页。
这种纯filter型插件最适合起步。没有数据库、没有后台页、没有定时任务，出问题关掉插件就恢复。
如果需求要存配置，用WordPress自带的options表，一条记录存一个数组，不要自己建表。简单设置用get_option和update_option就够。
| 钩子类型 | 常用钩子 | 用途 |
|---|---|---|
| filter过滤器 | wp_mail_from、the_content | 修改输出内容 |
| action动作 | wp_head、admin_init | 插入代码或执行动作 |
| 后台动作 | admin_menu、admin_init | 加设置页，只在后台跑 |
| 前台动作 | wp_enqueue_scripts | 加载CSS/JS，只在前台跑 |
钩子挂载位置是性能关键。admin_init只在后台加载时触发，wp_head只在前台页面加载。别把后台专属逻辑挂到init上，那会让每次前台请求都白跑一遍。
加载自己的CSS和JS要用wp_enqueue_scripts钩子，不能直接在wp_head里echo。直接echo会导致脚本重复加载。
场景示例三：插件要在表单页加载一段校验脚本。用wp_enqueue_script注册，声明依赖jquery，第五个参数设为true让脚本在页脚加载，不阻塞首屏渲染。
三、激活、卸载与数据清理
插件会建数据表或写option时，必须处理激活和卸载。激活时建表，卸载时删表，否则卸了插件数据库里还留着垃圾。
register_activation_hook在插件被启用时触发，适合建表、写默认option。uninstall.php在删除插件时触发，适合清理数据。注意deactivate和uninstall不一样：停用不删数据，删除才删。
场景示例二：插件记录询盘来源到一张自定义表。激活时用dbDelta建表，卸载时DROP TABLE。用户停用再启用，数据还在；删除插件，表一起清掉。
| 生命周期 | 钩子 | 该做什么 |
|---|---|---|
| 启用插件 | register_activation_hook | 建表、写默认option |
| 停用插件 | register_deactivation_hook | 清定时任务，不动数据 |
| 删除插件 | uninstall.php | 删表、删option |
| 每次加载 | plugins_loaded | 定义常量、加载文本域 |
安全上要注意：自定义插件里凡是处理用户输入，都要用$wpdb->prepare做预处理，不能直接拼接SQL。用户角色和后台权限的基线配置，见WordPress安全基线。PHP版本兼容性则参考独立站PHP版本升级。
四、发布与维护：私有插件不上官方库
给单个客户站写的私有插件，不需要提交到wordpress.org。打包成zip在后台上传即可，或直接git clone到wp-content/mu-plugins目录，MU插件默认启用且不能被误停用。
版本管理要做。插件头里的Version号每次改动递增，后台能看到更新。别在生产站直接改插件文件，本地改完上传。
环形山团队的几个自研插件就是这个思路，详见环形山技术栈。它们解决的都是具体小问题，每个都不超过两个文件。
| 发布方式 | 适用场景 | 优点 | 风险 |
|---|---|---|---|
| zip上传后台 | 私有插件交付客户 | 客户可自行停用 | 可能被误删 |
| mu-plugins目录 | 核心逻辑不能停 | 默认启用，不可误停 | 更新要手动 |
| wordpress.org提交 | 通用公开插件 | 自动更新 | 要过审核，写文档 |
版本号管理别忽略。每次改动递增插件头里的Version，后台插件列表才能看到”有更新”标记。
自己维护的私有插件没有官方更新通道，建议用git管理，部署时直接git pull到服务器目录。不要在生产站直接改文件。
FAQ 常见问题
什么情况下该自己写插件而不是装第三方？
把代码写在主题functions.php里不行吗？
一个最小能跑的WordPress插件要多少行代码？
插件建了数据表，卸载时要自己删吗？
私有插件要提交到wordpress.org吗？
为什么我的插件代码在前台每次都执行？
写在最后
自研插件的价值不在炫技，在于把可控的小逻辑从第三方插件库里拿回来。第三方插件更新可能改行为，自己的代码永远在你手里。
落地三步：把functions.php里的自定义逻辑逐个搬进单文件插件；建了表就写uninstall清理；私有插件打zip或放mu-plugins，不凑热闹提交官方库。
一个常见疑问：要不要用Composer、代码框架来写插件？给单个客户站用的轻量插件不需要。
引入框架意味着vendor目录多几十MB，每次更新都要维护依赖。300行能写完的事，加框架是给自己添乱。
只有当插件要做成公开产品、要单元测试、要多人协作时，才值得上Composer和命名空间。
安全上再补一点：插件里处理后台表单，必须check_admin_referer做nonce校验，防止跨站请求伪造。这是WordPress后台表单的标准动作，漏了等于后台接口裸奔。
输出用户输入到页面时，要用esc_html、esc_attr这些转义函数，不要直接echo。即便是自己后台写的配置值，输出到前台也要转义。
最后提一个上手顺序。第一次写插件，从改发件人、改摘要长度这种纯filter开始，不碰数据库、不碰后台页。
跑通一次完整的”写代码、上传、启用、看到效果”循环，再逐步加功能。一上来就写带数据表和后台页的插件，容易被钩子和生命周期绕晕。
插件越写越小是对的。每加一个功能前先问自己，能不能用现有钩子二十行写完。能就别建表，能就别加后台页。
插件代码量控制在300行以内，是对自己也是对客户负责。超过这个量级，多半是该用第三方成熟插件了。
最后再强调一次：别把自定义逻辑堆在主题的functions.php里。搬进独立插件，主题才能放心换，客户才能自己长期维护。
一句可以记住的话：能20行钩子解决的事，别装一个5000行的第三方插件——代码越少，失控面越小。