NextJS 14.2.12使用TypeScript命名空间组件报错，求非全客户端渲染方案

问题根源 #

NextJS 14.2.12的React Server Components（RSC）打包器对TypeScript命名空间的解析存在bug：当通过AccordionItem.Header这类命名空间方式导入子组件时，会生成类似//components/accordion/AccordionItem.tsx#AccordionItem#Header的模块路径，无法在客户端manifest中找到对应资源，从而触发报错。

可行的规避方案 #

1. 改用独立导出（推荐） #

放弃TypeScript命名空间，将Header和Body作为顶层独立导出：

// AccordionItem.tsx
"use client"

// 主组件
export default function AccordionItem({ children }: { children: React.ReactNode }) {
  // 组件逻辑实现
}

// 独立导出子组件
export function AccordionItemHeader({ children }: { children: React.ReactNode }) {
  // Header逻辑实现
}

export function AccordionItemBody({ children }: { children: React.ReactNode }) {
  // Body逻辑实现
}

使用时直接导入独立组件：

// 服务器组件中使用
import AccordionItem, { AccordionItemHeader, AccordionItemBody } from '@/components/accordion/AccordionItem';

export default function ServerComponent() {
  return (
    <AccordionItem>
      <AccordionItemHeader>折叠面板标题</AccordionItemHeader>
      <AccordionItemBody>折叠面板内容</AccordionItemBody>
    </AccordionItem>
  );
}

这种方式完全避开命名空间的打包问题，父组件仍保持服务器渲染，仅子组件（本身已标记use client）在客户端渲染。

2. 将子组件挂载为父组件的静态属性 #

若希望保留AccordionItem.Header的调用习惯，可将子组件挂载到默认导出的主组件上作为静态属性，并补充TypeScript类型定义：

// AccordionItem.tsx
"use client"

function AccordionItem({ children }: { children: React.ReactNode }) {
  // 主组件逻辑实现
}

function Header({ children }: { children: React.ReactNode }) {
  // Header逻辑实现
}

function Body({ children }: { children: React.ReactNode }) {
  // Body逻辑实现
}

// 挂载子组件为静态属性
AccordionItem.Header = Header;
AccordionItem.Body = Body;

// 补充TypeScript类型
type AccordionItemWithSubcomponents = typeof AccordionItem & {
  Header: typeof Header;
  Body: typeof Body;
};

export default AccordionItem as AccordionItemWithSubcomponents;

使用方式与原有命名空间写法一致：

// 服务器组件中使用
import AccordionItem from '@/components/accordion/AccordionItem';

export default function ServerComponent() {
  return (
    <AccordionItem>
      <AccordionItem.Header>折叠面板标题</AccordionItem.Header>
      <AccordionItem.Body>折叠面板内容</AccordionItem.Body>
    </AccordionItem>
  );
}

该方案既保留了原有调用语法，又能被NextJS的RSC打包器正确解析。

3. 临时包装器方案（最小改动） #

若不想修改原有组件结构，可创建一个小型客户端包装器专门导出命名空间下的子组件：

// AccordionItemSubcomponents.tsx
"use client"
import AccordionItem from './AccordionItem';

export const AccordionItemHeader = AccordionItem.Header;
export const AccordionItemBody = AccordionItem.Body;

然后在服务器组件中导入该包装器的组件：

// 服务器组件中使用
import AccordionItem from '@/components/accordion/AccordionItem';
import { AccordionItemHeader, AccordionItemBody } from '@/components/accordion/AccordionItemSubcomponents';

export default function ServerComponent() {
  return (
    <AccordionItem>
      <AccordionItemHeader>折叠面板标题</AccordionItemHeader>
      <AccordionItemBody>折叠面板内容</AccordionItemBody>
    </AccordionItem>
  );
}

此方案仅将子组件的导出层标记为客户端，主组件和父页面仍保持服务器渲染。

总结 #

目前这是NextJS RSC打包器的已知bug，上述方案均为有效规避手段，无需将整个父组件改为客户端渲染。等官方修复后可恢复使用TypeScript命名空间的写法。

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