NextJS结合Sanity.io动态加载组件时Hook调用异常排查

问题根源 #

你遇到的React Hook错误，本质是违反了Hook调用规则：Hook必须在组件的顶层作用域调用，不能嵌套在条件判断、循环或动态执行的函数逻辑中。之前的getDynamicComponent如果是在渲染阶段动态导入组件并直接执行（比如返回一个临时函数包裹组件），会导致组件内部的useContext/useMemo等Hook不在顶层执行，触发报错。

可行解决方案 #

1. 建立组件映射表（核心修复）

提前将所有Sanity内容类型与对应React组件做静态映射，确保组件是合法的React组件类型，而非动态执行的函数。

步骤1：创建组件映射文件

// components/componentMap.js
import Hero from './Hero';
import Quote from './Quote';
import PortableTextBlock from './PortableTextBlock'; // 封装PortableText的组件
import HeroImageBlock from './HeroImageBlock'; // 封装Next/Image的组件

// 键名对应Sanity文档的_type字段（注意大小写匹配）
export const componentMap = {
  hero: Hero,
  quote: Quote,
  portableText: PortableTextBlock,
  heroImage: HeroImageBlock,
};

如果组件数量较多，可使用React.lazy实现代码分割优化：

// 动态导入版本
import { lazy } from 'react';

export const componentMap = {
  hero: lazy(() => import('./Hero')),
  quote: lazy(() => import('./Quote')),
  portableText: lazy(() => import('./PortableTextBlock')),
  heroImage: lazy(() => import('./HeroImageBlock')),
};

步骤2：修改动态组件加载逻辑

// 页面或父组件中
import { componentMap } from '../components/componentMap';
import { Suspense } from 'react';

// 简化的动态组件获取函数
const getDynamicComponent = (type) => {
  // 兜底处理未知类型
  return componentMap[type] || (() => <div>Unsupported block type: {type}</div>);
};

export default function ContentPage({ contentBlocks }) {
  return (
    <div className="page-container">
      {/* 如果用React.lazy，必须用Suspense包裹处理加载状态 */}
      <Suspense fallback={<div>Loading content...</div>}>
        {contentBlocks.map((block) => {
          const Component = getDynamicComponent(block._type);
          // 直接渲染组件，确保组件内部Hook在顶层执行
          return <Component key={block._id} data={block} />;
        })}
      </Suspense>
    </div>
  );
}

2. 组件内部Hook合规检查

确保每个动态组件内部的Hook都在顶层调用，比如：

// HeroImageBlock.js（正确示例）
import Image from 'next/image';
import { useSanityImage } from '@sanity/image-url/lib/types/react';

export default function HeroImageBlock({ data }) {
  // Hook在组件顶层调用，符合规则
  const imageUrl = useSanityImage(data.image);

  return (
    <div className="hero-image">
      <Image
        src={imageUrl}
        alt={data.alt}
        fill
        className="object-cover"
      />
    </div>
  );
}

方案合理性确认 #

1. 扩展性：内容管理器新增内容类型时，只需在componentMap中添加对应组件映射即可，完全支持自由调整内容块的数量和顺序。
2. 性能：静态导入适合组件数量少的场景，编译时打包所有组件，无加载延迟；React.lazy动态导入适合大量组件的场景，实现代码分割，减少初始包体积。
3. 稳定性：严格遵循React Hook规则，彻底避免Hook调用错误，同时通过兜底组件处理未知类型，防止页面崩溃。

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