WordPress函数：delete_option 删除选项

简介

delete_option 函数用于从WordPress数据库中永久移除一条“选项”记录，是管理站点设置、插件及主题配置数据的基础工具。

语法

该函数定义于 wp-includes/option.php 文件中。其内部主要调用 $wpdb 的 delete 方法执行数据库删除操作，并会清理所有相关的对象缓存（wp_cache_delete）和调用相关钩子。

delete_option( string $option ): bool

参数	类型	必填	说明
`$option`	字符串	是	要删除的选项名称。
返回值	布尔值	–	删除成功返回 `true`，失败或选项不存在则返回 `false`。

重要说明：该函数操作的数据表为 wp_options（表前缀可能不同）。如果传入的 $option 参数未包含站点前缀，WordPress会自动为其加上 $wpdb->prefix。对于网络（Multisite）环境下的站点级选项，它会自动添加博客ID前缀。

用法

基础用法

最常见的场景是在插件或主题停用、卸载时，清理其创建的配置数据。一个负责任的开发者应该提供数据清理功能。

以下是一个完整的插件示例，展示了如何在插件的主文件中定义和清理选项：

<?php
/**
 * Plugin Name: 示例选项管理插件
 */

// 插件激活时，创建一些示例选项（仅供演示，实际可能通过设置页面添加）
register_activation_hook( __FILE__, 'wpdemo_create_options' );
function wpdemo_create_options() {
    add_option( 'wpdemo_plugin_setting', 'default_value' );
    add_option( 'wpdemo_plugin_version', '1.0.0' );
}

// 插件卸载时，删除它所创建的选项
// 这个函数应该只在用户点击“删除”插件时，通过 uninstall.php 调用。
// 此处仅为演示定义，切勿直接在此处调用。
function wpdemo_cleanup_options() {
    // 删除单个选项
    delete_option( 'wpdemo_plugin_setting' );
    // 在删除前检查选项是否存在是一个好习惯，可以避免不必要的数据库操作。
    if ( get_option( 'wpdemo_plugin_version' ) !== false ) {
        delete_option( 'wpdemo_plugin_version' );
    }
}

// 切勿在插件停用钩子中直接删除选项，这会导致用户下次启用时配置丢失。
// register_deactivation_hook( __FILE__, 'wpdemo_cleanup_options' ); // ❌ 错误做法
?>

为什么这样做？：将清理逻辑放在独立的函数中，并通过 uninstall.php 文件调用，是WordPress插件的标准做法。这确保了只有当用户意图永久删除插件时，数据才会被清除，而不是在每次停用时。

进阶用法

在复杂的插件中，您可能有一系列相关联的选项需要批量删除，例如按特定前缀命名的选项。

// 假设一个插件创建了以下选项：
// wpdemo_color_primary, wpdemo_color_secondary, wpdemo_layout_mode

function wpdemo_bulk_delete_options_by_prefix( $prefix ) {
    global $wpdb;

    // 安全性：对用户提供的输入进行转义，防止SQL注入。
    $escaped_prefix = $wpdb->esc_like( $prefix ) . '%';

    // 使用 $wpdb->prepare 安全地准备查询语句
    $sql = $wpdb->prepare(
        "SELECT option_name FROM {$wpdb->options} WHERE option_name LIKE %s",
        $escaped_prefix
    );

    $option_names = $wpdb->get_col( $sql );

    foreach ( $option_names as $option_name ) {
        // 使用核心函数 delete_option 删除，它能确保缓存被正确清理。
        delete_option( $option_name );
    }

    return count( $option_names ); // 返回删除的选项数量
}

// 调用示例：删除所有以 'wpdemo_color_' 开头的选项
// $deleted_count = wpdemo_bulk_delete_options_by_prefix( 'wpdemo_color_' );

为什么这样做？：直接使用 $wpdb 查询出所有符合前缀的选项名，然后循环调用 delete_option。这比猜测所有可能的选项名更可靠，并且利用了 delete_option 自带的缓存清理机制。使用 $wpdb->esc_like 和 prepare 是防止SQL注入的关键安全措施。

易错点

误删核心选项：直接删除像 siteurl, home, posts_per_page 等WordPress核心选项，会导致网站功能异常甚至无法访问。始终为你插件或主题的选项使用唯一且带有前缀的名称。
忽略返回值：delete_option 返回一个布尔值指示操作结果。在关键逻辑中忽略它，可能导致你无法知晓删除是否成功，进而引发后续的逻辑错误。
不安全的前缀处理：在像上面进阶用法中那样动态构建查询时，如果直接将用户输入（如来自表单的前缀）拼接进SQL语句，而未使用 $wpdb->prepare 进行转义，会造成严重的SQL注入漏洞。
混淆“删除”与“重置”：delete_option 是永久删除记录。如果你只是想将选项值恢复为空或默认值，应该使用 update_option( ‘your_option’, ’’ ) 或 update_option( ‘your_option’, $default_value )。
清理不彻底：许多插件除了 wp_options 表，还会在其他地方创建数据（如自定义表、用户元 usermeta、文章元 postmeta）。一个完整的卸载程序需要清理所有这些相关数据，而不仅仅是选项。

最佳实践

安全删除与验证

在删除任何选项前，尤其是基于用户输入决定删除哪个选项时，必须进行严格的权限和有效性检查。

function wpdemo_safe_delete_option_from_request() {
    // 1. 检查权限：确保只有有权限的管理员才能执行删除
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( '权限不足' );
    }

    // 2. 验证Nonce：确保请求来自正确的表单，防止CSRF攻击
    if ( ! isset( $_POST['wpdemo_nonce'] ) || ! wp_verify_nonce( sanitize_key( $_POST['wpdemo_nonce'] ), 'wpdemo_delete_action' ) ) {
        wp_die( '安全校验失败' );
    }

    // 3. 清理并验证输入
    $option_to_delete = isset( $_POST['option_key'] ) ? sanitize_text_field( wp_unslash( $_POST['option_key'] ) ) : '';

    // 4. 限制可删除的范围：例如，只允许删除特定前缀的选项
    $allowed_prefix = 'wpdemo_';
    if ( strpos( $option_to_delete, $allowed_prefix ) !== 0 ) {
        wp_die( '非法操作：不允许删除此选项。' );
    }

    // 5. 执行删除并处理结果
    $result = delete_option( $option_to_delete );
    if ( $result ) {
        // 删除成功，可能记录日志或重定向
        wp_safe_redirect( add_query_arg( 'message', 'deleted', wp_get_referer() ) );
        exit;
    } else {
        // 删除失败，可能是选项不存在
        wp_die( '删除失败，选项可能不存在。' );
    }
}
// 这个函数应该挂载到 `admin_post_wpdemo_delete` 这样的Action上。

利用钩子进行关联清理

WordPress提供了 delete_option_{$option} 钩子，允许你在特定选项被删除时执行附加的清理工作。这对于维护数据一致性非常有用。

// 当 `wpdemo_complex_setting` 被删除时，同时清理相关的瞬态缓存 (Transient)
add_action( 'delete_option_wpdemo_complex_setting', function( $option_name ) {
    delete_transient( 'wpdemo_calculated_data_based_on_setting' );
});

性能考量

在循环中或需要批量删除大量选项时，直接使用 delete_option 会频繁操作数据库和缓存。对于极端情况下的性能优化，可以考虑直接使用 $wpdb 进行批量删除，但必须手动清理WordPress对象缓存，因为绕过了 delete_option 函数。

function wpdemo_bulk_delete_options_direct( $option_names ) {
    global $wpdb;
    if ( empty( $option_names ) ) {
        return;
    }

    $placeholders = array_fill( 0, count( $option_names ), '%s' );
    $format = implode( ', ', $placeholders );

    // 使用 $wpdb->prepare 安全地构建 IN 子句
    $sql = $wpdb->prepare(
        "DELETE FROM {$wpdb->options} WHERE option_name IN ({$format})",
        ...$option_names // PHP 5.6+ 的参数解包
    );

    $wpdb->query( $sql );

    // 手动清理对象缓存！这是关键步骤。
    foreach ( $option_names as $name ) {
        wp_cache_delete( $name, 'options' );
    }
    // 同时清理 `alloptions` 缓存，因为 `autoload` 选项可能在其中
    wp_cache_delete( 'alloptions', 'options' );
}

请注意：除非你完全理解其影响并在性能瓶颈确实存在时，否则应优先使用循环调用 delete_option 的标准方式。

完整的生命周期管理

将选项的删除逻辑整合到插件的卸载流程中，是专业开发的标准。
1. 创建 uninstall.php 文件：在插件根目录下创建此文件。当用户通过WordPress后台“删除”插件时，此文件会被自动加载执行。
2. 在 uninstall.php 中验证：为了防止直接访问此文件导致意外数据丢失，必须检查 WP_UNINSTALL_PLUGIN 常量。

示例 uninstall.php:

<?php
// 防止直接访问
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    exit;
}

// 包含主插件文件以获取清理函数定义（如果需要）
// require_once plugin_dir_path( __FILE__ ) . 'your-main-plugin-file.php';

// 调用清理函数
function my_plugin_uninstall() {
    delete_option( 'my_plugin_settings' );
    // ... 其他清理逻辑，如删除自定义表
}

my_plugin_uninstall();
?>