wp-plugin-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Plugin Development

WordPress插件开发

When to use

适用场景

Use this skill for plugin work such as:

creating or refactoring plugin structure (bootstrap, includes, namespaces/classes)
adding hooks/actions/filters
activation/deactivation/uninstall behavior and migrations
adding settings pages / options / admin UI (Settings API)
security fixes (nonces, capabilities, sanitization/escaping, SQL safety)
packaging a release (build artifacts, readme, assets)

本技能适用于以下插件开发工作：

创建或重构插件结构（引导文件、包含文件、命名空间/类）
添加钩子/动作/过滤器
激活/停用/卸载逻辑与数据迁移
添加设置页面/选项/后台UI（Settings API）
安全修复（随机数验证、权限控制、数据清理/转义、SQL安全）
发布打包（构建产物、说明文档、资源文件）

Inputs required

所需输入

Repo root + target plugin(s) (path to plugin main file if known).
Where this plugin runs: single site vs multisite; WP.com conventions if applicable.
Target WordPress + PHP versions (affects available APIs and placeholder support in
```
$wpdb->prepare()
```
).

代码仓库根目录 + 目标插件（若已知，需提供插件主文件路径）
插件运行环境：单站点还是多站点；若适用，需遵循WP.com规范
目标WordPress与PHP版本（会影响可用API以及
```
$wpdb->prepare()
```
中的占位符支持）

Procedure

操作流程

0) Triage and locate plugin entrypoints

0) 排查并定位插件入口

Run triage:

node skills/wp-project-triage/scripts/detect_wp_project.mjs

Detect plugin headers (deterministic scan):

node skills/wp-plugin-development/scripts/detect_plugins.mjs

If this is a full site repo, pick the specific plugin under

wp-content/plugins/

mu-plugins/

before changing code.

执行排查：

node skills/wp-project-triage/scripts/detect_wp_project.mjs

检测插件头部信息（确定性扫描）：

node skills/wp-plugin-development/scripts/detect_plugins.mjs

如果是完整站点仓库，在修改代码前，请选择

wp-content/plugins/

或

mu-plugins/

下的具体插件。

1) Follow a predictable architecture

1) 遵循可预测的架构规范

Guidelines:

Keep a single bootstrap (main plugin file with header).
Avoid heavy side effects at file load time; load on hooks.
Prefer a dedicated loader/class to register hooks.
Keep admin-only code behind
```
is_admin()
```
(or admin hooks) to reduce frontend overhead.

See:

```
references/structure.md
```

规范说明：

保持单一引导文件（带头部信息的插件主文件）
避免在文件加载时产生大量副作用；通过钩子触发加载
优先使用专用的加载器/类来注册钩子
将仅后台使用的代码放在
```
is_admin()
```
（或后台钩子）中，以减少前端性能开销

参考文档：

```
references/structure.md
```

2) Hooks and lifecycle (activation/deactivation/uninstall)

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

Activation hooks are fragile; follow guardrails:

register activation/deactivation hooks at top-level, not inside other hooks
flush rewrite rules only when needed and only after registering CPTs/rules
uninstall should be explicit and safe (
```
uninstall.php
```
or
```
register_uninstall_hook
```
)

See:

```
references/lifecycle.md
```

激活钩子较为敏感，请遵循以下准则：

在顶级作用域注册激活/停用钩子，不要嵌套在其他钩子内部
仅在必要时刷新重写规则，且需在注册自定义文章类型（CPTs）/规则之后执行
卸载逻辑需明确且安全（使用
```
uninstall.php
```
或
```
register_uninstall_hook
```
）

参考文档：

```
references/lifecycle.md
```

3) Settings and admin UI (Settings API)

3) 设置与后台UI（Settings API）

Prefer Settings API for options:

register_setting()

add_settings_section()

add_settings_field()

sanitize via
```
sanitize_callback
```

See:

```
references/settings-api.md
```

优先使用Settings API来处理选项：

register_setting()

add_settings_section()

add_settings_field()

通过
```
sanitize_callback
```
进行数据清理

参考文档：

```
references/settings-api.md
```

4) Security baseline (always)

4) 安全基准（必须遵循）

Before shipping:

Validate/sanitize input early; escape output late.
Use nonces to prevent CSRF and capability checks for authorization.
Avoid directly trusting
```
$_POST
```
/
```
$_GET
```
; use
```
wp_unslash()
```
and specific keys.
Use
```
$wpdb->prepare()
```
for SQL; avoid building SQL with string concatenation.

See:

```
references/security.md
```

发布前需检查：

尽早验证/清理输入数据；延迟转义输出内容
使用nonce防止CSRF攻击，并通过权限控制进行授权验证
不要直接信任
```
$_POST
```
/
```
$_GET
```
数据；使用
```
wp_unslash()
```
并仅获取指定键值
使用
```
$wpdb->prepare()
```
处理SQL语句；避免通过字符串拼接构建SQL

参考文档：

```
references/security.md
```

5) Data storage, cron, migrations (if needed)

5) 数据存储、定时任务与迁移（按需使用）

Prefer options for small config; custom tables only if necessary.
For cron tasks, ensure idempotency and provide manual run paths (WP-CLI or admin).
For schema changes, write upgrade routines and store schema version.

See:

```
references/data-and-cron.md
```

小型配置优先使用选项存储；仅在必要时使用自定义数据表
定时任务需保证幂等性，并提供手动触发方式（WP-CLI或后台界面）
若需修改数据库结构，请编写升级程序并记录结构版本

参考文档：

```
references/data-and-cron.md
```

Verification

验证环节

Plugin activates with no fatals/notices.
Settings save and read correctly (capability + nonce enforced).
Uninstall removes intended data (and nothing else).
Run repo lint/tests (PHPUnit/PHPCS if present) and any JS build steps if the plugin ships assets.

插件激活无致命错误或通知
设置能正确保存与读取（已强制执行权限+nonce验证）
卸载操作仅删除目标数据（无额外误删）
运行仓库代码检查/测试（若存在PHPUnit/PHPCS），若插件包含资源文件，需执行JS构建步骤

Failure modes / debugging

故障模式与调试

Activation hook not firing:
- hook registered incorrectly (not in main file scope), wrong main file path, or plugin is network-activated
Settings not saving:
- settings not registered, wrong option group, missing capability, nonce failure
Security regressions:
- nonce present but missing capability checks; or sanitized input not escaped on output

See:

```
references/debugging.md
```

激活钩子未触发：
- 钩子注册错误（未在主文件作用域）、主文件路径错误，或插件为网络激活模式
设置无法保存：
- 设置未注册、选项组错误、缺少权限、nonce验证失败
安全回归问题：
- 存在nonce但缺少权限检查；或已清理的输入在输出时未转义

参考文档：

```
references/debugging.md
```

Escalation

问题升级

For canonical detail, consult the Plugin Handbook and security guidelines before inventing patterns.

如需权威细节，请先查阅插件手册与安全指南，切勿自行创造不规范的实现方式。