WooCommerce商品页面添加CSV下载按钮故障排查求助

问题描述 #

在WooCommerce单商品页面添加CSV下载按钮后，点击仅打开空白标签页，无CSV文件生成下载，原有代码如下：

// Add Download CSV button on product page
add_action( 'woocommerce_single_product_summary', 'add_download_csv_button', 25 );
function add_download_csv_button() {
    global $product;
    echo '<a href="' . get_home_url() . '/export-csv/?product_id=' . $product->get_id() . '" class="button">Download CSV</a>';
}

// Generate CSV file on button click
add_action( 'template_redirect', 'generate_csv_file' );
function generate_csv_file() {
    if ( isset( $_GET['product_id'] ) && $_GET['product_id'] != '' ) {
        $product_id = intval( $_GET['product_id'] );
        $product = wc_get_product( $product_id );

        // Set CSV headers
        header( 'Content-Type: text/csv; charset=utf-8' );
        header( 'Content-Disposition: attachment; filename=product-' . $product_id . '.csv' );

        // Create CSV file
        $output = fopen( 'php://output', 'w' );
        fputcsv( $output, array( 'Product Name', 'Product SKU', 'Product Description', 'Product Price' ) );
        fputcsv( $output, array( $product->get_name(), $product->get_sku(), $product->get_description(), $product->get_price() ) );
        fclose( $output );
        exit;
    }
}

故障原因 #

• HTML实体编码错误：按钮代码里的<a、"是HTML实体，浏览器解析后会破坏链接结构，导致请求地址无效。
• 输出缓冲区干扰：template_redirect钩子执行时，可能已有页面内容提前输出到缓冲区，导致CSV响应头部无法正确发送，浏览器识别不到下载指令。
• 无商品有效性校验：没有判断wc_get_product()是否成功获取商品对象，若传入无效ID会直接报错中断流程。

修复步骤 #

1. 修正按钮链接的HTML编码问题，直接输出原生HTML标签并做安全转义。
2. 在发送CSV头部前清空输出缓冲区，确保头部能正常生效。
3. 添加商品对象有效性校验，避免无效ID导致的错误。
4. 优化CSV头部设置，增强浏览器对下载响应的识别。

修复后的完整代码 #

// Add Download CSV button on product page
add_action( 'woocommerce_single_product_summary', 'add_download_csv_button', 25 );
function add_download_csv_button() {
    global $product;
    // 直接输出原生HTML，用esc_url做安全转义，避免编码错误
    echo '<a href="' . esc_url( get_home_url() . '/export-csv/?product_id=' . $product->get_id() ) . '" class="button">Download CSV</a>';
}

// Generate CSV file on button click
add_action( 'template_redirect', 'generate_csv_file' );
function generate_csv_file() {
    if ( isset( $_GET['product_id'] ) && !empty( $_GET['product_id'] ) ) {
        $product_id = intval( $_GET['product_id'] );
        $product = wc_get_product( $product_id );

        // 校验商品是否存在，避免无效ID报错
        if ( !$product ) {
            wp_die( '无效的商品ID' );
        }

        // 清空输出缓冲区，确保头部不被之前的内容干扰
        ob_clean();
        flush();

        // 设置规范的CSV响应头部
        header( 'Content-Type: text/csv; charset=utf-8' );
        header( 'Content-Disposition: attachment; filename="product-' . $product_id . '.csv"' );
        header( 'Cache-Control: no-cache, no-store, must-revalidate' );
        header( 'Pragma: no-cache' );
        header( 'Expires: 0' );

        // 生成CSV内容
        $output = fopen( 'php://output', 'w' );
        // 写入表头
        fputcsv( $output, array( '商品名称', '商品SKU', '商品描述', '商品价格' ) );
        // 写入商品数据，移除描述中的HTML标签避免格式混乱，用WooCommerce方法格式化价格
        fputcsv( $output, array( 
            $product->get_name(), 
            $product->get_sku(), 
            wp_strip_all_tags( $product->get_description() ),
            wc_price( $product->get_price() )
        ) );
        fclose( $output );
        exit;
    }
}

关键修复说明 #

• 用esc_url()处理链接地址，同时直接输出<a>标签，彻底解决实体编码导致的链接失效问题。
• ob_clean()和flush()清空缓冲区，确保CSV头部能被浏览器正确接收。
• 增加商品对象校验，避免无效ID触发的致命错误。
• 对商品描述做HTML标签清理，防止CSV格式被破坏；用wc_price()格式化价格，符合WooCommerce的显示规范。
• 补充缓存控制头部，避免浏览器缓存旧的下载内容。

内容的提问来源于stack exchange，提问作者Paul M