深入理解 WordPress `switch_to_blog()` 和 `restore_current_blog()` 函数的源码：如何在多站点环境中安全地切换站点上下文。

大家好，欢迎来到今天的“WordPress 多站点奇妙之旅”讲座！今天咱们要聊聊 WordPress 多站点里两个非常重要的函数：switch_to_blog() 和 restore_current_blog()。这俩哥们儿就像多站点世界的传送门，能让你在不同的站点之间自由穿梭。但是，传送门用不好，可是会出大事的！所以，今天我们就来扒一扒它们的源码，看看如何安全可靠地使用它们。

首先，咱们先来打个招呼，用代码的方式：

<?php
/**
 *  这是一个友好的打招呼函数
 */
function say_hello_to_audience() {
    echo "<h1>嘿，各位大佬，晚上好！</h1>";
    echo "<p>今天我们一起探索多站点宇宙，Let's go!</p>";
}

say_hello_to_audience();
?>

好，打完招呼，进入正题。

一、多站点是个啥？为什么要用 switch_to_blog() 和 restore_current_blog()？

想象一下，你要管理一个网站联盟，每个网站都长得不一样，功能也不尽相同。如果每个网站都要单独安装一个 WordPress，那简直是噩梦！多站点就是来拯救你的。

多站点允许你在一个 WordPress 安装下，管理多个网站。这些网站共享核心代码、主题和插件，但有各自的数据库表、上传目录和用户。

但是，问题来了：你怎么在一个 WordPress 安装里，操作不同站点的数据呢？这就是 switch_to_blog() 和 restore_current_blog() 的用武之地。

switch_to_blog( $new_blog_id )：这个函数就像一个传送门，把你当前的 WordPress 上下文切换到 ID 为 $new_blog_id 的站点。切换之后，所有的数据库查询、主题函数、插件操作都会针对新的站点。

restore_current_blog()：这个函数就像一个回城卷轴，把你从新的站点传送回原来的站点。

二、switch_to_blog() 源码解析：传送门的秘密

让我们打开 WordPress 源码，找到 wp-includes/ms-functions.php 文件（或者直接搜索函数名），看看 switch_to_blog() 的真面目。

简化后的 switch_to_blog() 源码如下：

function switch_to_blog( $new_blog, $deprecated = '' ) {
    global $wpdb, $switched, $blog_id, $table_prefix, $wp_theme_directories;

    // Back compat.
    if ( ! empty( $deprecated ) ) {
        _deprecated_argument( __FUNCTION__, '3.5' );
    }

    $new_blog = (int) $new_blog;

    if ( empty( $new_blog ) ) {
        return false;
    }

    if ( $new_blog == $blog_id ) {
        return true; // Already on this blog.
    }

    $old_blog = $blog_id;

    $switched = true;

    // Switch.
    $blog_id        = $new_blog;
    $table_prefix   = $wpdb->get_blog_prefix( $new_blog );

    // Switch user object
    switch_to_user_blog( get_current_user_id(), $new_blog );

    // Clear caches.
    wp_cache_switch_to_blog( $new_blog );

    /**
     * Fires immediately before switching to a blog ID.
     *
     * @since 2.3.0
     *
     * @param int $new_blog ID of the blog to switch to.
     * @param int $old_blog ID of the current blog.
     */
    do_action( 'switch_to_blog', $new_blog, $old_blog );

    return true;
}

我们来逐行解读：

参数校验： 首先，它会把 $new_blog 转换成整数，并检查是否为空或与当前站点 ID 相同。如果是，就直接返回，避免不必要的切换。
记录旧站点： 它会把当前的 $blog_id 存储到 $old_blog 变量中。这个变量非常重要，稍后 restore_current_blog() 会用到它。
设置全局变量： 关键步骤来了！它会修改全局变量 $blog_id 和 $table_prefix。 $blog_id 变成新的站点 ID，$table_prefix 变成新站点对应的数据库表前缀。这意味着，之后所有的数据库查询都会针对新的站点。
切换用户上下文： switch_to_user_blog() 这个函数用于切换当前用户的站点上下文，确保权限和用户数据正确。
清除缓存： wp_cache_switch_to_blog() 函数会清除与当前站点相关的缓存，防止缓存数据污染。
触发钩子： do_action( 'switch_to_blog', $new_blog, $old_blog ) 触发一个 action 钩子，允许开发者在站点切换前后执行自定义操作。

总结： switch_to_blog() 的核心就是修改全局变量 $blog_id 和 $table_prefix，以及清除缓存，让 WordPress 认为你正在操作一个新的站点。

三、restore_current_blog() 源码解析：回城卷轴的奥秘

同样，我们来扒一扒 restore_current_blog() 的源码：

function restore_current_blog() {
    global $wpdb, $switched, $blog_id, $table_prefix, $current_site, $current_blog, $wp_theme_directories;

    if ( ! $switched ) {
        return true; // If we haven't switched, there is nothing to do.
    }

    $switched = false;

    // Restore the user's blog to prevent access issues.
    restore_current_user_blog();

    // Switch back.
    $blog = get_site()->blog_id; // Use get_site() to avoid the blog cache.
    $blog_id        = $blog;
    $table_prefix   = $wpdb->get_blog_prefix( $blog );

    // Clear caches.
    wp_cache_switch_to_blog( $blog );

    /**
     * Fires immediately after switching back to the original blog ID.
     *
     * @since 2.3.0
     *
     * @param int $new_blog ID of the blog switched back to.
     * @param int $old_blog ID of the blog switched from.
     */
    do_action( 'restore_current_blog', $blog, get_current_blog_id() );

    return true;
}

解读：

检查是否切换过： 它首先检查 $switched 变量是否为 true。如果为 false，说明你没有切换过站点，直接返回。
恢复用户上下文： restore_current_user_blog() 函数用于恢复当前用户的站点上下文，确保权限和用户数据正确。
恢复全局变量： 关键步骤！它会把 $blog_id 和 $table_prefix 恢复到原来的值。这里使用 get_site()->blog_id 来获取主站点的 ID，避免使用缓存。
清除缓存： 再次清除缓存，确保数据一致性。
触发钩子： 触发 restore_current_blog action 钩子，允许开发者在站点恢复后执行自定义操作。

总结： restore_current_blog() 的核心就是把全局变量 $blog_id 和 $table_prefix 恢复到切换之前的状态，并清除缓存。

四、如何安全地使用 switch_to_blog() 和 restore_current_blog()？

这两个函数虽然强大，但使用不当，可能会导致数据混乱、权限问题等严重后果。下面是一些安全使用建议：

成对使用： 必须成对使用 switch_to_blog() 和 restore_current_blog()。就像打开和关闭文件一样，切换到新站点后，一定要记得返回。

try…finally 代码块： 使用 try...finally 代码块，确保 restore_current_blog() 始终会被执行，即使在 switch_to_blog() 之后的代码发生错误。

<?php
$original_blog_id = get_current_blog_id(); // 备份原始 blog ID

try {
    switch_to_blog( $target_blog_id );

    // 在新站点上执行操作
    update_option( 'my_option', 'some_value' );

} catch ( Exception $e ) {
    // 处理异常
    error_log( 'Error occurred: ' . $e->getMessage() );
} finally {
    // 确保总是恢复到原始站点
    switch_to_blog( $original_blog_id ); // 恢复原始 blog ID
}
?>

备份当前站点 ID： 在切换站点之前，备份当前的站点 ID。虽然 restore_current_blog() 会自动恢复，但备份一下总是好的。
谨慎操作数据库： 在切换到新站点后，要特别小心数据库操作。确保你的 SQL 查询针对的是正确的表。
注意用户权限： 切换站点可能会影响用户权限。确保你在新站点上的操作符合用户的权限设置。
避免嵌套切换： 尽量避免在 switch_to_blog() 之后再次调用 switch_to_blog()。如果必须嵌套，一定要小心管理站点 ID，确保正确恢复。

五、实战演练：一个简单的例子

假设我们要在所有站点上创建一个新的 option。

<?php
/**
 * 在所有站点上创建 option
 */
function create_option_on_all_sites( $option_name, $option_value ) {
    global $wpdb;

    $original_blog_id = get_current_blog_id(); // 备份原始站点 ID
    $blog_ids = $wpdb->get_col( "SELECT blog_id FROM {$wpdb->blogs}" ); // 获取所有站点 ID

    foreach ( $blog_ids as $blog_id ) {
        switch_to_blog( $blog_id );

        // 在当前站点上创建 option
        add_option( $option_name, $option_value );

        restore_current_blog();
    }

    switch_to_blog( $original_blog_id ); // 切换回原始站点，确保后续操作在正确的上下文中
}

// 调用函数
create_option_on_all_sites( 'my_new_option', 'Hello from all sites!' );
?>

这个例子展示了如何安全地遍历所有站点，并在每个站点上执行相同的操作。

六、进阶技巧：利用钩子进行扩展

switch_to_blog 和 restore_current_blog 提供了 action 钩子，允许我们自定义站点切换前后的操作。

switch_to_blog: 在切换到新站点之前触发。
restore_current_blog: 在恢复到原始站点之后触发。

我们可以利用这些钩子来执行一些高级操作，例如：

记录站点切换日志
更新站点缓存
发送通知邮件

七、常见问题及解答

问题	解决方案
忘记调用 `restore_current_blog()` 导致数据混乱	确保使用 `try...finally` 代码块，始终执行 `restore_current_blog()`。
站点切换后用户权限出现问题	检查 `switch_to_user_blog()` 函数是否正确调用，并确保用户在新站点上拥有必要的权限。
嵌套调用 `switch_to_blog()` 导致站点 ID 错乱	尽量避免嵌套调用。如果必须嵌套，需要手动管理站点 ID，并在恢复时按照正确的顺序调用 `restore_current_blog()`。
缓存问题导致数据不一致	在站点切换前后，调用 `wp_cache_switch_to_blog()` 函数清除缓存。

八、总结

switch_to_blog() 和 restore_current_blog() 是 WordPress 多站点开发中的利器。掌握它们的原理和使用方法，可以让你在多站点环境中游刃有余。记住，安全第一！遵循最佳实践，才能避免踩坑。

希望今天的讲座对大家有所帮助！如果还有什么问题，欢迎提问。祝大家在多站点世界里玩得开心！

发表回复 取消回复

发表回复取消回复