wordpress-plugin-core

WordPress 插件开发（核心）

状态：生产就绪 最后更新：2026-08-03 依赖项：无（WordPress 6.0+、PHP 8.0+） 最新版本：建议使用 WordPress 7.0+、PHP 8.3+

---

快速入门（10 分钟）

1. 选择插件结构

提供三种架构模式（详细示例请参阅 references/plugin-architectures.md）：

• 简单（仅函数）——小型插件（函数少于 5 个）
• OOP——具有相关功能的中型插件
• PSR-4（命名空间 + Composer）——现代标准（2025），最易维护

2. 创建插件头部信息

每个插件的主文件中都必须包含头部注释：

<?php
/**
 * Plugin Name:       My Awesome Plugin
 * Description:       Brief description.
 * Version:           1.0.0
 * Requires at least: 6.0
 * Requires PHP:      8.0
 * Text Domain:       my-plugin
 */

if ( ! defined( 'ABSPATH' ) ) exit;

重要：必须填写插件名称，文本域必须与插件 slug 完全一致。

3. 安全基础（5 项要点）

// 1. Unique Prefix (4-5 chars)
function mypl_init() { /* code */ }
add_action( 'init', 'mypl_init' );

// 2. ABSPATH Check (every file)
if ( ! defined( 'ABSPATH' ) ) exit;

// 3. Nonces for Forms
wp_nonce_field( 'mypl_action', 'mypl_nonce' );

// 4. Sanitize Input, Escape Output
$clean = sanitize_text_field( $_POST['input'] );
echo esc_html( $output );

// 5. Prepared Statements
$wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}table WHERE id = %d", $id ) );

---

安全基础的 5 个步骤

步骤 1：所有内容都使用唯一前缀

规则：至少 4-5 个字符，并应用于函数、类、常量、选项、瞬态和元键。避免使用 wp_、__、_。

// GOOD
function mypl_init() {}
class MyPL_Settings {}
add_option( 'mypl_option', 'value' );

// BAD - Will conflict
function init() {}
class Settings {}

步骤 2：检查权限，而不是管理员身份

// WRONG
if ( is_admin() ) { /* SECURITY HOLE */ }

// CORRECT
if ( current_user_can( 'manage_options' ) ) { /* Secure */ }

常见权限：manage_options（管理员）、edit_posts（编辑）、publish_posts（作者）

步骤 3：安全三要素

输入 → 处理 → 输出（清理 → 验证 → 转义）：

// SANITIZATION (Input)
$name = sanitize_text_field( $_POST['name'] );
$email = sanitize_email( $_POST['email'] );
$url = esc_url_raw( $_POST['url'] );
$html = wp_kses_post( $_POST['content'] );

// VALIDATION (Logic)
if ( ! is_email( $email ) ) wp_die( 'Invalid email' );

// ESCAPING (Output)
echo esc_html( $name );
echo '<a href="' . esc_url( $url ) . '">' . esc_html( $text ) . '</a>';

规则：清理输入，转义输出。永远不要信任用户数据。

步骤 4：Nonce（CSRF 保护）

用于证明请求来自你的网站的一次性令牌。

// Form
<form method="post">
    <?php wp_nonce_field( 'mypl_action', 'mypl_nonce' ); ?>
    <input type="text" name="data" />
</form>

// Verify
if ( ! wp_verify_nonce( $_POST['mypl_nonce'], 'mypl_action' ) ) wp_die( 'Security check failed' );

// AJAX
check_ajax_referer( 'mypl-ajax-nonce', 'nonce' );

步骤 5：数据库预处理语句

重要：处理用户输入时，始终使用 $wpdb->prepare()。

// WRONG - SQL Injection
$wpdb->get_results( "SELECT * FROM {$wpdb->prefix}table WHERE id = {$_GET['id']}" );

// CORRECT
$wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}table WHERE id = %d", $_GET['id'] ) );

占位符：%s（字符串）、%d（整数）、%f（浮点数）

LIKE 查询：添加通配符前，先使用 $wpdb->esc_like()：

$search = '%' . $wpdb->esc_like( $term ) . '%';
$wpdb->get_results( $wpdb->prepare( "... WHERE title LIKE %s", $search ) );

---

关键规则

务必做到

✅ 使用唯一前缀（4-5 个字符）标记所有全局代码（函数、类、选项、瞬态） ✅ 在每个 PHP 文件中添加 ABSPATH 检查：if ( ! defined( 'ABSPATH' ) ) exit; ✅ 检查权限（current_user_can()），而不只是检查 is_admin() ✅ 验证所有表单和 AJAX 请求的 nonce ✅ 对所有包含用户输入的数据库查询使用 $wpdb->prepare() ✅ 保存前使用 sanitize_*() 函数清理输入 ✅ 显示前使用 esc_*() 函数转义输出 ✅ 注册自定义文章类型时，在激活时刷新重写规则 ✅ 使用 uninstall.php 执行永久清理（不要使用停用钩子） ✅ 遵循 WordPress 编码标准（使用制表符缩进、Yoda 条件）

绝对不要做

❌ 绝不使用 extract()——会造成安全漏洞 ❌ 未经清理，绝不信任 $_POST/$_GET ❌ 绝不将用户输入拼接进 SQL——始终使用 prepare() ❌ 绝不单独使用 is_admin() 检查权限 ❌ 绝不输出未经清理的数据——始终进行转义 ❌ 绝不使用通用的函数/类名称——始终添加前缀 ❌ 绝不使用短 PHP 标签 <? 或 <?=——仅使用 <?php ❌ 绝不在停用时删除用户数据——仅在卸载时删除 ❌ 绝不重复注册卸载钩子——仅在激活时注册一次 ❌ 绝不在主流程中使用 register_uninstall_hook()——改用 uninstall.php

---

防范已知问题

此技能可防范 20 个已记录的问题：

问题 #1：SQL 注入

错误：未转义的用户输入导致数据库遭到入侵 来源：https://patchstack.com/articles/sql-injection/（占所有漏洞的 15%） 成因：直接将用户输入拼接到 SQL 查询中 预防措施：始终使用带占位符的 $wpdb->prepare()

// VULNERABLE
$wpdb->query( "DELETE FROM {$wpdb->prefix}table WHERE id = {$_GET['id']}" );

// SECURE
$wpdb->query( $wpdb->prepare( "DELETE FROM {$wpdb->prefix}table WHERE id = %d", $_GET['id'] ) );

问题 #2：XSS（跨站脚本攻击）

错误：恶意 JavaScript 在用户浏览器中执行 来源：https://patchstack.com（占所有漏洞的 35%） 成因：将未经清理的用户数据输出到 HTML 预防措施：始终根据上下文使用适当的函数转义输出

// VULNERABLE
echo $_POST['name'];
echo '<div class="' . $_POST['class'] . '">';

// SECURE
echo esc_html( $_POST['name'] );
echo '<div class="' . esc_attr( $_POST['class'] ) . '">';

问题 #3：CSRF（跨站请求伪造）

错误：攻击者代表用户执行未经授权的操作 来源：https://blog.nintechnet.com/25-wordpress-plugins-vulnerable-to-csrf-attacks/ 原因：未验证请求是否来自你的网站 预防：使用 wp_nonce_field() 和 wp_verify_nonce() 创建并验证 nonce

// VULNERABLE
if ( $_POST['action'] == 'delete' ) {
    delete_user( $_POST['user_id'] );
}

// SECURE
if ( ! wp_verify_nonce( $_POST['nonce'], 'mypl_delete_user' ) ) {
    wp_die( 'Security check failed' );
}
delete_user( absint( $_POST['user_id'] ) );

问题 #4：缺少能力检查

错误：普通用户可以访问管理功能 来源：WordPress 安全审查指南 原因：使用 is_admin() 而不是 current_user_can() 预防：始终检查用户能力，而不只是管理上下文

// VULNERABLE
if ( is_admin() ) {
    // Any logged-in user can trigger this
}

// SECURE
if ( current_user_can( 'manage_options' ) ) {
    // Only administrators can trigger this
}

问题 #5：直接访问文件

错误：PHP 文件在 WordPress 上下文之外执行 来源：WordPress 插件手册 原因：文件顶部未检查 ABSPATH 预防：在每个 PHP 文件中添加 ABSPATH 检查

// Add to top of EVERY PHP file
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

其他问题（#6-20）

如需全面了解 Top 5 之外的错误，请加载 references/error-catalog.md，其中包括：

• 功能：前缀冲突、未刷新重写规则、已弃用函数、文本域不匹配、插件依赖项、自动保存触发
• 性能：脚本在所有页面加载、未清理临时数据、admin-ajax.php 性能问题
• 安全：保存时缺少数据净化、LIKE 查询不正确、使用 extract()、缺少 REST API 权限回调、卸载钩子问题
• 数据完整性：停用时删除数据

每个问题都包括：错误描述、来源、原因、预防代码、影响严重程度和发生频率。

---

插件架构模式

根据插件的规模和复杂程度选择合适的架构：

决策指南

简单（仅函数）

• 适用情况：小型插件（少于 5 个函数），单一功能
• 优点：容易上手，样板代码少
• 缺点：难以扩展，超过约 5 个函数后难以组织
• 示例：简单的短代码插件、基础小工具

OOP（单例模式）

• 适用情况：中型插件（5–20 个函数），功能相互关联
• 优点：组织更清晰、封装性更好、便于测试
• 缺点：比简单方案需要更多样板代码，未使用现代 PHP 特性
• 示例：自定义文章类型插件、管理设置页面

PSR-4（命名空间 + Composer）

• 适用情况：大型或现代化插件、团队开发、2025 年及以后的标准
• 优点：现代 PHP、命名空间、自动加载、最佳实践
• 缺点：需要 Composer，初始配置更多
• 示例：电子商务扩展、多功能插件

完整示例

如需查看包含目录结构、激活钩子和代码模式的完整实现示例，请加载 references/plugin-architectures.md。

---

常见实现模式

此技能为 8 种常见 WordPress 插件功能提供可用于生产环境的模式：

1. 自定义文章类型 - 注册支持 Gutenberg 的 CPT，刷新重写规则
2. 自定义分类法 - 分层（类别）或扁平（标签）分类法
3. 元数据框 - 使用适当的安全措施（nonce、能力检查、自动保存检查）保存自定义字段
4. 设置 API - 使用 WordPress 原生设置页面并进行数据净化
5. REST API 端点 - 使用权限回调和验证的现代 API 端点
6. AJAX 处理器 - 传统的 admin-ajax.php 模式（新项目请使用 REST API）
7. 自定义数据库表 - 使用 dbDelta 创建表并进行版本管理
8. 临时数据缓存 - 缓存开销较大的操作，并在更新时清除缓存

如需完整实现代码，在实现上述任一功能时加载 references/common-patterns.md。每种模式都包括：

• 完整的可运行代码示例
• 安全要求清单
• 应避免的常见错误
• 最佳实践和性能提示

---

---

分发与自动更新

托管在 WordPress.org 之外的插件可以使用 YahnisElsts 的 Plugin Update Checker（推荐）提供自动更新。

快速方案：

• 公共仓库：Plugin Update Checker（GitHub/GitLab/BitBucket）
• 私有插件：Plugin Update Checker + 身份验证令牌
• 商业插件：Freemius 或自定义更新服务
• 无需编码：Git Updater 插件

完整实现指南，请加载 references/github-auto-updates.md，其中包括：

• Plugin Update Checker 设置（5 分钟）
• GitHub Releases 工作流
• 私有仓库身份验证
• 安全最佳实践（校验和、令牌、速率限制）
• 替代方案比较
• ZIP 结构要求

---

依赖项

必需：

• WordPress 6.0+（推荐 7.0+）
• PHP 8.0+（推荐 8.3+）

可选：

• Composer 2.0+ - 用于 PSR-4 自动加载
• WP-CLI 2.0+ - 用于通过命令行管理插件
• Query Monitor - 用于调试和性能分析

---

官方文档

• WordPress 插件手册：https://developer.wordpress.org/plugins/
• WordPress 编码规范：https://developer.wordpress.org/coding-standards/
• WordPress REST API：https://developer.wordpress.org/rest-api/
• WordPress 数据库类（$wpdb）：https://developer.wordpress.org/reference/classes/wpdb/
• WordPress 安全：https://developer.wordpress.org/apis/security/
• Settings API：https://developer.wordpress.org/plugins/settings/settings-api/
• 自定义文章类型：https://developer.wordpress.org/plugins/post-types/
• Transients API：https://developer.wordpress.org/apis/transients/
• Context7 Library ID：/websites/developer_wordpress

---

故障排除

致命错误：启用 WP_DEBUG，检查 wp-content/debug.log，确认名称带有正确的前缀

CPT 返回 404：刷新重写规则（在 wp-admin 中临时添加 flush_rewrite_rules();）

Nonce 失败：检查名称是否匹配、操作是否正确，以及有效期是否为 24 小时

AJAX 返回 0/-1：确认操作名称与 wp_ajax_{action} 匹配、nonce 已发送并验证，且处理程序已挂接

HTML 被剥离：使用 wp_kses_post() 代替 sanitize_text_field()

数据库查询失败：始终使用 $wpdb->prepare()，包含 $wpdb->prefix，并检查语法

---

何时加载参考资料

此技能采用渐进式披露——主文件包含必备内容，参考文件包含详细实现。根据当前任务加载参考资料：

references/common-patterns.md（465 行）

加载时机：实现特定的 WordPress 功能 包含内容：

• 自定义文章类型（注册、Gutenberg 支持、重写规则）
• 自定义分类法（层级式与扁平式、REST API）
• 元数据框（安全要求、保存钩子、自动保存检查）
• Settings API（register_setting、分区、字段层级）
• REST API 端点（权限回调、验证、响应）
• AJAX 处理程序（nonce 验证、wp_ajax 钩子、JavaScript 集成）
• 自定义数据库表（dbDelta、字符编码、版本控制）
• 用于缓存的 Transients（缓存模式、失效、过期）

references/plugin-architectures.md（220 行）

加载时机：选择插件结构或在不同模式间迁移 包含内容：

• 简单模式（仅函数，<5 个函数）
• OOP 模式（单例、封装、中型插件）
• PSR-4 模式（命名空间、Composer 自动加载、现代标准）
• 模式选择决策树
• 包含所有文件的完整目录结构
• 激活/停用钩子示例
• 不同模式之间的迁移路径

references/error-catalog.md（问题 #6-20，共 573 行）

在以下情况下加载：调试超出前 5 大安全漏洞范围的问题 包含：

• 功能问题（前缀冲突、重写规则、已弃用函数、文本域、依赖项、自动保存）
• 性能问题（脚本随处加载、临时数据清理、admin-ajax.php 的替代方案）
• 安全问题（清理、extract()、REST 权限、卸载钩子）
• 数据完整性问题（停用与卸载） 每个问题均包含：错误描述、来源/参考、发生原因、预防代码、影响严重程度、出现频率

references/advanced-topics.md（150 行）

在以下情况下加载：实现 i18n、WP-CLI、Cron 作业或依赖项检查 包含：

• 国际化（i18n）——load_plugin_textdomain()、翻译工作流、.pot/.po/.mo 文件
• WP-CLI 命令——自定义命令创建、进度条、输出函数
• 计划事件（Cron）——wp_schedule_event()、自定义计划、激活钩子
• 插件依赖项检查——版本要求、软依赖项、便于用户理解的错误消息

references/security-checklist.md（527 行）

在以下情况下加载：执行安全审计或审查代码中的漏洞 包含：

• 完整的安全审计清单
• WordPress OWASP Top 10
• 各类漏洞的代码示例
• 测试流程和工具
• 安全插件建议

references/github-auto-updates.md（1,224 行）

在以下情况下加载：为托管在 WordPress.org 之外的插件设置自动更新 包含：

• Plugin Update Checker（推荐）——5 分钟即可完成设置
• GitHub Releases 工作流和自动化
• 私有仓库身份验证（令牌、wp-config.php）
• 替代方案（Git Updater、自定义服务、Freemius）
• 安全最佳实践（校验和、签名、速率限制）
• ZIP 结构要求和常见错误
• 部署自动化示例

references/common-hooks.md（234 行）

在以下情况下加载：使用 WordPress 钩子并需要钩子参考 包含：

• 操作钩子参考（init、admin_menu、save_post 等）
• 过滤器钩子参考（the_content、post_type_args 等）
• 钩子优先级和执行顺序
• 常见钩子组合和模式

---

完整设置检查清单

使用此检查清单验证你的插件：

• 插件标头包含所有字段
• 每个 PHP 文件顶部都有 ABSPATH 检查
• 所有函数/类都使用唯一前缀
• 所有表单都经过 nonce 验证
• 所有用户输入都经过清理
• 所有输出都经过转义
• 所有数据库查询都使用 $wpdb->prepare()
• 检查功能权限（不能只使用 is_admin()）
• 自定义文章类型在激活时刷新重写规则
• 停用钩子仅清除临时数据
• uninstall.php 负责永久清理
• 文本域与插件 slug 一致
• 仅在需要时加载脚本/样式
• 开发期间启用 WP_DEBUG
• 使用 Query Monitor 测试性能
• 没有已弃用函数警告
• 兼容最新版本的 WordPress

---

有问题？遇到故障？

1. 查看 references/error-catalog.md 中的其他问题 #6-20
2. 核实安全基础中的所有步骤
3. 查看官方文档：https://developer.wordpress.org/plugins/
4. 启用 WP_DEBUG 并检查 debug.log
5. 使用 Query Monitor 插件调试钩子和查询