Next.js AppRouter中react-notion-x自定义图片组件渲染异常求助

核心问题分析 #

切换到App Router并添加"use client"后，自定义Cloudinary图片组件未生效，原因包括：客户端组件标识位置错误、react-notion-x预览图片配置未正确启用、App Router下图片组件的配置差异、props传递逻辑问题。

具体解决步骤 #

1. 标记组件为客户端组件
   在文件最顶部（所有import之前）添加"use client";，因为NotionRenderer和自定义图片组件都需要在客户端执行：

   "use client";
   
   // core styles shared by all of react-notion-x (required)
   import 'react-notion-x/src/styles.css'
   // ... 其余import代码
   

2. 启用react-notion-x预览图片功能
   自定义图片组件仅在previewImages为true时生效，需确保：

   • 调用NotionPage时传入previewImagesEnabled={true}（比如：<NotionPage previewImagesEnabled={true} recordMap={...} />）
   • 确保recordMap包含preview_images字段，若数据获取逻辑未生成该字段，可手动处理Notion图片URL，或使用react-notion-x工具函数生成预览图映射。

3. 全局配置Cloudinary与图片域名
   在next.config.js中配置Cloudinary环境变量和Notion图片的远程访问规则，避免组件内配置的兼容性问题：

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     images: {
       remotePatterns: [
         {
           protocol: 'https',
           hostname: 's3-us-west-2.amazonaws.com',
           pathname: '/secure.notion-static.com/**',
         },
         // 如有其他Notion图片域名，需同步添加
       ],
     },
     env: {
       CLOUDINARY_CLOUD_NAME: 'iant1359',
     },
   }
   
   module.exports = nextConfig
   

   然后修改ImageComponent，移除组件内的config prop：

   const ImageComponent: React.FC<ImageComponentProps> = ({ src, width, height, alt, ...props }) => (
     <CldImage
       {...props}
       src={src}
       width={width || 2048}
       height={height || 1600}
       alt={alt || "illustration image for doc"}
       deliveryType="fetch"
       dpr="auto"
     />
   );
   

4. 适配App Router动态组件导入
   对Collection组件的动态导入添加ssr: false，确保仅在客户端渲染：

   const Collection = dynamic(() =>
     import('react-notion-x/build/third-party/collection').then(m => m.Collection),
     { ssr: false }
   )
   

5. 替换next/head为App Router兼容方案
   App Router推荐使用原生<head>标签或generateMetadata函数替代next/head，示例修改：

   // 移除import Head from 'next/head'
   // ...
   return (
     <>
       <head>
         {socialDescription && (
           <>
             <meta name="description" content={socialDescription} />
             <meta property="og:description" content={socialDescription} />
             <meta name="twitter:description" content={socialDescription} />
           </>
         )}
         {/* 其余meta标签保持不变 */}
       </head>
       <NotionRenderer {/* 配置参数 */} />
     </>
   )
   

验证要点 #

• 检查浏览器控制台是否有Cloudinary相关错误日志
• 查看图片元素的src是否已替换为Cloudinary的URL
• 确认NotionRenderer的previewImages属性已设为true

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