Next 14通过index.ts导入Shadcn Badge组件报HTMLElement未定义错误

我在开发Next 14应用，UI层使用Shadcn组件（其中Badge组件未做任何修改，单独导入使用完全正常）。为了规整项目导入结构，在组件文件夹下创建了index.ts统一导出组件：

export { default as ErrorMessage } from "./ErrorMessage";
export { default as IssueStatusBadge } from "./IssueStatusBadge";
export { default as LabelWithErrorMessage } from "./LabelWithErrorMessage";
export { default as Loader } from "./Loader";
export { default as Skeleton } from "./Skeleton";

通过该index.ts导入Loader、LabelWithErrorMessage等组件时均正常，比如：

import { Loader, LabelWithErrorMessage } from "@/app/components";

但导入IssueStatusBadge组件时出现异常，该组件代码如下：

import { Badge } from "@/components/ui/badge";
import { Status } from "@prisma/client";

const statusMap: Record<Status, { label: string; bgClass: string }> = {
  OPEN: { label: "Open", bgClass: "bg-red-600" },
  IN_PROGRESS: { label: "In Progress", bgClass: "bg-indigo-600" },
  CLOSED: { label: "Closed", bgClass: "bg-emerald-600" },
};

const IssueStatusBadge = ({ status }: { status: Status }) => {
  return (
    <Badge className={statusMap[status].bgClass}>
      {statusMap[status].label}
    </Badge>
  );
};

export default IssueStatusBadge;

两种导入方式结果完全不同：

import IssueStatusBadge from "@/app/components/IssueStatusBadge"; // 正常工作
import { IssueStatusBadge } from "@/app/components"; // 抛出错误：Error: HTMLElement is not defined

原因分析 #

这是Next.js 14的服务器组件默认行为导致的：

• Next.js 14中所有组件默认是服务器组件，当你通过index.ts统一导出时，Next.js会将整个index.ts视为服务器组件模块，提前解析所有导出组件的依赖。
• Shadcn的Badge组件（或其底层依赖如Radix UI）包含仅在浏览器环境中存在的HTMLElement引用，这些代码在服务器端渲染时被执行，就会触发"HTMLElement is not defined"错误。
• 单独导入IssueStatusBadge时，Next.js会自动识别其依赖的客户端组件（比如Badge组件带有'use client'指令），正确分配渲染环境；但通过index.ts批量导出时，index.ts本身没有'use client'标记，服务器端会强制加载所有导出组件的依赖，导致浏览器专属代码在服务器端运行。

解决方案 #

最直接的修复方式是在IssueStatusBadge组件顶部添加'use client'指令，明确标记为客户端组件：

'use client'; // 新增该行
import { Badge } from "@/components/ui/badge";
import { Status } from "@prisma/client";

// 其余代码保持不变

这样即使通过index.ts导入，Next.js也会识别该组件需要在客户端执行，避免服务器端运行浏览器专属代码。

内容的提问来源于stack exchange，提问作者Muhtasim Fuad Showmik