Next.js+无头WordPress中Swiper滑块无法渲染的问题排查

核心错误分析 #

1. 无头模式下PHP模板无效：你写的PHP代码是传统WordPress的前端渲染逻辑，但在无头CMS架构中，Next.js通过WP REST API获取数据，不会执行这段PHP输出的HTML，因此这段代码完全起不到作用。
2. 数据传递逻辑错误：你将block.innerBlocks传给Slider组件的slides属性，但ACF的重复字段（slides）属于区块的ACF属性，并非innerBlocks，导致组件拿到的是空数组。
3. ACF数据未暴露到REST API：默认情况下，ACF字段不会自动包含在WP REST API的区块响应中，Next.js根本拿不到滑块的实际内容数据。

分步解决方案 #

1. 在WordPress端暴露ACF字段到REST API #

在主题的functions.php中添加以下代码，确保ACF区块字段被包含到REST API响应里：

// 暴露指定ACF区块的字段到REST API
add_filter('acf/rest_api/block/get_fields', function($fields, $block) {
    if ($block['name'] === 'acf/swiperslider') {
        $fields['slides'] = get_field('slides', $block['id']);
    }
    return $fields;
}, 10, 2);

// 通用方案：让所有ACF区块的字段都暴露到REST API
add_filter('rest_prepare_block', function($response, $block) {
    if (str_starts_with($block['blockName'], 'acf/')) {
        $acf_fields = get_fields($block['id']);
        $response->data['attributes']['acf'] = $acf_fields;
    }
    return $response;
}, 10, 2);

2. 修改Next.js的BlockRenderer组件 #

修正数据传递逻辑，从区块的ACF属性中获取slides数据：

case "acf/swiperslider": {
    return (
        <Slider
            key={block.id}
            // 从ACF属性中读取滑块数组，兜底空数组避免报错
            slides={block.attributes.acf?.slides || []}
        />
    );
}

3. 重构Slider组件以正确渲染ACF字段 #

现在拿到的slides是ACF字段对象数组，需要解构每个slide的字段来渲染内容：

import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
// Swiper 8+版本需要导入基础样式及所需组件样式
import 'swiper/css';
import 'swiper/css/pagination';

export const Slider = ({ slides }) => {
    return (
        <Swiper
            // 可根据需求添加Swiper配置项
            spaceBetween={30}
            pagination={{ clickable: true }}
            autoplay={{ delay: 3000 }}
        >
            {slides.map((slide, index) => (
                <SwiperSlide key={index}>
                    <img src={slide.slide_image.url} alt={slide.slide_image.alt || "Slide Image"} />
                    <h2>{slide.slide_title}</h2>
                    <p>{slide.slide_text}</p>
                    {slide.slide_link && (
                        <a 
                            href={slide.slide_link.url} 
                            target={slide.slide_link.target || "_self"}
                            rel={slide.slide_link.target === "_blank" ? "noopener noreferrer" : ""}
                        >
                            {slide.slide_link_text}
                        </a>
                    )}
                </SwiperSlide>
            ))}
        </Swiper>
    );
};

注意：ACF图片字段默认返回包含url、alt等属性的对象，需通过slide.slide_image.url访问图片地址。

4. 验证数据传递 #

可在BlockRenderer中临时添加日志，确认数据是否正常获取：

case "acf/swiperslider": {
    console.log('滑块ACF数据:', block.attributes.acf);
    return (
        <Slider
            key={block.id}
            slides={block.attributes.acf?.slides || []}
        />
    );
}

若控制台能输出包含slide内容的数组，说明数据传递正常，滑块即可正常渲染。

额外注意事项 #

• 确保Swiper与swiper/react版本兼容，避免因版本差异导致初始化失败。
• 若需使用分页、导航等功能，需额外导入对应Swiper模块并配置。
• 可直接访问WordPress REST API地址（如https://你的WP域名/wp-json/wp/v2/posts/文章ID），确认区块的ACF数据是否已包含在响应中。

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