Vite + React 中静态资源动态访问
Vite + React 中静态资源动态访问
本文基于Vite + React 实现静态图片的动态访问，说明在 Vite 项目中如何安全地按业务字段动态展示多张本地 PNG，并记录常见踩坑与最终写法。
一、业务诉求
图标文件按约定放在：
src/assets/下，命名为icon-{code}.png（例如icon-1.png、icon-2.png）。
数据侧通过code区分类型，需要在运行时根据 code 选中对应图片，但图片集合在构建时已确定，不会从 CDN 任意拼接未知路径。
二、为什么new URL+ 模板字符串往往行不通
常见尝试：
constfileName='icon-1';consticon=newURL(`@/assets/${fileName}.png`,import.meta.url);在 Vite 中，new URL(第一个参数, import.meta.url)要求第一个参数在编译期可被静态分析为确定资源路径，打包器才能把文件纳入依赖并生成正确的 hash URL。
一旦路径里出现运行时变量（如${fileName}），Vite 无法枚举具体文件，可能出现：
- 资源未被打进产物；
- 或
@别名未在该场景下解析，浏览器请求到错误路径。
因此：「构建期固定」不等于可以用任意字符串拼路径，仍需要让构建器在编译期枚举出所有候选文件。
三、推荐方案：import.meta.glob预加载 + 运行时查表
Vite 提供import.meta.glob，在模式字符串保持静态的前提下，构建阶段会扫描匹配到的所有模块；运行时只需根据fileName在返回的Record里查找即可。
核心实现如下：
const PaletteItem = ({ item }) => { const iconModules = import.meta.glob('@/assets/*.png', { eager: true, query: '?url', import: 'default', }) as Record<string, string>; const getIconUrl = (fileName: string) => { const key = Object.keys(iconModules).find((k) => k.endsWith(`${fileName}.png`)); return key ? iconModules[key] : ''; }; const iconUrl = getIconUrl(`icon-${item.code}`); return ( <div className={/* ... */}> <img src={iconUrl} alt='' /> </div> ); };要点说明：
| 点 | 说明 |
|---|---|
glob模式 | '@/assets/*.png'为字面量，构建期可枚举目录下全部 png |
query: '?url' | 将资源解析为 URL 字符串（适合<img src>） |
eager: true | 同步打包进当前 chunk，避免异步import()的额外分支（组件库图标数量可控时很合适） |
import: 'default' | 让每个匹配项的值直接为string URL，而不是{ default: string }的模块对象，避免<img src={模块对象} />触发 React 警告 |
四、踩坑记录：src收到Module类型
若仅使用eager: true+query: '?url'，未设置import: 'default'，运行时得到的往往是：
{"default":"/xxx/src/assets/.../icon-area.png?t=..."}若误把该对象传给<img src={...} />，会出现类似警告：
The provided
srcattribute is an unsupported type Module. This value must be coerced to a string…
处理方式二选一：
- 加上
import: 'default'，glob 结果为Record<string, string>（推荐）；或 - 类型声明为
Record<string, { default: string }>，取iconModules[key].default。
新增组件类型时，只需在components目录增加对应 png，无需改glob模式。
五、小结
- 动态路径若交给
new URL(\…${var}…`)`，容易脱离 Vite 静态分析，导致资源丢失或路径错误。 - 构建期固定、运行期选择应使用
import.meta.glob静态枚举 + 运行时按 key/endsWith查找。 - 使用
query: '?url'时注意返回值是字符串还是{ default }，用import: 'default'或显式取.default，保证<img src>始终是字符串。