本文详解如何通过 woocommerce 钩子（hook）在商品列表页（如首页、分类页）中调用并展示产品图库的**全尺寸原图**，而非默认缩略图，并修正常见代码误用问题。
在 WooCommerce 中，默认情况下，get_gallery_image_ids() 获取的是产品图库中上传的图片 ID 列表，但实际渲染时需明确指定图像尺寸。原始代码中使用 'thumbnail' 尺寸参数，导致输出的是小尺寸缩略图；若需展示原始上传的高清大图，必须将尺寸参数改为 'full'。
以下是经过验证、可直接使用的完整解决方案：
add_action('woocommerce_shop_loop_item_title', 'wps_add_fullsize_product_thumbs', 5);
function wps_add_fullsize_product_thumbs() {
// 注意：此钩子在循环中执行，$product 对象需手动获取
global $post;
if (!$post || !is_object($post)) return;
$product = wc_get_product($post->ID);
if (!$product || !$product->is_type('simple') && !$product->is_type('variable')) return;
$attachment_ids = $product->get_gallery_image_ids();
if (empty($attachment_ids)) return;
echo '<div class="product-fullsize-thumbs" style="margin-top: 8px; display: flex; gap: 4px;">';
// 取前3张图库图片，输出为 full 尺寸（即原始上传尺寸）
foreach (array_slice($attachment_ids, 0, 3) as $attachment_id) {
$full_size = wp_get_attachment_image_src($attachment_id, 'full');
if ($full_size && is_array($full_size) && !empty($full_size[0])) {
echo '<img class="product-full-thumb"
src="' . esc_url($full_size[0]) . '"
style="max-width:90%" . esc_attr($full_size[1]) . '"
height="' . esc_attr($full_size[2]) . '"
alt="' . esc_attr(get_the_title($attachment_id)) . '"
loading="lazy">';
}
}
echo '</div>';
}✅ 关键修正说明：
- 将 'thumbnail' → 'full'，确保调用原始分辨率图像；
- 使用 wc_get_product($post->ID) 替代全局 $product（因 woocommerce_shop_loop_item_title 钩子中 $product 并未自动全局化，直接使用可能导致空对象错误）；
- 增加安全判断（如 $product 存在性、图库非空、wp_get_attachment_image_src 返回有效性）；
- 添加 esc_url() / esc_attr() 防止 XSS，符合 WordPress 安全编码规范；
- 补充 width/height 和 loading="lazy" 提升性能与可访问性。
⚠️ 注意事项：
- 此代码适用于商品列表页（archive 页面），如分类页、搜索页、首页等；若需在单个产品页（single-product.php）显示全尺寸图库，请改用 woocommerce_before_single_product_summary 等对应钩子；
- 大图直出可能影响页面加载性能，建议配合 WebP 格式、CDN 或响应式图片（srcset）优化；
- 如主题已自定义循环结构，需确认 woocommerce_shop_loop_item_title 钩子是否被移除或优先级冲突，必要时调整 hook 位置或使用 woocommerce_after_shop_loop_item_title。
通过以上修改，即可稳定、安全地在 WooCommerce 商品循环中展示图库图片的完整尺寸版本，兼顾功能正确性与最佳实践。
