wp-plugin-development

WP 插件开发

适用场景

在以下插件工作中使用此技能：

• 创建或重构插件结构（引导文件、包含文件、命名空间/类）
• 添加钩子/操作/筛选器
• 添加激活/停用/卸载行为和迁移
• 添加设置页面/选项/管理界面（Settings API）
• 修复安全问题（随机数、功能权限、清理/转义、SQL 安全）
• 打包发布版本（构建产物、readme、资源）

所需输入

• 仓库根目录和目标插件（如果已知，请提供插件主文件路径）。
• 此插件的运行环境：单站点还是多站点；如适用，请说明 WP.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) 钩子和生命周期（激活/停用/卸载）

激活钩子容易出问题；请遵循以下防护措施：

• 在顶层注册激活/停用钩子，不要放在其他钩子内部
• 仅在必要时刷新重写规则，并且只能在注册 CPT/规则后刷新
• 卸载逻辑应明确且安全（使用 uninstall.php 或 register_uninstall_hook）

参见：

• references/lifecycle.md

3) 设置和管理界面（Settings API）

选项优先使用 Settings API：

• register_setting()、add_settings_section()、add_settings_field()
• 通过 sanitize_callback 清理数据

参见：

• references/settings-api.md

4) 安全基线（始终遵守）

发布前：

• 尽早验证/清理输入；在输出时进行转义。
• 使用随机数防止 CSRF，并通过功能权限检查进行授权。
• 不要直接信任 $_POST / $_GET；使用 wp_unslash() 和指定的键。
• 对 SQL 使用 $wpdb->prepare()；避免通过字符串拼接构建 SQL。

参见：

• references/security.md

5) 数据存储、cron、迁移（如有需要）

• 少量配置优先使用选项；仅在必要时使用自定义表。
• 对 cron 任务确保幂等性，并提供手动运行方式（WP-CLI 或管理端）。
• 对架构更改编写升级例程，并存储架构版本。

参见：

• references/data-and-cron.md

验证

• 插件激活时没有致命错误或通知。
• 设置可以正确保存和读取（已执行功能权限和随机数验证）。
• 卸载时只删除预期数据，不影响其他数据。
• 运行仓库中的 lint/测试（如有 PHPUnit/PHPCS），以及插件发布资源所需的任何 JS 构建步骤。

故障模式 / 调试

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

参见：

• references/debugging.md

升级处理

如需权威细节，请在自行设计模式前查阅 Plugin Handbook 和安全指南。