WordPress自定义插件文件上传功能故障排查求助

问题根源分析 #

你的代码存在几个核心问题，直接导致文件提交后跳404且无响应：

• 缺失安全验证（Nonce）：WordPress后台会拦截未携带有效nonce的POST请求，直接返回404，这是核心原因
• 直接使用原生PHP上传函数：move_uploaded_file未遵循WordPress上传规范，易触发权限或安全机制拦截
• 错误使用wp_die()：在处理函数末尾调用会中断页面正常渲染，不符合后台表单提交逻辑

修正后的完整代码 #

<?php
/*
Plugin Name: MyPage
Plugin URI: https://yourwebsite.com/
Description: A plugin to upload audio and video files to the MyPage folder.
Version: 1.0
Author: Me
Author URI: https://yourwebsite.com/
*/

if (!defined('ABSPATH')) {
    exit; // Exit if accessed directly
}

// Hook to add a menu item in the WordPress admin dashboard
add_action('admin_menu', 'myPage_menu');

function myPage_menu() {
    add_menu_page(
        'MyPage',
        'MyPage',
        'manage_options',
        'myPage',
        'myPage_page',
        'dashicons-media-audio'
    );
}

// Function to display the form on the plugin page
function myPage_page() {
    $message = '';
    // Check if the form has been submitted and handle the file upload
    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
        $message = myPage_handle_upload();
    }
    ?>
    <div class="wrap">
        <h1>MyPage</h1>
        <form id="myPage-form" method="post" enctype="multipart/form-data" action="<?php echo esc_url(admin_url('admin.php?page=myPage')); ?>">
            <?php wp_nonce_field('myPage_upload_nonce', 'myPage_nonce'); ?>
            <input type="file" name="myPage_file" id="myPage_file" accept="audio/*,video/*" required>
            <button type="submit" id="myPage_submit">Upload File</button>
        </form>
        <?php if (!empty($message)) : ?>
            <div id="myPage_message" class="notice notice-<?php echo strpos($message, '成功') ? 'success' : 'error'; ?> is-dismissible">
                <p><?php echo esc_html($message); ?></p>
            </div>
        <?php endif; ?>
    </div>
    <?php
}

// Handle file upload on form submission
function myPage_handle_upload() {
    // 验证nonce和权限
    if (!isset($_POST['myPage_nonce']) || !wp_verify_nonce($_POST['myPage_nonce'], 'myPage_upload_nonce')) {
        return '非法请求，请重试。';
    }

    if (!current_user_can('manage_options')) {
        return '权限不足，无法执行上传操作。';
    }

    if (!isset($_FILES['myPage_file']) || $_FILES['myPage_file']['error'] !== UPLOAD_ERR_OK) {
        switch ($_FILES['myPage_file']['error']) {
            case UPLOAD_ERR_INI_SIZE:
            case UPLOAD_ERR_FORM_SIZE:
                return '文件大小超出限制。';
            case UPLOAD_ERR_NO_FILE:
                return '未选择要上传的文件。';
            default:
                return '文件上传出错，请检查后重试。';
        }
    }

    // 使用WordPress官方上传函数处理
    $upload_overrides = array(
        'test_form' => false,
        'unique_filename_callback' => 'myPage_unique_filename'
    );

    $upload_result = wp_handle_upload($_FILES['myPage_file'], $upload_overrides);

    if ($upload_result && !isset($upload_result['error'])) {
        // 创建自定义目录
        $upload_dir = wp_upload_dir();
        $target_dir = $upload_dir['basedir'] . '/my-page/';
        wp_mkdir_p($target_dir);

        // 移动文件到自定义目录
        $target_file = $target_dir . basename($upload_result['file']);
        if (rename($upload_result['file'], $target_file)) {
            // 可选：将文件添加到媒体库
            $attachment = array(
                'guid' => $upload_dir['baseurl'] . '/my-page/' . basename($target_file),
                'post_mime_type' => $upload_result['type'],
                'post_title' => sanitize_file_name(basename($target_file)),
                'post_content' => '',
                'post_status' => 'inherit'
            );
            wp_insert_attachment($attachment, $target_file);
            return '文件上传成功：' . esc_html(basename($target_file));
        } else {
            unlink($upload_result['file']);
            return '无法将文件移动到目标目录，请检查目录权限。';
        }
    } else {
        return $upload_result['error'];
    }
}

// 可选：生成唯一文件名避免覆盖
function myPage_unique_filename($dir, $name, $ext) {
    $filename = pathinfo($name, PATHINFO_FILENAME);
    $counter = 1;
    while (file_exists($dir . '/' . $filename . $ext)) {
        $filename = pathinfo($name, PATHINFO_FILENAME) . '-' . $counter;
        $counter++;
    }
    return $filename . $ext;
}
?>

关键修复点说明 #

• 添加Nonce验证：通过wp_nonce_field生成安全令牌，提交时用wp_verify_nonce验证，避免请求被WordPress安全机制拦截
• 使用wp_handle_upload：WordPress官方上传函数，自动处理权限、文件类型验证、临时文件管理，比原生函数更安全合规
• 明确表单Action：指定提交到当前插件页面URL，避免空Action导致的路径问题
• 完善错误处理：针对不同上传错误返回明确提示，便于排查
• 可选媒体库集成：通过wp_insert_attachment将文件添加到媒体库，方便后续管理

额外排查建议 #

1. 检查服务器upload_max_filesize和post_max_size配置，确保能容纳音视频文件
2. 确认wp-content/uploads目录权限为755（所有者为服务器运行用户）
3. 开启WordPress调试模式（wp-config.php中设置WP_DEBUG=true），查看隐藏错误日志

内容的提问来源于stack exchange，提问作者Zachary Rodriguez