WooCommerce订单完成后附加媒体文件至下载标签失败求助

我来帮你搞定这个问题！你遇到的核心问题是直接手动修改订单_files元数据的方式不符合WooCommerce的内部规范，导致账户页面的下载模块识别不到你添加的文件。另外还有个关键小错误：你用了add_filter来处理woocommerce_order_status_completed，但这个钩子其实是动作钩子（不需要返回值），用过滤器会导致逻辑无法正确执行。

原代码的问题分析 #

• 直接构造_files元数据：WooCommerce的可下载文件是绑定到订单商品项的，而不是订单本身的元数据，手动写入的格式不被系统识别
• 硬编码固定值：order_key、download_id这些值应该动态获取，而不是写死，否则会和实际订单信息不匹配
• 错误使用钩子类型：woocommerce_order_status_completed是动作，不是过滤器，用add_filter会导致函数执行异常

修复后的完整代码 #

下面是符合WooCommerce规范的实现，它会正确将文件添加到订单的可下载列表中，并且在用户账户的下载标签中显示：

add_action( 'woocommerce_order_status_completed', 'attach_custom_files_to_order_downloads' );
function attach_custom_files_to_order_downloads( $order_id ) {
    // 获取订单对象，判断是否有效
    $order = wc_get_order( $order_id );
    if ( ! $order ) return;

    // 配置你要添加的文件信息
    $file_url = 'http://localhost/wordpress/wp-content/uploads/abc.png';
    $file_name = '自定义下载文件';
    $target_product_id = 17; // 要关联的商品ID
    $downloads_remaining = 1; // 剩余下载次数
    $access_expires = null; // 永不过期，如需设置过期可改为 strtotime('+30 days')

    // 遍历订单中的商品，找到目标商品
    foreach ( $order->get_items() as $item_id => $order_item ) {
        if ( $order_item->get_product_id() === $target_product_id ) {
            // 创建WooCommerce标准的下载项对象
            $download_item = new WC_Order_Item_Download();
            $download_item->set_name( $file_name );
            $download_item->set_product_id( $target_product_id );
            $download_item->set_download_url( $file_url );
            // 自动生成或获取匹配的下载ID（避免硬编码）
            $download_item->set_download_id( wc_get_product_download_id( $target_product_id, $file_url ) );
            $download_item->set_order_id( $order_id );
            $download_item->set_order_item_id( $item_id );
            $download_item->set_access_expires( $access_expires );
            $download_item->set_downloads_remaining( $downloads_remaining );

            // 将下载项添加到订单商品并保存
            $order_item->add_download( $download_item );
            $order_item->save();
        }
    }

    // 刷新订单的下载权限，确保系统识别新添加的文件
    $order->update_download_permissions();
}

关键修复点说明 #

1. 改用动作钩子：把add_filter换成add_action，确保钩子触发时函数能正确执行
2. 使用官方API：通过WC_Order_Item_Download类创建下载项，符合WooCommerce的内部数据结构，避免手动写元数据的兼容性问题
3. 绑定到商品项：可下载文件是和订单中的具体商品绑定的，所以需要遍历订单商品找到目标商品再添加
4. 刷新权限缓存：调用update_download_permissions()方法，让WooCommerce立即更新订单的下载权限信息，确保新文件能显示在用户账户中

测试步骤 #

• 替换代码中的$file_url、$target_product_id等变量为你的实际信息
• 创建一个测试订单，将状态改为completed（或完成支付流程）
• 登录用户账户，查看「下载」标签，应该能看到你添加的自定义文件了

内容的提问来源于stack exchange，提问作者Rashmi Jain