QwikJS中使用React图标组件时Vite构建报错：Cannot read properties of undefined

我在React组件里定义了选项列表，通过映射生成UI，这个组件用qwikify$适配后在基于Vite的QwikJS项目中使用。但给选项列表添加图标值后，Vite构建时报错：

[vite] Internal server error: Cannot read properties of undefined (reading 'IconHome')

这段代码在Next.js里能正常运行，但在QwikJS里不行。我的代码如下：

import { IconHome, IconMail, IconPencilPlus } from '@tabler/icons'

interface OptionProps {
    id: number
    text: string
    icon: React.ReactElement
    url?: string
    action?: () => void
}

export const Command = qwikify$(() => {
    ...
    const options: OptionProps[] = [
        {
            id: 1,
            text: 'Home',
            icon: <IconHome className='h-5 w-5' stroke={1} />,
            url: '/',
            action: undefined,
        },
        {
            id: 2,
            text: 'Join the waitlist',
            icon: <IconPencilPlus className='h-5 w-5' stroke={1} />,
            url: undefined,
            action: () => {
                setShowWaitlist(true)
            },
        },
     ]
     ...
})

我希望映射选项列表时渲染图标，示例代码：

{options.map((option, i) => (
    <div>
        <div>{option.icon}</div>
        <div>{option.text}</div>
    </div>
))}

原因与解决方法 #

1. 核心问题：Qwik与React的运行时差异 #

qwikify$虽能兼容React组件，但不能在React组件的渲染上下文之外提前创建React元素。你在qwikify$包裹的组件内部直接实例化<IconHome />这类React元素并存在数组中，Qwik的构建流程会提前执行这段代码，此时React运行时还未就绪，导致图标组件未被正确初始化，出现undefined报错。

2. 正确实现步骤 #

步骤1：修改类型定义

把icon的类型从React.ReactElement改为React.ElementType（表示组件本身，而非实例化后的元素）：

interface OptionProps {
    id: number
    text: string
    icon: React.ElementType // 调整类型
    url?: string
    action?: () => void
}

步骤2：更新选项列表

存储图标组件的引用，而非实例化后的元素：

const options: OptionProps[] = [
    {
        id: 1,
        text: 'Home',
        icon: IconHome, // 直接传组件本身
        url: '/',
        action: undefined,
    },
    {
        id: 2,
        text: 'Join the waitlist',
        icon: IconPencilPlus, // 同理
        url: undefined,
        action: () => {
            setShowWaitlist(true)
        },
    },
]

步骤3：渲染时实例化图标

在映射渲染时，再传入props实例化图标组件：

{options.map((option, i) => (
    <div key={option.id}>
        <div>
            {/* 这里才实例化图标并传入props */}
            <option.icon className='h-5 w-5' stroke={1} />
        </div>
        <div>{option.text}</div>
    </div>
))}

3. 额外注意事项 #

• 所有React元素的创建必须在qwikify$包裹的React组件渲染函数内部完成，避免提前执行导致的运行时问题。
• 如果需要动态传递props给图标，直接在渲染阶段传入即可，不要在选项数组中提前绑定。

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