WooCommerce产品数据常规标签添加自定义文件上传字段并实现单品页下载

核心思路 #

直接用表单file类型字段会遇到WooCommerce后台表单未配置enctype="multipart/form-data"、文件存储逻辑不兼容WordPress机制的问题。正确的做法是借助WordPress原生媒体选择器，让用户从媒体库选择或上传文件，保存附件ID而非文件路径，这样既能兼容权限控制，又能保证文件存储的可靠性。

完整实现代码 #

将以下代码添加到主题的functions.php文件中，或者自定义插件里：

1. 添加自定义字段到产品数据常规标签

add_action('woocommerce_product_options_general_product_data', 'add_custom_product_file_upload_field');
function add_custom_product_file_upload_field() {
    // 添加文本输入框存储附件ID
    woocommerce_wp_text_input(array(
        'id'          => '_custom_product_file_id',
        'label'       => __('自定义下载文件', 'woocommerce'),
        'placeholder' => __('点击右侧按钮选择或上传文件', 'woocommerce'),
        'desc_tip'    => true,
        'description' => __('支持PDF、DOC、XLSX等格式', 'woocommerce'),
        'class'       => 'custom-file-input'
    ));

    // 添加媒体选择按钮
    echo '<button type="button" class="button custom-file-select" data-input-id="_custom_product_file_id">' . __('选择/上传文件', 'woocommerce') . '</button>';
}

2. 引入媒体选择器JS逻辑

add_action('admin_footer', 'custom_product_file_upload_js');
function custom_product_file_upload_js() {
    // 只在产品编辑页面加载
    if (get_current_screen()->id !== 'product') return;
    ?>
    <script>
        jQuery(document).ready(function($) {
            $('.custom-file-select').on('click', function(e) {
                e.preventDefault();
                var inputId = $(this).data('input-id');
                var fileFrame = wp.media({
                    title: '选择或上传文件',
                    button: { text: '选择文件' },
                    multiple: false,
                    library: { type: ['application/pdf', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/vnd.ms-excel', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'] }
                });

                fileFrame.on('select', function() {
                    var attachment = fileFrame.state().get('selection').first().toJSON();
                    $('#' + inputId).val(attachment.id);
                });

                fileFrame.open();
            });
        });
    </script>
    <?php
}

3. 保存自定义字段的附件ID

add_action('woocommerce_process_product_meta', 'save_custom_product_file_upload_field');
function save_custom_product_file_upload_field($post_id) {
    if (isset($_POST['_custom_product_file_id'])) {
        update_post_meta($post_id, '_custom_product_file_id', absint($_POST['_custom_product_file_id']));
    } else {
        delete_post_meta($post_id, '_custom_product_file_id');
    }
}

4. 在单品页面显示下载链接

add_action('woocommerce_single_product_summary', 'display_custom_product_file_download_link', 25);
function display_custom_product_file_download_link() {
    global $product;
    $file_id = get_post_meta($product->get_id(), '_custom_product_file_id', true);
    
    if ($file_id) {
        $file_url = wp_get_attachment_url($file_id);
        $file_name = get_the_title($file_id);
        
        echo '<div class="custom-file-download">';
        echo '<p><strong>' . __('下载附件：', 'woocommerce') . '</strong><a href="' . esc_url($file_url) . '" target="_blank" download>' . esc_html($file_name) . '</a></p>';
        echo '</div>';
    }
}

代码说明 #

• 媒体选择器限制了文件类型，只允许PDF、DOC、DOCX、XLS、XLSX，符合需求；
• 保存的是附件ID，而非直接路径，后续如果文件在媒体库中被修改，链接会自动更新；
• 单品页的下载链接添加了download属性，触发浏览器下载行为，同时用esc_url和esc_html保证安全；
• 所有钩子都是WooCommerce和WordPress原生钩子，兼容性更好，避免冲突。

为什么之前的方法失败？ #

1. 用woocommerce_wp_text_input设置type="file"：WooCommerce产品数据的表单没有设置enctype="multipart/form-data"，导致文件无法被正确提交到后台，而且直接保存文件路径没有关联WordPress媒体库，权限和存储逻辑都不兼容；
2. 自定义AJAX上传：如果没有正确调用WordPress的媒体上传API，会绕过权限验证和媒体库的存储机制，导致文件无法被正确保存和关联到产品。

内容的提问来源于stack exchange，提问作者sambhu lambhu