Next.js自定义Heroicons动态导入组件打包后显示异常如何解决？

问题原因 #

• 核心原因是Next.js生产构建会执行Tree Shaking（摇树优化）：你通过import * as SolidIcons全量导入后用字符串动态索引图标的写法，构建工具无法识别你实际用到了哪些图标，会把所有未显式引用的图标都从打包产物中移除。开发环境默认关闭严格摇树，所以运行正常。你的页面使用了SSG预渲染，构建阶段图标就已经被清理，预渲染输出的HTML本身就没有正确的图标内容，所以生产环境、移动端都无法正常显示。
• 次要原因是Tailwind CSS的JIT编译机制：你动态拼接h-${size} w-${size}这类类名的写法，Tailwind生产构建时无法扫描到这些动态生成的类，会导致对应的尺寸、颜色样式不生效，进一步引发显示异常。

修复方案 #

1. 显式声明图标映射，避免动态索引 #

将你项目中用到的所有图标做显式映射，避免全量导入后动态取值，确保摇树时不会把用到的图标删掉。同时可以直接用映射的key做类型限定，还能去掉原来的@ts-ignore注解，类型更安全。

2. 避免动态拼接Tailwind类 #

要么用内联样式控制尺寸，要么将用到的Tailwind类提前写死，或者将动态生成的类加入Tailwind的安全列表（safelist）。

修改后的组件示例代码如下：

// HeroIcon.tsx
// 显式导入所有你项目中用到的实底图标
import { CogIcon, UserIcon, HomeIcon } from '@heroicons/react/solid';
// 显式导入所有你项目中用到的线框图标，重名的可以加后缀区分
import { CogIcon as CogIconOutline, UserIcon as UserIconOutline, HomeIcon as HomeIconOutline } from '@heroicons/react/outline';

// 建立实底图标映射表
const solidIconMap = {
  CogIcon,
  UserIcon,
  HomeIcon
  // 其他用到的实底图标依次补全
} as const;

// 建立线框图标映射表
const outlineIconMap = {
  CogIcon: CogIconOutline,
  UserIcon: UserIconOutline,
  HomeIcon: HomeIconOutline
  // 其他用到的线框图标依次补全
} as const;

// 限定icon参数的可选值
interface Props {
  icon: keyof typeof solidIconMap;
  color?: string;
  size?: number;
  outline?: boolean;
}

export const HeroIcon = (props: Props): JSX.Element => {
  const { icon, color = 'text-black', size = 6, outline = false } = props;
  const Icon = outline ? outlineIconMap[icon] : solidIconMap[icon];
  // 用内联样式控制尺寸，避免动态拼接Tailwind类
  return <Icon className={color} style={{ width: `${size * 0.25}rem`, height: `${size * 0.25}rem` }} />;
};

组件调用方式和原来完全兼容：

<HeroIcon icon='CogIcon' color='text-blue-600' size={6} outline />

如果你的项目用到的图标非常多，不想手动维护映射表，也可以直接使用社区已经封装好的支持动态传名的heroicons组件库。

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