WordPress函数：update_option 更新设置

简介

update_option 是 WordPress 存储、更新和持久化网站设置的核心机制。它让你轻松地将数据（如网站标题、开关状态、用户配置等）保存到数据库的 wp_options 表中，供后续任何页面请求时读取。

语法

该函数定义于 wp-includes/option.php 文件中。

update_option( string $option, mixed $value, string|bool $autoload = null ): bool

参数	类型	默认值	说明
`$option`	`string`	(必填)	要更新的选项名称。应仅包含小写字母、数字和下划线，建议使用蛇形命名法。
`$value`	`mixed`	(必填)	选项的新值。可以是字符串、数字、数组、对象等。非标量数据（数组、对象）会被自动序列化后存储。
`$autoload`	`string` \| `bool`	`null`	控制此选项是否在 WordPress 初始化时自动加载到缓存中。 – `‘yes’` 或 `true`: 自动加载（默认，适合频繁访问的选项）。 – `‘no’` 或 `false`: 不自动加载（适合极少用到的选项，节约内存）。 – `null`: 保持该选项当前的自动加载状态不变。
返回值	`bool`		更新成功返回 `true`，若新值与旧值相同则返回 `false`。

内部逻辑上，update_option 会首先调用 get_option 检查原值，若值未改变则直接返回 false，避免了不必要的数据库写入。若值发生改变，它会对值进行序列化（如果需要），并使用 wpdb->update 方法安全地更新数据库。

用法

基础用法

最直接的应用就是更新一个简单的标量值。下面的示例展示了如何在插件或主题的某个处理逻辑中，保存用户提交的网站联系电话。

// 当用户在某个表单提交了新的联系电话时（例如在自定义设置页面）
if ( isset( $_POST['phone_number'] ) && current_user_can( 'manage_options' ) ) {
    // 在保存前，必须进行验证、清理和权限检查
    $clean_phone_number = sanitize_text_field( wp_unslash( $_POST['phone_number'] ) );

    // 调用 update_option 将清理后的值保存到数据库
    $update_result = update_option( 'my_theme_contact_phone', $clean_phone_number );

    if ( $update_result ) {
        // 保存成功，可以进行后续操作，如设置成功消息
        add_settings_error( 'my_settings_page', 'phone_updated', '联系电话已更新。', 'success' );
    } else {
        // 保存失败或值未改变
        add_settings_error( 'my_settings_page', 'phone_unchanged', '联系电话未更改。', 'info' );
    }
}

进阶用法

存储结构化数据（数组或对象）

许多插件或主题需要存储一组相关的配置，使用数组可以避免为每个值单独创建一个选项，减少数据库查询。

// 将一组相关的社交链接配置作为一个选项存储
$social_links = array(
    'facebook'  => 'https://facebook.com/yourpage',
    'twitter'   => 'https://twitter.com/yourhandle',
    'instagram' => 'https://instagram.com/yourprofile',
    'linkedin'  => '',
);

// update_option 会自动将数组序列化为字符串后存储
$updated = update_option( 'my_theme_social_media_links', $social_links );

// 读取时，get_option 会自动反序列化，直接返回数组
$links = get_option( 'my_theme_social_media_links', array() );
echo esc_url( $links['facebook'] );

批量更新与自动加载优化

在插件激活或主题切换时，可能需要初始化多个选项，并精细控制它们的自动加载行为以优化性能。

// 在主题的 `after_switch_theme` 钩子中初始化设置
function my_theme_setup_default_options() {
    // 核心配置，几乎每个页面都会用到，设为自动加载
    update_option( 'my_theme_layout_mode', 'full-width', true ); // 或 'yes'
    update_option( 'my_theme_color_scheme', 'light', true );

    // 日志或诊断信息，仅在后台特定页面查看，设为不自动加载以节省内存
    update_option( 'my_theme_last_updated', current_time( 'mysql' ), false ); // 或 'no'
    update_option( 'my_theme_debug_log', array(), false );
}
add_action( 'after_switch_theme', 'my_theme_setup_default_options' );

易错点

错误理解返回值：update_option 在选项值实际发生变化时返回 true，在值相同、更新失败或数据库错误时返回 false。不能仅凭 false 就断定发生了错误。若需要无条件写入数据库，应结合 delete_option 使用，但这不推荐，因为会破坏 autoload 设置。
混淆 autoload 参数：将大量不常用或体积大的选项（如缓存的数据、日志）设置为 autoload=‘yes’ 会导致每个页面加载时 WordPress 都需要从数据库读取这些数据，显著增加内存消耗和页面加载时间。正确区分“高频”和“低频”访问的选项是关键。
序列化与非序列化数据混淆：直接向存储了序列化数据的选项追加字符串或进行字符串替换，会破坏其序列化结构，导致 get_option 读取时失败或返回错误数据。永远不要手动拼接或修改已序列化的值。
忽视权限检查和安全处理：在直接处理 $_POST、$_GET 等用户输入来调用 update_option 时，若未进行能力检查、数据验证和清理，将导致严重的权限绕过和数据污染风险。WordPress 提供了 Settings API 来系统化地处理这个问题。
选项命名冲突：使用过于通用的选项名（如 ‘theme_settings’, ‘plugin_config’）极易与其他插件或主题发生冲突，导致数据被意外覆盖或读取错误。务必为选项名添加唯一前缀。

最佳实践

安全性：通过设置API进行验证和清洗

对于需要在管理后台呈现的设置页面，强烈建议使用 WordPress 的 Settings API。它将选项注册、表单渲染、数据验证、安全检查和自动保存封装在一起，是最安全、最规范的处理方式。

// 1. 注册设置
function my_theme_register_settings() {
    register_setting(
        'my_theme_options_group', // 设置组名，与 settings_fields() 对应
        'my_theme_contact_phone', // 选项名，即 update_option 的第一个参数
        array(
            'type'              => 'string',
            'sanitize_callback' => 'my_theme_sanitize_phone', // 自定义清洗函数
            'default'           => '',
        )
    );
}
add_action( 'admin_init', 'my_theme_register_settings' );

// 2. 定义清洗函数
function my_theme_sanitize_phone( $input ) {
    $cleaned = sanitize_text_field( $input );
    // 可以添加更多验证逻辑，例如格式检查
    if ( ! preg_match( '/^[\d\s\-\+\(\)]+$/', $cleaned ) ) {
        // 验证失败，可返回旧值或添加错误信息
        add_settings_error( 'my_theme_contact_phone', 'invalid_phone', '电话号码格式无效。' );
        return get_option( 'my_theme_contact_phone' ); // 返回原值，不更新
    }
    return $cleaned;
}
// 后续通过 Settings API 自动生成表单，用户提交后，WordPress 会自动调用 update_option

性能优化：善用autoload

默认设为‘no’：在创建新选项时，除非你确信它会在绝大多数页面的前端或后台逻辑中被用到，否则应显式地将 $autoload 设置为 ‘no’。
批量转移：如果发现 wp_options 表中自动加载的选项过多，可以使用 wp-cli 命令 (wp option list --autoload=on --format=count) 进行审计，并使用 wp option update <key> --autoload=no 或相关代码批量调整。

代码组织与可维护性：面向对象开发中的封装

在现代 WordPress 插件或主题开发中，将选项操作封装在一个类中可以提高可维护性，避免选项名在代码中硬编码。

class MyPlugin_Settings {
    const OPTION_NAME_PREFIX = 'myplugin_';

    private static $defaults = array(
        'api_key'     => '',
        'cache_ttl'   => 3600,
        'is_enabled'  => true,
    );

    public static function get( $key, $default = null ) {
        $full_key = self::OPTION_NAME_PREFIX . $key;
        $value = get_option( $full_key, self::$defaults[ $key ] ?? $default );
        // 可在此处添加全局的过滤器
        return apply_filters( "myplugin_get_option_{$key}", $value );
    }

    public static function update( $key, $value, $autoload = null ) {
        $full_key = self::OPTION_NAME_PREFIX . $key;
        // 在更新前可以进行集中验证或记录
        do_action( "myplugin_before_update_option_{$key}", $value, $autoload );
        return update_option( $full_key, $value, $autoload );
    }
}
// 使用方式
$api_key = MyPlugin_Settings::get( 'api_key' );
$updated = MyPlugin_Settings::update( 'cache_ttl', 7200, 'yes' );

与现代开发模式的结合

REST API：如果你正在构建一个使用 WordPress REST API 的现代前端（如 React、Vue 应用），可以通过注册设置到 settings 端点，使前端能够安全地读写这些选项。这通常需要结合 register_rest_route 创建自定义端点，或在插件中扩展 WP_REST_Settings_Controller。

版本兼容性与数据升级

对于需要存储复杂结构数据的插件，当数据结构需要改变时（例如从版本 1.0 升级到 2.0），直接更新可能导致旧数据无法识别。一个健壮的做法是引入“版本号”选项。

// 插件激活或加载时检查数据版本
function my_plugin_check_data_version() {
    $current_data_version = get_option( 'my_plugin_data_version', '1.0' );

    if ( version_compare( $current_data_version, '2.0', '<' ) ) {
        // 执行从 1.0 到 2.0 的数据结构迁移逻辑
        $old_option = get_option( 'my_plugin_old_data' );
        if ( $old_option ) {
            $new_option = my_plugin_migrate_data_to_v2( $old_option );
            update_option( 'my_plugin_new_data', $new_option, true );
            delete_option( 'my_plugin_old_data' ); // 清理旧数据
        }
        // 更新版本标记
        update_option( 'my_plugin_data_version', '2.0', true );
    }
}
add_action( 'admin_init', 'my_plugin_check_data_version' );