wp-plugin-development

WP插件开发

何时使用

在以下插件开发场景中使用此技能：

• 创建或重构插件结构（引导文件、includes、命名空间/类）
• 添加钩子/动作/过滤器
• 激活/停用/卸载行为及迁移
• 添加设置页面/选项/管理界面（设置API）
• 安全修复（nonce、权限、清理/转义、SQL安全）
• 打包发布（构建产物、readme、资源）

所需输入

• 仓库根目录及目标插件（如果已知插件主文件路径）。
• 插件运行环境：单站点还是多站点；如果适用，WordPress.com约定。
• 目标WordPress + PHP版本（影响可用API和$wpdb->prepare()中的占位符支持）。

操作步骤

0) 分类并定位插件入口点

1. 运行分类：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 检测插件头部（确定性扫描）：
   • node skills/wp-plugin-development/scripts/detect_plugins.mjs

如果是完整站点仓库，在修改代码前，选择wp-content/plugins/或mu-plugins/下的特定插件。

1) 遵循可预测的架构

指南：

• 保持单个引导文件（包含头部的主插件文件）。
• 避免在文件加载时产生大量副作用；在钩子上加载。
• 优先使用专用的加载器/类来注册钩子。
• 将仅管理端的代码放在is_admin()（或管理钩子）后面，以减少前端开销。

参见：

• references/structure.md

2) 钩子与生命周期（激活/停用/卸载）

激活钩子很脆弱；请遵循以下准则：

• 在顶层注册激活/停用钩子，不要在其他钩子内部注册
• 仅在需要时刷新重写规则，且必须在注册自定义文章类型/规则之后
• 卸载应明确且安全（uninstall.php或register_uninstall_hook）

参见：

• references/lifecycle.md

3) 设置与管理界面（设置API）

优先使用设置API处理选项：

• register_setting()、add_settings_section()、add_settings_field()
• 通过sanitize_callback进行清理

参见：

• references/settings-api.md

4) 安全基线（始终执行）

在发布前：

• 尽早验证/清理输入；延迟转义输出。
• 使用nonce防止CSRF，并使用权限检查进行授权。
• 避免直接信任$_POST / $_GET；使用wp_unslash()和特定键。
• 使用$wpdb->prepare()处理SQL；避免使用字符串拼接构建SQL。

参见：

• references/security.md

5) 数据存储、定时任务、迁移（如果需要）

• 对于小型配置，优先使用选项；仅在必要时使用自定义表。
• 对于定时任务，确保幂等性并提供手动运行路径（WP-CLI或管理界面）。
• 对于架构变更，编写升级例程并存储架构版本。

参见：

• references/data-and-cron.md

验证

• 插件激活时无致命错误/通知。
• 设置正确保存和读取（强制权限+nonce）。
• 卸载删除预期数据（且仅删除预期数据）。
• 运行仓库的lint/测试（如果存在PHPUnit/PHPCS），如果插件包含资源，则运行JS构建步骤。

失败模式/调试

• 激活钩子未触发：
  • 钩子注册不正确（不在主文件作用域内）、主文件路径错误、或插件已网络激活
• 设置未保存：
  • 设置未注册、选项组错误、缺少权限、nonce失败
• 安全回归：
  • 存在nonce但缺少权限检查；或清理后的输入在输出时未转义

参见：

• references/debugging.md

升级

对于权威细节，请查阅插件手册和安全指南，然后再自行发明模式。