Vue 项目里图片引不出来这种事从新手到老手几乎都遇到过。我见过不少奇怪报错有的本地起服务一切正常npm run build之后页面所有图标全裂有的在某个组件里写../assets/logo.png看着没问题换两层目录就 404还有的在style里写url(~/assets/bg.png)能显示放到img标签里就失效。这篇文章就围绕静态资源中最常见的图片引用把 Vue 里的相对路径、绝对路径、别名、~符号这几类写法一次理清楚再结合打包后的路径变化聊透部署场景下的坑。无论你是刚接触 Vue 的新手还是写了好几个项目但始终没弄明白静态资源路径的“熟练工”这篇文章都值得花十分钟看完。我会把开发服务器里的请求情况、构建产物目录都拆开讲并且准备了一个可以直接在本地跑起来的演示工程方便你对照验证。毕竟路径问题光看文档容易迷糊真正在浏览器 Network 面板里看一次就全明白了。1. 先搞清楚 Vue 项目里的两套静态资源机制1.1 src/assets 与 public 目录的本质区别在 Vue CLI 和 Vite 的项目结构里静态资源默认有两个存放位置src/assets和public。这两个目录的处理机制完全不同这也是路径问题最大的根源。src/assets下的资源会参与打包。以图片为例它会走一遍构建工具的资源处理链小体积图片会被转成 base64 字符串直接嵌进代码里大体积图片会被复制到打包输出目录并重新命名加哈希值。这种处理方式的优势是浏览器请求数减少、文件名带哈希方便缓存更新代价是“文件路径在打包后不再是你写的那个路径了”。public目录则简单粗暴里面的文件会被原样复制到打包结果的根目录不压缩、不哈希、不做任何转换。你在代码里怎么写引用路径上传服务器后就得按这个路径去访问。这个目录适合放 favicon.ico、外部脚本、某些不想参与构建的静态文件。理解了这两套机制再看路径写法就会清晰很多写在src/assets里的资源需要考虑“构建工具会怎么处理我写的这个字符串”写在public下的资源需要考虑“浏览器最终会请求哪个 URL”。1.2 路径解析的层级代码的哪一层在处理你的路径很多人有个直觉只要从“当前文件出发”的路径指对了就行。但这个直觉在 Vue 项目里经常失灵因为一行路径可能被不同层级的处理器解析而它们遵循的规则不一样。我们先按代码出现的位置把路径分成三类模板里的src属性、script里的import语句、以及style里的url()。在 Vue 的 SFC 单文件组件中这三部分会被分别交给不同的编译器或加载器处理。模板部分的src会被 vue-loader 或 Vue 插件转换import语句会被 webpack 或 Vite 的模块解析器处理样式里的url()则要经过 css-loader 或 Vite 的 CSS 插件。每一层对相对路径、、~的支持程度都有细微差别。所以判断一条路径是否正确不要只看“从当前文件能不能到目标文件”还要看“写路径的这行代码最终会被哪一层处理器给吃掉”。这个视角一旦建立起来很多奇奇怪怪的 404 问题都能自己推断出答案。2. 四类路径写法逐个拆解相对路径、绝对路径、、~2.1 相对路径与绝对路径的行为差异相对路径./、../是大家最熟悉的写法它从当前模块文件出发去寻找目标资源。在template的img标签里写img src./assets/logo.png这个src会被构建工具解析成对./assets/logo.png的依赖请求并交给资源加载器处理。相对路径最大的问题是“脆弱”组件目录一旦变深../就要跟着加层级一乱就会引用错位置。我自己写项目时只有在资源文件和组件距离很近、且只有一个组件用到时才会用相对路径否则一律用别名。绝对路径在这里需要分两种情况。第一种是网络上的完整 URL比如https://cdn.example.com/images/a.png这种浏览器直接请求原样地址构建工具不会管。第二种是根路径写法比如/images/logo.png在 Vue 项目里它默认指向public目录的根也就是打包后服务器域的根路径。这里就藏着一个常见的部署坑如果项目部署在域名子目录下/images/logo.png仍然会去请求域名最顶层的/images/logo.png结果肯定是 404。这个问题我放到第四章详细说。2.2 别名的配置与使用边界是 Vue 生态里最常见的路径别名默认指向src目录。在 Vue CLI 创建的项目里已经配置好可以直接使用在 Vite 项目里需要手动在vite.config.js中配置resolve.alias通常写法是// vite.config.js import path from path import { defineConfig } from vite export default defineConfig({ resolve: { alias: { : path.resolve(__dirname, src) } } })配置好之后在script的import语句里写import logo from /assets/logo.png这种写法的好处是无论组件嵌套在哪个目录层级永远指向src从根源上消灭了“../../../数不清”的问题。值得注意的是在 Vue CLI 项目的template里直接写img src/assets/logo.png是可以被解析的因为 vue-loader 会把模板里的这个src转成一个require(/assets/logo.png)请求再交给 webpack 的模块解析别名在这个环节依然有效。但在 Vite 项目里如果你的alias配置得没问题在模板中也能工作原理是 Vue 插件将模板中的静态资源路径变成了一个 import 声明。不过为了少踩莫名其妙的坑我更推荐在script中用import显式引入再通过变量去绑定src。2.3 ~ 符号的真正用途CSS 模块解析的钥匙~这个符号看起来神秘实际上是一个专门为解决 CSS 解析问题而存在的“钥匙”。在 webpack 体系下当你在 CSS 或预处理器文件里写url()时css-loader 默认会把相对路径解析成相对于当前样式文件的路径。但如果你写url(/assets/logo.png)css-loader 不会主动去识别别名它很可能直接把当成一个相对目录去拼接结果报找不到模块。解决办法就是在路径前面加上~.background { background-image: url(~/assets/logo.png); }这里的~是在告诉 css-loader别按普通 url 处理把后面这段字符串当模块请求扔给 webpack 的模块解析器这样一来别名就能识别了。在 Vite 中~的语义类似Vite 会剥离~然后把后面内容当作模块 ID 去解析所以~/assets/logo.png也能正常工作。还有一个细节Vite 里直接写url(/assets/logo.png)其实也能解析因为 Vite 的 CSS 处理会自动按 alias 尝试解析。但考虑到项目可能在 Vue CLI 和 Vite 之间迁移保留~/这种写法兼容性最高。3. 图片引入实操template、script、style 与动态绑定3.1 template 中直接用 src 引入图片在模板里引入图片是最直观的场景我按不同写法整理了一个可以直接运行的示例template div classpath-demo !-- 相对路径相对于当前 .vue 文件 -- img src./assets/logo.png altrelative / !-- 上级目录控制好层级就行 -- img src../assets/logo.png altparent / !-- 指向 public 目录下的一张图 -- img src/images/logo.png altpublic / !-- 别名推荐写法 -- img src/assets/logo.png altalias / /div /template这里最容易被忽略的是src./assets/logo.png这种写法虽然看着像纯字符串但在 Vue CLI 的构建体系里它会被 vue-loader 识别并转成require(./assets/logo.png)所以图片才能被打包处理。如果你在src前面动态绑定:src./assets/logo.png这个字符串就不会被构建工具转换运行时就只能按浏览器地址栏的相对位置去找大概率 404。这个细微差别非常关键我会在 3.4 节再展开。演示工程里我建议你重点观察 Network 面板相对路径和别名的图片请求在开发环境下会真实存在如果你把一张public目录下的图片路径写成/public/images/logo.png请求会直接 404因为public目录的文件应该以/images/logo.png这种不带public前缀的方式访问。3.2 script 中用 import 和 require 引入图片当图片需要被当作模块使用比如传给 canvas 或手动设置 DOM 背景时就要在script里引入。最推荐的是静态importscript setup import logo from /assets/logo.png /script template img :srclogo altimported / /template这里有一个新手常犯的错误import的路径必须是固定的字符串不能是拼接出来的变量。如果你硬写import logo from /assets/ name .png语法上就不被允许会在编译阶段直接报错。在 webpack 体系里对应的方法是使用require// Vue CLI / webpack 环境 const logo require(/assets/logo.png)require支持动态拼接字符串比如require(/assets/ name .png)webpack 会尝试把能匹配上的资源都打包进来运行时再按具体请求取出对应文件。但正因为这个“打包所有可能文件”的行为它会把整个目录下符合条件的图片全部打进产物导致包体积变大所以不建议滥用。如果确实有很多图片需要动态加载更应该用require.context明确筛选范围不过这部分严格来说已经超出路径问题的范畴了。在 Vite 里除了import和require还有一种官方推荐的方式是new URLconst logoUrl new URL(./assets/logo.png, import.meta.url).href这种写法的特点是基于当前模块的 URL 来计算目标路径可以结合模板字符串做动态拼接但在构建时要求相对路径的模式能被静态识别否则构建会警告或失效。3.3 style 中 url() 引入背景图的关键细节在style中引用背景图是~符号出现频率最高的场景。以 Vue 单文件组件为例style langscss scoped .card { /* 相对于当前 .vue 文件 */ background-image: url(../assets/card-bg.png); /* 推荐使用 ~ 加上 别名 */ background-image: url(~/assets/card-bg.png); } /style如果你在 webpack 环境下老老实实写url(/assets/card-bg.png)大概率会碰到 css-loader 解析失败报“找不到模块 /assets/card-bg.png”。加上~之后css-loader 会把后面内容当作模块请求来处理别名才能生效。在 Vite 里我实测过url(/assets/card-bg.png)也可以出图但为了项目将来可能切换构建工具建议保持~/的写法。还有一个和预处理相关的细节在scss或less文件中如果你把图片路径写在一个变量里再传给url()比如background-image: url($bg)路径解析的规则会略有不同因为预处理器在编译阶段就可能把路径改写了。遇到这种情况最简单的方法是把变量值里直接写成完整的~/assets/xxx.png并确保构建工具能识别。3.4 动态 src 的正确姿势打包处理与运行时解析的界线动态绑定src是路径问题中翻车率最高的一类典型错误是template !-- 这种写法不行运行时会拿这个字符串去请求 -- img :src/assets/${imageName}.png / /template开发时如果项目跑在根路径/assets/xxx.png可能碰巧能命中 dev server 里的某个资源一旦打包上线资源路径会被加上哈希比如/assets/photo.a1b2c3.png你写死的字符串里并没有这些哈希请求就直接 404 了。正确思路是在构建阶段就把图片“拿进”打包流程然后在运行时只负责选择文件。在 Vue CLI 项目中最朴素的做法是写一个方法methods: { getImage(name) { return require(/assets/${name}.png) } }在 Vite 项目中require不可用我更常用import.meta.globscript setup const modules import.meta.glob(/assets/*.png, { eager: true, import: default }) const getImage (name) modules[/assets/${name}.png] /script这段代码会在构建时把/assets下的所有.png文件都收集起来运行时通过name取出对应的打包后 URL。这种方式把路径问题完全收敛到了构建层是我目前最推荐的动态图片方案。演示工程里我专门放了一个下拉框选择不同图片的页面你能直观看到切换时 Network 请求如何从同一份打包资源里取图。4. 打包构建后的路径变化与部署调整4.1 资源打包后究竟去了哪里先看一个 Vue CLI 项目打包后的典型目录结构dist/ ├── index.html ├── css/ │ └── app.a1b2c3.css ├── js/ │ ├── app.a1b2c3.js │ └── chunk-vendors.a1b2c3.js ├── img/ │ └── logo.c4d5e6.png └── favicon.icosrc/assets/logo.png打包后会进入img目录并被改名为logo.c4d5e6.pngpublic/favicon.ico则原样复制到dist根目录。打开打包后的index.html你看到的是script defer src/js/app.a1b2c3.js/script link href/css/app.a1b2c3.css relstylesheet /这个/js/...前缀来自构建配置里的publicPathVue CLI或baseVite。默认是根路径/表示资源从服务器域名的根开始找。这样做有个明显问题如果项目部署到https://example.com/my-app/这个子目录浏览器加载index.html后会去请求https://example.com/js/app.a1b2c3.js而不是https://example.com/my-app/js/app.a1b2c3.js结果自然就是 404。CSS 加载不出来页面布局当然整个崩塌。4.2 部署到服务器子目录时的 base 配置变更解决子目录部署问题思路就是告诉构建工具所有生成的资源路径都要带上前缀。Vue CLI 项目在vue.config.js里设置module.exports { publicPath: process.env.NODE_ENV production ? /my-app/ : / }Vite 项目在vite.config.js里设置export default { base: process.env.NODE_ENV production ? /my-app/ : / }设置后打包出来的index.html就会变成/my-app/js/app.a1b2c3.js资源请求路径就和部署目录对上了。还有一种更省心的写法是把publicPath或base直接设为./这样打包后所有资源路径都变成相对路径。用相对路径时index.html无论放在哪个子目录资源都会基于当前 HTML 文件位置去查找对部署位置比较包容。缺点也很明显如果项目里有基于绝对路径写死的路由、或者需要配合 history 路由这种相对路径方案会带来新的问题。4.3 打包后布局异常最常见的 404 资源链很多人在网上搜“Vue 打包后布局异常”走进来一看CSS 没挂上JS 没加载页面像纯文本。这种情况十有八九是资源路径没有配上部署目录。排查的第一步是打开浏览器控制台的 Network 面板看 HTML 请求之外的 JS、CSS 资源返回了什么。如果一堆404你就把 URL 和实际部署目录对比一下基本能判断是缺少/my-app/前缀还是路径多了一截。第二步是看 HTML 里的资源引用方式。如果你用的是publicPath: ./但 HTML 里有一张图片写成/images/logo.png这张图在子目录部署时依然会 404因为它是纯浏览器绝对路径不受构建配置控制。所以在子目录部署场景里凡是涉及public目录下的资源引用我都建议用相对路径或者通过BASE_URL动态拼接const assetUrl ${import.meta.env.BASE_URL}images/logo.pngVue CLI 里对应的环境变量是process.env.BASE_URL。用这种方式组合出来的 URL会跟着构建配置里的publicPath或base一起变化就不会出现“其他资源都好就那几张图 404”的诡异情况了。5. 常见问题与排查技巧实录5.1 本地正常、打包后图片全无这个问题的根源通常是开发服务器和打包产物对路径的处理方式不同。开发服务器为了实时编译会把很多相对路径自动修正打包产物则是按最终的资源输出路径来写。我遇到过最典型的一个例子项目里用img src/assets/logo.png开发时因为 dev server 把某个目录暴露在根路径下所以能显示以为没问题打包后在纯静态服务器上一看/assets/logo.png请求 404。查了半天才发现资源放在public/assets下但 server 部署在/web子路径浏览器去请求域名的根路径/assets/...当然找不到。应对方式很简单先定位资源文件的归属。如果图片在src/assets尽量用/assets/...或import引入如果图片在public引用时用BASE_URL拼接别写死/开头的绝对路径。5.2 动态拼接图片路径不生效前面已经说过构建工具只能静态分析固定的路径字符串。import logo from /assets/logo.png这种写死了的路径能被处理:src/assets/${name}.png这种由运行变量拼出来的字符串构建工具完全无能为力。如果你非要在运行时拼接路径就得让拼接过程发生在构建层webpack 用require或require.contextVite 用import.meta.glob。记住这个分界就能少走弯路凡是经过构建的资源路径动作发生在构建阶段运行时只能“选择已经构建好的资源”而不是“重新拼一个资源路径”。5.3 常用排查命令与速查表排查路径问题时我通常按这套流程走# 先看打包后的资源引用的基础路径 # Vue CLI npx vue-cli-service inspect # Vite npx vite build --debug直接把打包入口 index.html 和相关 CSS/JS 标签里的路径和浏览器实际请求对比效率最高。下面是几张速查表方便你对照判断。写入场景写法说明模板 img src./assets/logo.png相对路径会经过构建处理模板 img src/images/logo.png指向 public不参与构建模板 img src/assets/logo.pngVue CLI 可用Vite 需配置 aliasscript import/assets/logo.png最推荐构建时会正确解析script require/assets/logo.png仅 webpack 环境style url../assets/bg.png相对于当前样式文件style url~/assets/bg.png兼容 webpack 与 Vite运行时动态绑定require或import.meta.glob构建阶段处理运行时写死字符串不可行会直接 404部署场景推荐配置服务器根路径部署publicPath: //base: /子目录部署publicPath: /my-app//base: /my-app/子目录部署且不确定位置publicPath: .//base: ./需要 history 路由避免用./建议显式子目录路径最后再补充一个我自己的习惯在项目初期就约定好图片资源的存放规则并把这些规则写进 README。优先级从高到低是静态 import /路径优先public 资源统一通过BASE_URL引用动态资源走构建层工具所有写死/开头路径的代码必须过评审。养成这个习惯之后团队里因为图片引用产生的“玄学问题”基本就绝迹了。你可以直接照着这篇文章的演示工程试一遍把四类路径都跑一遍浏览器控制台的红色报错会比一千句经验总结记得更牢。