企业官网建设流程全解析

1. 页面上一排“裂图”：本地图片加载失败的真实场景

如果你打开某个Vue3管理后台页面，发现一排小图标全是裂的，头像区域一片空白，控制台一堆404——先别急着怀疑Element Plus的Image组件有问题。这个锅，大概率要记在“本地图片引用方式”头上。

Element Plus的el-image本身很单纯，它就是一个被增强过的img标签，你给它一个能访问的URL，它就能正常显示。问题是很多朋友给的是一个“只有源码环境里才存在”的路径。比如在开发环境里直接写src="/src/assets/logo.png"，浏览器能打开；但当你执行npm run build之后，打开打包产物，整张图片就裂了。还有另一种情况是写相对路径src="../../assets/logo.png"，看起来挺对，实际上组件在渲染时这个相对路径是从当前页面URL去解析的，页面一换路由，图片就跟着失效。

下面是我这几年见过最多的三类典型现象，你可以对照一下自己遇到的是哪种：

• 开发环境里图正常，打包后全裂。这是最隐蔽的一种。路径在dev server下能访问，但build后的dist目录里根本没有这个路径对应的文件，于是页面上出现一堆断裂的图标占位符。
• 开发环境就404。直接写了src="/src/assets/xxx.png"或src="assets/xxx.png"，浏览器从根路径去拿文件，而dev server没有把这个源码目录映射成静态资源路由，自然404。
• v-for循环里动态拼接图片路径。比如<el-image :src="'/src/assets/' + item.name + '.png'" />，这种写法令构建工具完全无法识别，打包时这些图片不会被处理，最终全部丢失。

如果你中了其中任意一条，这篇文章就是给你写的。下文不绕弯子，先把“为什么不行”的根因讲透，再给出四种完全可落地的正确加载方案，最后把el-image的懒加载、预览、循环渲染等场景整合起来说，包含完整的代码示例和排查顺序。

2. 根因拆解：构建工具不会主动“搬运”你没打招呼的文件

理解这个问题，关键要搞清楚一个事：在你的项目里，图片文件不是“放在那儿就能被访问的”，它必须经过构建工具的显式处理，才会出现在最终的线上静态资源里。

2.1 开发环境与生产环境的本质差异

Vite在开发环境下启动的dev server，会把项目根目录作为静态资源服务器，所以你访问/src/assets/logo.png这类的URL，理论上能拿到文件——这是dev server为了方便调试提供的便利，并不是说这个路径在线上一定有效。到了build阶段，事情完全不同：Vite会以入口文件（通常是main.ts）为起点，顺着代码里的import语句、url()函数、new URL表达式去收集资源依赖。只有出现在这些“依赖清单”里的文件，才会被拷贝到dist目录，并且文件名会带上内容hash，比如logo.abc123.png。

换句话说，构建工具像是一个严格的搬家公司，只搬你写在清单上的行李。你指着客厅说“把这些都搬了”，它不会动；只有你明确说“把这个箱子、这个袋子和这个收纳盒搬走”，它才会逐一登记、贴上标签、装车发走。

所以，当你直接在template里写死一个字符串路径，比如<el-image src="/src/assets/logo.png" />，构建工具并不知道这个字符串和src/assets/logo.png这个文件之间有任何关联。它不会去解析HTML模板里的src属性，更不会帮你把图片从源码目录拷贝到输出目录。结果就是：dev模式可能碰巧能显示，build之后必然裂图。

2.2 为什么“相对路径”也不靠谱

有朋友说：“那我写成相对路径总行了吧？比如src="../../assets/logo.png"。”这个思路只对了一半，而且很容易踩更大的坑。

<el-image>组件最终渲染到页面上时，浏览器解析它src属性的基准是“当前页面的URL”。单页应用里，你路由可能是http://localhost:5173/dashboard，也可能是http://localhost:5173/order/2024。这些都还好，页面路径层级基本不深。但如果部署后前端代码放在一个子目录下，比如http://example.com/admin/，那相对路径../../assets/xxx.png就会向上跳两层，直接跳出/admin/范围，404没商量。

组件库不会替你做路径归一化，它就是把src原样丢给img标签。所以别再依赖相对路径写本地图了，路由一嵌套就会出问题。

2.3 真正需要理解的一句话

本地图片要正常显示，最终传给el-image的src必须是一个“构建工具认可并处理过”的最终URL。处理过的结果通常有两种形态：

• 小图片（默认小于4KB）被转成base64字符串，直接内联在JS里，src的值是一长串data:image/png;base64,...。
• 大图片被生成独立的hash文件，输出到dist的assets目录下，src的值是打包后的相对路径或绝对路径。

这两种形态，都不是你手写字符串能伪造的，必须借助代码让构建工具帮你算出来。这也是下面所有方案的核心思路。

3. 本地图片的正确加载姿势：四种方案与选型判断

搞懂了原理，接下来就是实操环节。我按使用场景给你拆成四种方案，每一种都给你标注清楚什么时候用、有什么坑、代码怎么写。

3.1 import导入：最正统、控制力最强的方案

这是我最推荐的一种方式，也是官方文档演示的主流用法。把图片当作模块导入，构建工具会完成后续所有处理。

在<script setup>里这样写：

<script setup> import logo from '@/assets/logo.png' import avatar from '@/assets/images/avatar.svg' </script> <template> <el-image :src="logo" fit="cover" /> <el-image :src="avatar" fit="cover" /> </template>

导入进来的logo，在dev模式下就是/src/assets/logo.png这样的开发地址；在build后则变成/assets/logo.abc123.png或一段base64字符串。整个过程是构建工具自动完成的，你只需要保证文件路径正确即可。

为什么说它“控制力最强”？因为一旦图片变成了JS模块，你就可以在业务代码里对它做更多操作，比如：

import avatars from '@/assets/avatars.png' // 读尺寸 const img = new Image() img.onload = () => { console.log(img.width, img.height) } img.src = avatars // 判断类型或体积，做一些条件渲染 if (avatars.startsWith('data:image')) { // 它被内联了 }

我做了几个项目的经验是：凡是业务路径稳定、且需要跟随组件一起打包的图片，全部用import。比如页面顶部的插图、状态空视图、固定图标等。缺点也不是没有：import的路径必须是静态字符串，你不能指望import logo from '@/assets/' + name + '.png'这种写法能通过编译。

3.2 public目录：不参与构建的“原样搬用”

如果你的图片不希望在构建时被hash改名、不希望被压缩，也不需要按需加载，那么把它放进public目录是最省事的。

把文件放到项目根目录的public/images/logo.png，然后直接写：

<template> <el-image src="/images/logo.png" /> </template>

public目录的特殊之处在于：它里面的所有文件，会被原封不动地复制到dist的根目录。也就是说，dist目录里会出现images/logo.png，跟你的HTML入口平级。由于路径不经过hash处理，你可以在任何地方用绝对路径引用它。

注意事项也明显：

• 必须用绝对路径，且以/开头。写成images/logo.png在ElImage里会以当前路由为基准解析，容易出问题。
• public里的文件不会被压缩和hash，所以不利于缓存优化。大型图片放里面，每次发版都要强制刷新才能看到新图。
• 如果项目部署在子路径下，比如http://example.com/admin/，那么/images/logo.png的根路径就会变成http://example.com/images/logo.png，而不是http://example.com/admin/images/logo.png，直接404。这种情况下需要在vite.config.ts里设置base: '/admin/'，并配合import.meta.env.BASE_URL拼路径。

<script setup> const logoUrl = `${import.meta.env.BASE_URL}images/logo.png` </script> <template> <el-image :src="logoUrl" /> </template>

public目录适合放：favicon、manifest图标、登录页大背景图、以及那些“每次发版基本不变”的资源。

3.3 new URL()动态构造：适合模板里写“死”但带变量的情况

有些场景让你很尴尬：图片路径前半段是固定的，后半段要根据条件变化。比如src/assets/status/loading.png、src/assets/status/success.png，你想通过变量切换状态图。import做不到动态拼接，public目录又不想用，那就可以用Vite提供的new URL语法。

在Vite项目里，new URL('./relative/path', import.meta.url)会被构建工具识别并解析为一个模块：

<script setup> import { computed } from 'vue' const statusMap = { loading: 'loading.png', success: 'success.png', error: 'error.png' } const currentStatus = ref('loading') const statusUrl = computed(() => { return new URL(`../assets/status/${statusMap[currentStatus.value]}`, import.meta.url).href }) </script> <template> <el-image :src="statusUrl" /> </template>

这里有个特别重要的点，也是很多人踩坑的地方：new URL()的第一个参数必须是相对路径，必须相对第二个参数import.meta.url去解析。你不能直接写new URL('@/assets/status/loading.png', import.meta.url)，因为@别名在new URL里不会被解析，必须写成相对路径。相对路径的基准是当前文件所在目录，所以上面例子中../assets/status/...表示从当前文件上一级开始找，你自己要根据实际目录结构调整层级。

这种方案的优点是：路径模式清晰，动态文件名也能支持。缺点是：构建工具只会打包“你能拼出来的那部分路径上存在的文件”，如果文件名写错了，它不会报错，最终运行时才404。排查成本比import要高一些。

3.4 import.meta.glob：批量注册本地资源的终极解法

如果图片多到像图标库一样，比如几十个上百个图标要在侧边栏菜单里循环渲染，单个import会显得很蠢。这就要用到import.meta.glob了。

import.meta.glob是Vite提供的一个批量导入“通配符”的API。它接受一个路径模式，返回一个对象，对象的key是匹配到的文件路径，value是对应模块。

分两种用法：懒加载和预加载。

// 懒加载方式：只有访问到某个key时才加载对应图片 const modules = import.meta.glob('../assets/icon/*.png') // 返回： {'../assets/icon/home.png': () => import('../assets/icon/home.png')} // 预加载方式：直接把所有图片一次性处理成URL const modules = import.meta.glob('../assets/icon/*.png', { eager: true }) // 返回： {'../assets/icon/home.png': { default: '/assets/home.abc123.png' }}

预加载方式在菜单渲染场景里最实用。比如你的侧边栏菜单数据结构是这样：

const menus = [ { title: '首页', icon: 'home' }, { title: '订单', icon: 'order' }, { title: '用户', icon: 'user' } ]

可以这样把图标批量变成可访问的URL：

<script setup> import { computed } from 'vue' // eager: true 表示立即处理所有图片，不需要异步等待 const iconModules = import.meta.glob('../assets/icon/*.png', { eager: true }) // 把路径映射转成文件名映射 const iconMap = Object.fromEntries( Object.entries(iconModules).map(([path, module]) => { const fileName = path.split('/').pop().replace('.png', '') return [fileName, module.default] }) ) const menus = [ { title: '首页', icon: 'home' }, { title: '订单', icon: 'order' }, { title: '用户', icon: 'user' } ] </script> <template> <div v-for="item in menus" :key="item.title"> <el-image :src="iconMap[item.icon]" fit="cover" /> <span>{{ item.title }}</span> </div> </template>

这样做的好处是：新增图标时只需要丢进assets/icon/目录，菜单配置里写上对应文件名即可，不用再手动import。注意glob模式里的路径同样是相对当前文件的路径，也要小心处理好目录层级。

3.5 四种方案的选型对比

把四种方案放一起看，选哪个就直观多了：

我个人的选型习惯是：单张定制图片用import，部署根路径稳定时用public放公共logo，状态图用new URL，批量图标用glob。这个习惯在多个项目里验证下来，维护成本是最低的。

4. 不只是src：ElImage的懒加载、预览和插槽里的路径陷阱

解决了src本身的问题，你以为就完事了？我在实际使用中还遇到过三个跟本地图片“纠缠不清”的细节坑。它们看似不起眼，一旦触发就是整块区域异常。

4.1 preview-src-list：预览大图也要用处理后的URL

ElImage的preview-src-list属性用来控制点击图片后出现的大图预览列表。很多人会想当然地直接写：

<template> <el-image :src="logo" :preview-src-list="['/src/assets/logo-big.png']" /> </template>

这个写法，等它真正点击预览的时候才会发现完全失效。因为预览列表里的每一项，本质上跟src一样，必须是构建工具处理过的URL字符串，不能是源码路径台账。

正确做法是，把预览大图也通过import引入，再塞进数组：

<script setup> import logo from '@/assets/logo.png' import logoBig from '@/assets/logo-big.png' const previewList = [logoBig] </script> <template> <el-image :src="logo" :preview-src-list="previewList" /> </template>

如果你有多个预览图，就用数组组合起来，但里面每一项都必须是处理过的URL。

4.2 高度塌陷：fit="cover"不生效，图不见了

本地图片加载成功，但页面上看起来像“没图”——这种情况通常跟加载机制无关，而是布局高度问题。

el-image渲染出的根元素默认是inline-block，高度在没有明确设置的时候取决于图片内容高度，这看起来没什么问题。但一旦你给外层容器设置了固定高度，或者使用了fit="cover"等需要裁剪的模式，el-image自身如果没拿到有效高度，图片区域就会塌陷成0。

举个常见例子：

<template> <div class="avatar-wrapper"> <el-image :src="avatar" fit="cover" /> </div> </template> <style scoped> .avatar-wrapper { width: 80px; height: 80px; } .avatar-wrapper :deep(.el-image) { width: 100%; height: 100%; } </style>

这里我特意用了:deep(.el-image)给组件根节点设置宽高。因为el-image的根节点并不总是自动继承父容器尺寸，你得显式告诉它，width: 100%; height: 100%。很多朋友只设置了容器的高度，忘了给el-image本身设高度，结果图片要么不显示、要么只显示一小条。本地图加载没问题，但视觉效果就是“图没了”。

有一种快速调试方法：临时给el-image加一个内联高度样式，比如style="height: 120px"，如果图片正常显示，那就说明问题出在高度继承链上，而不是图片路径。

4.3 循环渲染里最常见的动态拼接错误

先给一段典型的错误代码：

<template> <el-image v-for="item in imageList" :key="item.id" :src="`/src/assets/${item.fileName}`" /> </template>

这段代码在dev模式环境下，图片看起来正常，但只要一打包，全部裂掉。原因在前面已经讲过：字符串拼接的路径，构建工具完全不认识，build时不会把这些图片纳入资源依赖。它们没有被拷贝到dist，自然全部404。

循环渲染的正确做法，是先把所有可能的图片，用import.meta.glob批量变成URL映射，然后在循环里按key取值：

<script setup> const modules = import.meta.glob('@/assets/gallery/*.jpg', { eager: true }) const imageList = [ { id: 1, fileName: 'photo1.jpg' }, { id: 2, fileName: 'photo2.jpg' } ] const urlMap = Object.fromEntries( Object.entries(modules).map(([path, mod]) => { const fileName = path.split('/').pop() return [fileName, mod.default] }) ) const imageListWithUrl = imageList.map(item => ({ ...item, url: urlMap[item.fileName] })) </script> <template> <el-image v-for="item in imageListWithUrl" :key="item.id" :src="item.url" fit="cover" /> </template>

这样循环里的每一张图，都是构建工具处理过的合法URL，打包后稳定不变。注意glob匹配模式需要准确对应你文件的实际存放位置，如果用了@别名，它也会被Vite解析，这一点比new URL要友好一些。

4.4 部署在子路径下的base配置

最后一个坑，来自部署环境。

如果你的项目最终不是部署在域名根路径，而是http://example.com/admin/这样的子路径下，那图片资源的标准处理方式是要在vite.config.ts里配置base：

import { defineConfig } from 'vite' export default defineConfig({ base: '/admin/' })

配置之后，所有通过import和glob处理的资源，构建时都会自动加上/admin/前缀，线上访问就不会因为路径前缀不一致而404。

但这个配置对public目录不生效——public目录里的东西在构建时不会被注入base前缀，所以你在template里写/images/logo.png时，如果项目部署在子路径，实际访问的是根路径下的/images/logo.png，依然是404。这种情况下就需要用前面提到的方法：

const logoUrl = `${import.meta.env.BASE_URL}images/logo.png`

import.meta.env.BASE_URL读取的就是vite.config.ts里的base值。这样拼出来的路径，无论项目部署在根路径还是子路径，都能正确访问到public目录下的图片。

5. 一张排查清单：本地图片不显示的检查顺序和对照表

很多朋友一看到图片404，第一反应是“路径不对”，然后来回改各种拼接方式，改到最后更乱。下面是一套我平时排查图片问题时固定走的顺序，你可以直接当清单用。

5.1 六个步骤按顺序执行

1. 先看Network面板。找到裂图对应的请求，查看URL是什么样的。如果URL看起来像/src/assets/xxx.png或者assets/xxx.png这种源码路径，先别改路径，直接跳到第4步。
2. 确认是dev还是build后的问题。如果dev正常build后裂，说明构建工具没有处理这个资源引用。基本可以100%确定是“资源没被纳入构建依赖”。回到源码，检查是不是用了字符串拼接src。
3. 检查页面实际部署的base路径。如果项目部署在子路径，看看vite.config.ts里的base是否配好。没配好的话，dev正常，build完放到子路径下访问必然裂。
4. 查看dist目录结构。在项目根目录执行ls dist/assets或直接打开dist文件夹，看你要的图片名字是否在里面。不在，说明资源根本没被构建；在里面，说明URL路径拼接有误。
5. 确认el-image的容器高度。如果Network里图片请求返回200，但页面上还是空的，请检查el-image父容器和自身的高度设置。临时给el-image设置一个固定高度，比如style="height: 100px; width: 100px;"，如果图出来了，那就是高度问题。
6. 检查代码有没有用@别名但在new URL里使用了它。这种情况构建时不会报错，但运行时URL是错的。new URL只接受相对路径或完整URL，不接受alias。

5.2 常见现象与可能原因对照

这个排查表我总结了多次之后固定下来，每次有同事遇到图片问题，我基本都是按这几条去定位，思路清晰、效率高。

6. 我现在写本地图片的一个固定习惯

最后分享一个我自己的实操习惯，给刚接触这套技术栈的朋友做个参考。

我现在写代码时，凡是ElImage要用本地图片，都遵循这么个流程：先想这个图片的用途，然后决定用哪种加载方案。固定单图直接import；需要跟着菜单数据走的批量图标用glob；public目录只放真正全局的、几乎不变的文件，而且用了就立刻检查base路径。代码里我还会在图片组件外层加一个注释，标注图片的来源方式和存放目录，方便几个月后自己回来看代码时能快速想起来当初为什么这么写。

其实这整件事并不复杂，核心就是一句话：把本地图片当成一个“模块”而不是一个“文件路径”去对待。想通了这一点，无论是ElImage还是其他组件库里的图片组件，都不会再让你栽跟头。如果以后遇到类似“本地音频为什么不能播放”“本地字体为什么加载不出来”的问题，你会发现排查思路完全一致——通通是构建资源引用的问题。

如果你现在项目里正好有一张本地图片显示不出来，按清单排查一遍，多半十分钟内就能定位到问题所在。