分析 `wp_upload_dir()` 函数的源码，它是如何根据配置和日期生成媒体上传目录的路径和 URL 的？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位听众，早上好/下午好/晚上好！今天咱们来聊聊WordPress里一个既熟悉又重要的函数：wp_upload_dir()。别看它名字平平无奇，但它可是WordPress管理媒体上传的核心枢纽。简单来说，它负责告诉WordPress，你上传的图片、视频、文档等等，应该放在哪里，以及如何通过URL访问它们。

咱们今天就来扒一扒它的源码，看看它是怎么一步步算出这些路径和URL的。准备好，要发车了！

第一站：摸清底细 – 函数定义和基本结构

首先，我们先找到wp_upload_dir()的真身。它藏在 wp-includes/functions.php 文件里。打开它，你会看到这样的代码（简化版，省略了一些过滤器和不常用的参数）：

function wp_upload_dir( $time = null, $deprecated = false, $blog_id = null ) {
    global $switched;

    if ( $deprecated ) {
        _deprecated_argument( __FUNCTION__, '2.0' );
    }

    $siteurl = get_option( 'siteurl' );
    $upload_path = trim( get_option( 'upload_path' ) );

    if ( empty( $upload_path ) ) {
        $dir = WP_CONTENT_DIR . '/uploads';
    } else {
        $dir = ABSPATH . $upload_path;
    }

    $siteurl = untrailingslashit( $siteurl );
    $dir = untrailingslashit( $dir );
    $upload_path = untrailingslashit( $upload_path );

    $subdir = '';
    if ( get_option( 'uploads_use_yearmonth_folders' ) ) {
        // Generate the yearly and monthly folder name
        if ( ! $time ) {
            $time = current_time( 'mysql' );
        }

        $y = substr( $time, 0, 4 );
        $m = substr( $time, 5, 2 );
        $subdir = "/$y/$m";
    }

    $upload_url_path = get_option( 'upload_url_path' );
    if ( ! empty( $upload_url_path ) ) {
        $url = untrailingslashit( $upload_url_path );
    } else {
        $url = $siteurl . '/wp-content/uploads';
    }

    if ( defined( 'UPLOADS' ) && ! ( is_multisite() && ! is_main_site() && defined( 'MULTISITE' ) ) ) {
        $dir = ABSPATH . UPLOADS;
        $url = $siteurl . '/' . UPLOADS;
    }

    // Multisite check
    if ( is_multisite() ) {
        // 省略Multisite代码...
    }

    $basedir = $dir;
    $baseurl = $url;

    $dir .= $subdir;
    $url .= $subdir;

    return apply_filters( 'upload_dir', array(
        'path'   => $dir,
        'url'    => $url,
        'subdir' => $subdir,
        'basedir' => $basedir,
        'baseurl' => $baseurl,
        'error'  => false,
    ), $time, $deprecated, $blog_id );
}

可以看到，这个函数主要干了这么几件事：

获取配置信息： 从数据库里读取各种配置选项，比如upload_path、upload_url_path、uploads_use_yearmonth_folders等等。
确定基本目录和URL： 根据配置信息，计算出上传目录的基本路径（$dir）和URL（$url）。
生成子目录： 如果启用了按年月分文件夹的功能，就生成年月形式的子目录（$subdir）。
拼接路径和URL： 把基本目录、URL和子目录拼接起来，得到最终的上传目录路径和URL。
Multisite处理： 如果是多站点模式，还要进行额外的处理，确保每个站点都有自己的上传目录。
过滤器： 最后，通过upload_dir过滤器，允许开发者自定义上传目录的路径和URL。

第二站：配置信息大揭秘

wp_upload_dir() 函数依赖于一些重要的配置选项，这些选项决定了上传目录的结构。咱们来逐个击破：

配置选项	描述	默认值	备注
`upload_path`	上传目录的路径，相对于WordPress根目录（`ABSPATH`）。如果为空，则使用默认的 `wp-content/uploads` 目录。	空字符串	这个选项允许你把上传目录放在 WordPress 安装目录之外，比如放在 `/var/www/uploads` 这样的位置。注意：如果修改了这个选项，你需要确保 WordPress 有权限访问这个目录。
`upload_url_path`	上传目录的URL。如果为空，则使用默认的 `siteurl/wp-content/uploads` URL。	空字符串	这个选项允许你把上传目录放在不同的域名或子域名下，比如 `cdn.example.com/uploads`。注意：如果修改了这个选项，你需要确保这个URL指向的目录和 `upload_path` 指向的目录是同一个。
`uploads_use_yearmonth_folders`	是否启用按年月分文件夹的功能。如果启用，上传的文件会被放在 `year/month` 形式的子目录里。	`1` (启用)	启用这个选项可以更好地组织上传的文件，方便查找和管理。
`siteurl`	WordPress站点的URL。	在WordPress设置里配置	这个选项是WordPress的核心配置，必须正确设置。
`UPLOADS` (常量)	如果定义了这个常量，它会覆盖 `upload_path` 和 `upload_url_path` 的设置。	未定义	这个常量提供了一种更直接的方式来定义上传目录的位置。注意：只有在非多站点主站点下才有效。
`MULTISITE` (常量) 和 `is_multisite()`	决定是否是多站点模式。	根据WordPress的安装方式决定	在多站点模式下，上传目录的处理方式会更加复杂，每个站点都有自己的上传目录。

这些配置选项都存储在 wp_options 表里。你可以通过 get_option() 函数来读取它们的值。

第三站：目录和URL的计算过程

现在，咱们来一步步分析 wp_upload_dir() 函数是如何计算上传目录的路径和URL的。

获取基本路径和URL：
- 首先，函数会读取 upload_path 选项。如果这个选项为空，就使用默认的 WP_CONTENT_DIR . '/uploads' 作为基本目录。否则，就使用 ABSPATH . $upload_path 作为基本目录。
- 然后，函数会读取 upload_url_path 选项。如果这个选项为空，就使用默认的 $siteurl . '/wp-content/uploads' 作为基本URL。否则，就使用 $upload_url_path 作为基本URL。
- 如果定义了 UPLOADS 常量，并且不是多站点主站点，函数会直接使用 ABSPATH . UPLOADS 作为基本目录， $siteurl . '/' . UPLOADS 作为基本URL。
生成子目录：
- 如果启用了 uploads_use_yearmonth_folders 选项，函数会根据当前时间（或者传入的 $time 参数）生成 year/month 形式的子目录。
- 例如，如果当前时间是 2023年10月，那么生成的子目录就是 /2023/10。
拼接路径和URL：
- 函数会把基本目录、URL和子目录拼接起来，得到最终的上传目录路径和URL。
- 例如，如果基本目录是 /var/www/wordpress/wp-content/uploads，子目录是 /2023/10，那么最终的上传目录路径就是 /var/www/wordpress/wp-content/uploads/2023/10。
- 同样，如果基本URL是 https://example.com/wp-content/uploads，子目录是 /2023/10，那么最终的上传目录URL就是 https://example.com/wp-content/uploads/2023/10。
Multisite处理：
- 在多站点模式下，每个站点都有自己的上传目录。
- wp_upload_dir() 函数会根据当前站点的ID，生成一个唯一的子目录，用于区分不同站点的上传文件。
- 具体的多站点逻辑比较复杂，这里就不展开讲了。

第四站：代码示例 – 模拟 wp_upload_dir() 的行为

为了更好地理解 wp_upload_dir() 函数的工作原理，咱们来写一段简单的代码，模拟它的行为。

<?php

// 模拟 get_option() 函数
function my_get_option( $option ) {
    $options = array(
        'upload_path'                  => '',
        'upload_url_path'              => '',
        'uploads_use_yearmonth_folders' => 1,
        'siteurl'                      => 'https://example.com',
    );

    if ( isset( $options[ $option ] ) ) {
        return $options[ $option ];
    }

    return ''; // 默认返回空字符串
}

// 模拟 ABSPATH 和 WP_CONTENT_DIR 常量
define( 'ABSPATH', '/var/www/wordpress/' );
define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' );

// 模拟 is_multisite() 函数
function my_is_multisite() {
    return false; // 假设不是多站点模式
}

// 模拟 current_time() 函数
function my_current_time( $format ) {
    if ( $format == 'mysql' ) {
        return date( 'Y-m-d H:i:s' );
    }

    return date( $format );
}

function my_wp_upload_dir( $time = null ) {
    $siteurl = my_get_option( 'siteurl' );
    $upload_path = trim( my_get_option( 'upload_path' ) );

    if ( empty( $upload_path ) ) {
        $dir = WP_CONTENT_DIR . '/uploads';
    } else {
        $dir = ABSPATH . $upload_path;
    }

    $siteurl = rtrim( $siteurl, '/' );
    $dir = rtrim( $dir, '/' );
    $upload_path = rtrim( $upload_path, '/' );

    $subdir = '';
    if ( my_get_option( 'uploads_use_yearmonth_folders' ) ) {
        // Generate the yearly and monthly folder name
        if ( ! $time ) {
            $time = my_current_time( 'mysql' );
        }

        $y = substr( $time, 0, 4 );
        $m = substr( $time, 5, 2 );
        $subdir = "/$y/$m";
    }

    $upload_url_path = my_get_option( 'upload_url_path' );
    if ( ! empty( $upload_url_path ) ) {
        $url = rtrim( $upload_url_path, '/' );
    } else {
        $url = $siteurl . '/wp-content/uploads';
    }

    $basedir = $dir;
    $baseurl = $url;

    $dir .= $subdir;
    $url .= $subdir;

    return array(
        'path'   => $dir,
        'url'    => $url,
        'subdir' => $subdir,
        'basedir' => $basedir,
        'baseurl' => $baseurl,
        'error'  => false,
    );
}

// 调用模拟函数
$upload_dir = my_wp_upload_dir();

// 打印结果
echo '<pre>';
print_r( $upload_dir );
echo '</pre>';

?>

这段代码模拟了 wp_upload_dir() 函数的基本行为。你可以修改 my_get_option() 函数里的配置选项，看看输出结果会发生什么变化。

第五站：过滤器 – 自定义上传目录

wp_upload_dir() 函数提供了一个 upload_dir 过滤器，允许开发者自定义上传目录的路径和URL。这意味着你可以完全控制上传目录的位置和访问方式。

下面是一个使用 upload_dir 过滤器的例子：

<?php

add_filter( 'upload_dir', 'my_custom_upload_dir' );

function my_custom_upload_dir( $dirs ) {
    $dirs['path']   = '/var/www/my-uploads';
    $dirs['url']    = 'https://cdn.example.com/my-uploads';
    $dirs['basedir'] = '/var/www/my-uploads';
    $dirs['baseurl'] = 'https://cdn.example.com/my-uploads';

    return $dirs;
}

?>

这段代码会把上传目录的路径和URL修改为 /var/www/my-uploads 和 https://cdn.example.com/my-uploads。

第六站：总结和注意事项

wp_upload_dir() 函数是WordPress管理媒体上传的核心。
它依赖于一些重要的配置选项，比如 upload_path、upload_url_path 和 uploads_use_yearmonth_folders。
它会根据配置信息和当前时间，计算出上传目录的路径和URL。
它提供了一个 upload_dir 过滤器，允许开发者自定义上传目录的路径和URL。
在使用 wp_upload_dir() 函数时，需要注意以下几点：
- 确保 WordPress 有权限访问上传目录。
- 正确设置 upload_path 和 upload_url_path 选项，确保它们指向同一个目录。
- 在多站点模式下，要特别注意上传目录的处理方式。
- 合理使用 upload_dir 过滤器，可以实现各种自定义需求。

第七站：实际应用场景

CDN加速： 将上传目录放在CDN上，可以加速媒体文件的访问速度。
文件服务器： 将上传目录放在独立的文件服务器上，可以减轻主服务器的压力。
多站点管理： 在多站点模式下，可以使用 upload_dir 过滤器，为每个站点分配独立的上传目录。
安全增强： 可以将上传目录放在 WordPress 安装目录之外，防止恶意用户上传恶意文件。

第八站：常见问题解答

Q: 我修改了 upload_path 选项，但是上传的文件还是放在默认的 wp-content/uploads 目录里，这是怎么回事？
- A: 可能是因为你的主题或插件使用了 wp_upload_dir() 函数的缓存。你可以尝试清除缓存，或者重启服务器。
Q: 我想把上传目录放在不同的域名下，应该怎么做？
- A: 你需要修改 upload_url_path 选项，并确保这个域名指向的目录和 upload_path 指向的目录是同一个。
Q: 我想禁用按年月分文件夹的功能，应该怎么做？
- A: 你可以把 uploads_use_yearmonth_folders 选项设置为 0。

最后一站：结语

希望通过今天的讲解，大家对 wp_upload_dir() 函数有了更深入的了解。掌握了这个函数，你就可以更好地管理WordPress的媒体上传，实现各种自定义需求。记住，代码是最好的老师，多动手实践才能真正掌握。感谢大家的收听，下课！

发表回复 取消回复

发表回复取消回复