Vue 项目里写静态资源路径看着简单实际坑不少。前两天帮同事排查一个线上问题本地开发一切正常打包部署后页面图片全挂最后定位到根因就是路径写法和构建配置不匹配导致编译后的资源 URL 指向了错误位置。这类问题在 Vue 开发者里太常见了而且多半出在 相对路径、绝对路径、 别名、~ 前缀 这几种写法的底层逻辑没捋清楚。这篇笔记我专门以图片引入为例把这几种路径方式从头到尾梳理一遍它们分别在什么场景下生效编译后到底变成了什么本地和打包部署有什么差异以及最常见的几类报错怎么排查。另外我会给一个可以在线运行的演示工程直接打开浏览器就能对照验证不用先搭一堆环境。1. 先理解底层静态资源的两种存放姿势1.1 src/assets 和 public 的本质区别Vue 项目里放图片、字体、PDF 这类静态文件常规位置就两个src/assets和public。很多人只知道一个会被打包一个不会但没理解背后的设计意图导致后面选路径时全凭感觉。先说src/assets。这个目录下的文件会经过完整构建处理以 Vue CLIWebpack项目为例图片资源统一交给url-loader/file-loader处理小于设定阈值默认约 4KB的图片会直接转成 base64 字符串内联到 JS 里这样能减少一次 HTTP 请求超过阈值的则会被复制到打包输出目录文件名自动加上 hash 指纹类似logo.5c0b3a2f.png。指纹的作用是方便浏览器缓存更新——文件内容变了文件名就变不会命中旧缓存。再看public目录。这个目录下的文件完全原样拷贝到dist根目录不压缩、不指纹、不转 base64。访问方式也很直接开发时public/logo.png对应 URL 路径/logo.png打包后同样以/logo.png存在于服务器上。选择标准其实很清晰需要被构建处理、想吃压缩和指纹红利、由代码直接引用的资源放src/assets希望保持路径不变、不经过构建加工的资源放public。比如 favicon、第三方合作方要固定访问的静态文件就适合 public。但绝大多数业务图片正确选择都是src/assets。1.2 理解“编译时路径处理”是排坑的前提排查路径问题最大的阻碍是不少人默认浏览器会自己去解析这些路径。实际上 Vue 项目里的资源引用绝大多数在编译期就被处理了Webpack 或 Vite 在打包时根据你代码里写的路径去解析真实文件决定这个资源是转成 base64、输出成新文件还是原样保留然后把最终结果替换进编译产物。我给你举个例子。模板里写img src./assets/logo.png浏览器并不是自己跑到服务器上去找./assets/logo.png这个相对路径而是vue-loader在编译阶段先把这个文件解析出来转成 base64 或生成带 hash 的新文件最后把编译后的地址写进渲染函数。理解了这一点你就能解释很多诡异现象。比如 js 里动态拼接路径不生效因为编译期根本不知道你运行时把字符串拼成了什么比如在 style 里偶尔失效因为 CSS 的解析链路和 JS 不是一回事。所有路径坑本质上都是没分清这段路径是给编译器看的还是给浏览器看的。2. 四种路径写法逐一拆解2.1 相对路径./ 和 ../最直观但最容易写乱相对路径是以当前文件所在目录为基准去定位另一个文件。在 Vue 组件里img src./assets/logo.png表示去当前组件文件同级的assets目录找logo.png。在template的img标签、style的url()中相对路径都会被构建工具解析和加工资源正常进入打包流程。所以从功能上相对路径是能用的而且在小项目里很直观不用担心别名配置问题。但它有个致命弱点目录层级一深../../../../../assets/logo.png这种写法会让代码丑到没法看而且一旦调整目录结构所有引用全部失效。你想想一个组件如果你深挖到src/views/admin/user/components/ButtonGroup/index.vue要引用根目录附近的图片那../的数量数到怀疑人生。我的建议是相对路径只适合引用和自己强相关的、距离很近的资源比如当前组件目录下的一个小图。其他情况尽量别用。2.2 绝对路径/ 开头与 public 目录深度绑定这里说的绝对路径不是带域名的那种完整 URL而是站内根路径写法即/开头比如/images/logo.png。它的解析规则非常简单开发时去public目录里找对应文件打包后原样输出到服务器根路径。所以如果你写img src/images/logo.png团队里必须约定public/images/logo.png这个文件确实存在。它不会经过 Webpack 或 Vite 处理不会转 base64也不会加 hash。这种写法的坑主要在部署阶段。假如你的应用部署在https://example.com/myapp/这个子路径下而代码里写的是/images/logo.png浏览器会把它解析成https://example.com/images/logo.png——请求直接跑到域名根路径去了自然 404。要解决这个问题要么配合publicPath或base配置统一处理要么干脆少用这种绝对路径。2.3 别名指向 src 的灵魂写法本质上是一个路径别名alias它在构建配置里被指向src目录。你写/assets/logo.png编译器会把它当作src/assets/logo.png来解析。Vue CLI 创建的项目默认配好了vue.config.js里也能看到相关配置。Vite 项目如果用的是 create-vue 新模板也默认可用老项目或手动搭建的 Vite 项目则需要自己在vite.config.js里配置// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue import { fileURLToPath, URL } from node:url export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } } })的好处就是终结../../灾难代码可读性直线上升。它最常用于template和script中基本畅通无阻。但在 Webpack 项目的style里直接写url(/assets/logo.png)是有可能出问题的因为css-loader对路径的解析和 JS 模块解析不是同一套逻辑这时候就需要请出~前缀。2.4 ~ 符号主要服务于 CSS别在 JS 里乱用~这个符号对新手最不友好因为它只在特定场景下有用。它的核心作用是告诉 CSS 的解析器后面这段内容不是普通路径而是模块路径请你把它交给 Webpack 按模块规则去解析。典型场景有两个。第一个是~/assets/logo.png用来在 CSS 的url()里配合别名使用解决上一节说的style 里 可能失效的问题。第二个是引用node_modules里的资源比如url(~bootstrap/dist/img/logo.png)表示去node_modules下找bootstrap包里的文件。需要特别注意的是在 JS 和 template 里不需要也不应该加~。import logo from ~/assets/logo.png这种写法纯属多余直接写就行。Vite 场景下~的存在感会弱不少因为 Vite 对 CSS 中的别名解析支持得更好你写/assets/logo.png通常就能正常工作。不过为了兼容某些插件或历史项目Vite 对~开头的内容也会特殊处理剥掉~后当模块路径解析。所以~在 Vite 里写了也不会报错但我个人建议 Vite 项目里按官方文档走少用~。2.5 一张表总结四种写法写法解析基准是否被构建处理主要适用场景典型坑./assets/logo.png当前文件所在目录是引用近距离资源层级深了难维护/images/logo.png服务器根路径public否保持路径不变的静态文件子目录部署时 404/assets/logo.png别名指向 src是template 和 script 中的资源引用style 里可能失效~/assets/logo.png模块路径 别名是CSS url() 中引用别名资源不熟悉时容易混3. 三个高频场景实操3.1 template 里的 img静态与动态的区别模板里引用图片最常用的写法就是三种相对路径、别名、绝对路径。!-- 相对路径编译期解析资源会被构建处理 -- img src./assets/logo.png altlogo / !-- 别名推荐写法 -- img src/assets/logo.png altlogo / !-- 绝对路径对应 public/images/logo.png不构建处理 -- img src/images/logo.png altlogo /关键区别在动态绑定。如果你写成:srcimgUrl并且imgUrl是通过字符串拼接出来的比如/assets/ name .png那这张图必然出不来。原因在前面讲过编译器在打包时面对的是一个动态字符串它没法静态分析出真实文件是谁于是只能原样输出而浏览器拿到/assets/xxx.png这种地址根本不知道去哪找。正确的动态引入姿势是这样的script setup import logo from /assets/logo.png /script template img :srclogo altlogo / /template先把图片 import 进来作为一个模块对象再绑定给src让编译器在 import 阶段就知道资源位置。后面我会在在线演示里跑这个场景。3.2 style 里的 background别踩别名失效的坑CSS 里引用背景图写法上比模板更讲究。style scoped .box { /* Webpack 项目推荐 ~ 写法 */ background: url(~/assets/bg.png) center center / cover no-repeat; } /style为什么这里要用~而不是直接因为 CSS 文件在被css-loader解析时url()里的路径默认会被当作相对路径处理。直接写/assets/bg.pngcss-loader不知道是什么可能直接报错或者把它解析成一个错误的相对路径。加了~前缀之后css-loader就会明白这是模块路径转交给 Webpack 的模块解析逻辑别名也就能正确生效了。Vite 项目就没这么折腾CSS 里直接写/assets/bg.png就能被正确解析。不过如果你是从老项目迁移过来的遇到style里失效先检查 Vite 的resolve.alias是否配置再看当前版本对 CSS 别名支持是否有异常。还有一点scoped属性只影响样式作用域不影响资源路径解析别在这上面绕弯。3.3 script 里引入图片import、require 与 new URL现在写 Vue 3 Vite 是主流我先说这种组合下的推荐做法。在script setup里引入图片通常有两种方式// 方式一静态 import编译器能解析Vite/Webpack 都支持 import logo from /assets/logo.png // 方式二运行时动态路径Vite 推荐用 new URL function getLogo(name) { return new URL(../assets/${name}.png, import.meta.url).href }new URL(..., import.meta.url)是 Vite 官方推荐的动态资源引用方式它让浏览器在运行时基于import.meta.url当前模块的 URL去解析相对路径这样就不需要预先知道所有文件名。如果你还在用 Vue CLI 或者老版本 Webpack 项目可能会经常见到require写法// Vue CLI 项目可用 const logo require(/assets/logo.png)注意require是 Webpack 提供的模块系统语法Vite 原生不支持。在 Vite 项目里看到require is not defined就是这问题解决办法就是换 import 或 new URL。还有一个更适合批量场景的 Vite 方案是import.meta.glob可以把目录下所有图片一次性映射成对象适合做批量资源统一管理比如一个目录放了几十张图标想全部引入时很省事。不过这个用在你确实需要所有图片的前提下别为了帅而滥用。4. 在线演示一个工程验证所有结论4.1 演示环境怎么搭说再多不如跑一遍。我准备了一个可以直接在线运行的演示工程不用本地装 Node、不用配环境打开浏览器就能操作。打开 StackBlitz 网站点击新建项目选择 Vue 模板默认就是 Vite Vue 3 的组合。项目创建后需要准备一张测试图片随便找一张小 png命名为logo.png把它放到src/assets/目录下。同时在public目录下新建一个images子目录也放一张logo.png内容可以和 assets 里的相同用不同名字也行方便区分即可。最终目录结构类似这样src/ assets/ logo.png App.vue public/ images/ logo.png4.2 演示代码App.vue下面这份App.vue覆盖了五种引用方式复制进在线项目就能直接跑。template div classdemo h2Vue 静态资源路径演示/h2 div classrow p1. 相对路径./assets/logo.png/p img src./assets/logo.png altrelative width80 / /div div classrow p2. 别名/assets/logo.png/p img src/assets/logo.png altalias width80 / /div div classrow p3. 绝对路径/images/logo.png对应 public/images//p img src/images/logo.png altpublic width80 / /div div classrow p4. 动态绑定import 进来的图片/p img :srclogoUrl altdynamic import width80 / /div div classrow p5. style 中通过 引入背景图/p div classbg-box / /div /div /template script setup import logo from /assets/logo.png const logoUrl logo /script style scoped .demo { padding: 24px; } .row { margin-bottom: 16px; } .bg-box { width: 80px; height: 80px; border: 1px solid #ccc; background: url(/assets/logo.png) center center / contain no-repeat; } /style几点说明第 2 种和第 4 种本质上都是走别名只是引用方式不同第 5 种在 Vite 下直接写可以生效如果你把这份代码搬到 Vue CLI 项目里背景图那行建议改成~/assets/logo.png这就是前面章节反复强调的环境差异。4.3 怎么看结果运行起来之后正常情况五张图都能显示。但光能显示还不够建议你打开浏览器开发者工具重点看两件事。第一看Elements面板里img标签编译后的src是什么。当使用相对路径和时你会发现src已经不是代码里写的那个路径而变成了 base64 长串或者带 hash 的文件名取决于图片大小和构建配置。这就是编译期路径换血最直观的证据。而绝对路径那一种src依然是/images/logo.png原样保留。第二可以试试执行一次构建。StackBlitz 的终端里跑npm run build然后看dist目录结构assets里的图片被处理进了dist/assets或类似目录文件带 hashpublic/images/logo.png则会原样出现在dist/images/logo.png。这个对比直接把两种存放姿势的差异摊开了。5. 常见问题与排查技巧5.1 问题一打包后图片全部 404这是被问得最多的一个问题。排查思路按顺序走基本一两分钟内能定位。第一步打开打包产物目录确认图片到底有没有被打包进去。如果dist目录里根本没有这个文件说明路径解析有问题检查代码里的路径是否存在、是否写错优先换成别名再试。如果文件在但页面 404问题大概率出在部署路径配置上。第二步看浏览器 Network 面板找那条 404 请求看它实际请求的 URL 是什么。比如你部署在https://example.com/myapp/而请求地址是https://example.com/images/logo.png那基本可以断定是代码里用了/开头的绝对路径同时项目的publicPath或base没配置子路径。5.2 问题二动态拼接路径不生效模板里写:src/assets/ name .png图片死活不显示控制台报 404 或者直接警告。原因已经重复好几次了编译期无法解析动态字符串资源。解决方案有三个方向。一是用 import 静态引入后再根据条件切换二是用 Vite 的new URL运行时解析三是 Webpack 环境用require拼接完整路径。如果你有一整个目录的图片要动态展示import.meta.globVite或require.contextWebpack是更优雅的方案。5.3 问题三 在 style 里不生效现象是 CSS 里写url(/assets/bg.png)报错或图片 404但同样是写在 template 里却没事。这本质上不是 Vue 的问题而是构建链路上 CSS 解析器对路径的理解不同。Webpack 项目里解决办法就是给加上~前缀写成url(~/assets/bg.png)。Vite 项目里先说确认resolve.alias配置正确再确认 Vite 版本对 CSS 别名的解析行为个别版本可能会对~和处理方式有细微差别直接换个写法试试就能定位。5.4 问题四部署到子目录后全崩项目要部署到https://example.com/myapp/这类子路径结果样式丢失、图片 404。这通常是构建配置里缺了publicPathVue CLI或baseVite。Vue CLI 项目在vue.config.js里设置// vue.config.js module.exports { publicPath: /myapp/ }Vite 项目在vite.config.js里设置// vite.config.js export default defineConfig({ base: /myapp/ })注意配置base或publicPath只会影响构建时生成的资源路径对于代码里手写的/images/logo.png这类绝对路径它是不会自动帮你加前缀的。所以最省心的做法是业务代码里少写站内绝对路径统一用或相对路径让构建工具统一控制资源地址。5.5 问题速查表现象可能原因解决方向打包后图片 404dist 中无此文件代码路径写错或未成功解析改用别名并确认文件存在打包后图片 404dist 中有文件部署在子路径publicPath/base 没配配置publicPath或base动态拼接 src 不生效编译期无法解析运行时字符串import、new URL、require、globstyle 中 失效css-loader 不识别别名Webpack 写~Vite 检查 alias本地正常上线全崩绝对路径 子目录部署少用/开头路径配置 baseVite 项目 require 报错require 是 Webpack 语法改用 import 或 new URL6. 一点实操心得路径问题的核心其实就是一句话先分清资源放哪再决定用哪种写法。我自己的习惯是业务图片一律放src/assetstemplate和script里统一用别名Webpack 项目的style里用~Vite 项目直接用。public目录只放需要原样访问的静态文件而且很少在代码里通过绝对路径引用它。另外还有个小技巧每次打包部署后别急着关终端先看一眼构建产物目录再打开浏览器 Network 检查图片请求。这两步加起来不超过一分钟但能让你在问题刚冒头时就发现不用等到线上用户反馈再手忙脚乱去复盘。路径这东西看着是小事但它几乎会出现在你写的每一个组件里。花半小时把原理和坑位搞清楚后续能省下大量排查时间。希望这篇笔记能给你省下这段弯路。
Vue 项目里写静态资源路径看着简单实际坑不少。前两天帮同事排查一个线上问题本地开发一切正常打包部署后页面图片全挂最后定位到根因就是路径写法和构建配置不匹配导致编译后的资源 URL 指向了错误位置。这类问题在 Vue 开发者里太常见了而且多半出在 相对路径、绝对路径、 别名、~ 前缀 这几种写法的底层逻辑没捋清楚。这篇笔记我专门以图片引入为例把这几种路径方式从头到尾梳理一遍它们分别在什么场景下生效编译后到底变成了什么本地和打包部署有什么差异以及最常见的几类报错怎么排查。另外我会给一个可以在线运行的演示工程直接打开浏览器就能对照验证不用先搭一堆环境。1. 先理解底层静态资源的两种存放姿势1.1 src/assets 和 public 的本质区别Vue 项目里放图片、字体、PDF 这类静态文件常规位置就两个src/assets和public。很多人只知道一个会被打包一个不会但没理解背后的设计意图导致后面选路径时全凭感觉。先说src/assets。这个目录下的文件会经过完整构建处理以 Vue CLIWebpack项目为例图片资源统一交给url-loader/file-loader处理小于设定阈值默认约 4KB的图片会直接转成 base64 字符串内联到 JS 里这样能减少一次 HTTP 请求超过阈值的则会被复制到打包输出目录文件名自动加上 hash 指纹类似logo.5c0b3a2f.png。指纹的作用是方便浏览器缓存更新——文件内容变了文件名就变不会命中旧缓存。再看public目录。这个目录下的文件完全原样拷贝到dist根目录不压缩、不指纹、不转 base64。访问方式也很直接开发时public/logo.png对应 URL 路径/logo.png打包后同样以/logo.png存在于服务器上。选择标准其实很清晰需要被构建处理、想吃压缩和指纹红利、由代码直接引用的资源放src/assets希望保持路径不变、不经过构建加工的资源放public。比如 favicon、第三方合作方要固定访问的静态文件就适合 public。但绝大多数业务图片正确选择都是src/assets。1.2 理解“编译时路径处理”是排坑的前提排查路径问题最大的阻碍是不少人默认浏览器会自己去解析这些路径。实际上 Vue 项目里的资源引用绝大多数在编译期就被处理了Webpack 或 Vite 在打包时根据你代码里写的路径去解析真实文件决定这个资源是转成 base64、输出成新文件还是原样保留然后把最终结果替换进编译产物。我给你举个例子。模板里写img src./assets/logo.png浏览器并不是自己跑到服务器上去找./assets/logo.png这个相对路径而是vue-loader在编译阶段先把这个文件解析出来转成 base64 或生成带 hash 的新文件最后把编译后的地址写进渲染函数。理解了这一点你就能解释很多诡异现象。比如 js 里动态拼接路径不生效因为编译期根本不知道你运行时把字符串拼成了什么比如在 style 里偶尔失效因为 CSS 的解析链路和 JS 不是一回事。所有路径坑本质上都是没分清这段路径是给编译器看的还是给浏览器看的。2. 四种路径写法逐一拆解2.1 相对路径./ 和 ../最直观但最容易写乱相对路径是以当前文件所在目录为基准去定位另一个文件。在 Vue 组件里img src./assets/logo.png表示去当前组件文件同级的assets目录找logo.png。在template的img标签、style的url()中相对路径都会被构建工具解析和加工资源正常进入打包流程。所以从功能上相对路径是能用的而且在小项目里很直观不用担心别名配置问题。但它有个致命弱点目录层级一深../../../../../assets/logo.png这种写法会让代码丑到没法看而且一旦调整目录结构所有引用全部失效。你想想一个组件如果你深挖到src/views/admin/user/components/ButtonGroup/index.vue要引用根目录附近的图片那../的数量数到怀疑人生。我的建议是相对路径只适合引用和自己强相关的、距离很近的资源比如当前组件目录下的一个小图。其他情况尽量别用。2.2 绝对路径/ 开头与 public 目录深度绑定这里说的绝对路径不是带域名的那种完整 URL而是站内根路径写法即/开头比如/images/logo.png。它的解析规则非常简单开发时去public目录里找对应文件打包后原样输出到服务器根路径。所以如果你写img src/images/logo.png团队里必须约定public/images/logo.png这个文件确实存在。它不会经过 Webpack 或 Vite 处理不会转 base64也不会加 hash。这种写法的坑主要在部署阶段。假如你的应用部署在https://example.com/myapp/这个子路径下而代码里写的是/images/logo.png浏览器会把它解析成https://example.com/images/logo.png——请求直接跑到域名根路径去了自然 404。要解决这个问题要么配合publicPath或base配置统一处理要么干脆少用这种绝对路径。2.3 别名指向 src 的灵魂写法本质上是一个路径别名alias它在构建配置里被指向src目录。你写/assets/logo.png编译器会把它当作src/assets/logo.png来解析。Vue CLI 创建的项目默认配好了vue.config.js里也能看到相关配置。Vite 项目如果用的是 create-vue 新模板也默认可用老项目或手动搭建的 Vite 项目则需要自己在vite.config.js里配置// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue import { fileURLToPath, URL } from node:url export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } } })的好处就是终结../../灾难代码可读性直线上升。它最常用于template和script中基本畅通无阻。但在 Webpack 项目的style里直接写url(/assets/logo.png)是有可能出问题的因为css-loader对路径的解析和 JS 模块解析不是同一套逻辑这时候就需要请出~前缀。2.4 ~ 符号主要服务于 CSS别在 JS 里乱用~这个符号对新手最不友好因为它只在特定场景下有用。它的核心作用是告诉 CSS 的解析器后面这段内容不是普通路径而是模块路径请你把它交给 Webpack 按模块规则去解析。典型场景有两个。第一个是~/assets/logo.png用来在 CSS 的url()里配合别名使用解决上一节说的style 里 可能失效的问题。第二个是引用node_modules里的资源比如url(~bootstrap/dist/img/logo.png)表示去node_modules下找bootstrap包里的文件。需要特别注意的是在 JS 和 template 里不需要也不应该加~。import logo from ~/assets/logo.png这种写法纯属多余直接写就行。Vite 场景下~的存在感会弱不少因为 Vite 对 CSS 中的别名解析支持得更好你写/assets/logo.png通常就能正常工作。不过为了兼容某些插件或历史项目Vite 对~开头的内容也会特殊处理剥掉~后当模块路径解析。所以~在 Vite 里写了也不会报错但我个人建议 Vite 项目里按官方文档走少用~。2.5 一张表总结四种写法写法解析基准是否被构建处理主要适用场景典型坑./assets/logo.png当前文件所在目录是引用近距离资源层级深了难维护/images/logo.png服务器根路径public否保持路径不变的静态文件子目录部署时 404/assets/logo.png别名指向 src是template 和 script 中的资源引用style 里可能失效~/assets/logo.png模块路径 别名是CSS url() 中引用别名资源不熟悉时容易混3. 三个高频场景实操3.1 template 里的 img静态与动态的区别模板里引用图片最常用的写法就是三种相对路径、别名、绝对路径。!-- 相对路径编译期解析资源会被构建处理 -- img src./assets/logo.png altlogo / !-- 别名推荐写法 -- img src/assets/logo.png altlogo / !-- 绝对路径对应 public/images/logo.png不构建处理 -- img src/images/logo.png altlogo /关键区别在动态绑定。如果你写成:srcimgUrl并且imgUrl是通过字符串拼接出来的比如/assets/ name .png那这张图必然出不来。原因在前面讲过编译器在打包时面对的是一个动态字符串它没法静态分析出真实文件是谁于是只能原样输出而浏览器拿到/assets/xxx.png这种地址根本不知道去哪找。正确的动态引入姿势是这样的script setup import logo from /assets/logo.png /script template img :srclogo altlogo / /template先把图片 import 进来作为一个模块对象再绑定给src让编译器在 import 阶段就知道资源位置。后面我会在在线演示里跑这个场景。3.2 style 里的 background别踩别名失效的坑CSS 里引用背景图写法上比模板更讲究。style scoped .box { /* Webpack 项目推荐 ~ 写法 */ background: url(~/assets/bg.png) center center / cover no-repeat; } /style为什么这里要用~而不是直接因为 CSS 文件在被css-loader解析时url()里的路径默认会被当作相对路径处理。直接写/assets/bg.pngcss-loader不知道是什么可能直接报错或者把它解析成一个错误的相对路径。加了~前缀之后css-loader就会明白这是模块路径转交给 Webpack 的模块解析逻辑别名也就能正确生效了。Vite 项目就没这么折腾CSS 里直接写/assets/bg.png就能被正确解析。不过如果你是从老项目迁移过来的遇到style里失效先检查 Vite 的resolve.alias是否配置再看当前版本对 CSS 别名支持是否有异常。还有一点scoped属性只影响样式作用域不影响资源路径解析别在这上面绕弯。3.3 script 里引入图片import、require 与 new URL现在写 Vue 3 Vite 是主流我先说这种组合下的推荐做法。在script setup里引入图片通常有两种方式// 方式一静态 import编译器能解析Vite/Webpack 都支持 import logo from /assets/logo.png // 方式二运行时动态路径Vite 推荐用 new URL function getLogo(name) { return new URL(../assets/${name}.png, import.meta.url).href }new URL(..., import.meta.url)是 Vite 官方推荐的动态资源引用方式它让浏览器在运行时基于import.meta.url当前模块的 URL去解析相对路径这样就不需要预先知道所有文件名。如果你还在用 Vue CLI 或者老版本 Webpack 项目可能会经常见到require写法// Vue CLI 项目可用 const logo require(/assets/logo.png)注意require是 Webpack 提供的模块系统语法Vite 原生不支持。在 Vite 项目里看到require is not defined就是这问题解决办法就是换 import 或 new URL。还有一个更适合批量场景的 Vite 方案是import.meta.glob可以把目录下所有图片一次性映射成对象适合做批量资源统一管理比如一个目录放了几十张图标想全部引入时很省事。不过这个用在你确实需要所有图片的前提下别为了帅而滥用。4. 在线演示一个工程验证所有结论4.1 演示环境怎么搭说再多不如跑一遍。我准备了一个可以直接在线运行的演示工程不用本地装 Node、不用配环境打开浏览器就能操作。打开 StackBlitz 网站点击新建项目选择 Vue 模板默认就是 Vite Vue 3 的组合。项目创建后需要准备一张测试图片随便找一张小 png命名为logo.png把它放到src/assets/目录下。同时在public目录下新建一个images子目录也放一张logo.png内容可以和 assets 里的相同用不同名字也行方便区分即可。最终目录结构类似这样src/ assets/ logo.png App.vue public/ images/ logo.png4.2 演示代码App.vue下面这份App.vue覆盖了五种引用方式复制进在线项目就能直接跑。template div classdemo h2Vue 静态资源路径演示/h2 div classrow p1. 相对路径./assets/logo.png/p img src./assets/logo.png altrelative width80 / /div div classrow p2. 别名/assets/logo.png/p img src/assets/logo.png altalias width80 / /div div classrow p3. 绝对路径/images/logo.png对应 public/images//p img src/images/logo.png altpublic width80 / /div div classrow p4. 动态绑定import 进来的图片/p img :srclogoUrl altdynamic import width80 / /div div classrow p5. style 中通过 引入背景图/p div classbg-box / /div /div /template script setup import logo from /assets/logo.png const logoUrl logo /script style scoped .demo { padding: 24px; } .row { margin-bottom: 16px; } .bg-box { width: 80px; height: 80px; border: 1px solid #ccc; background: url(/assets/logo.png) center center / contain no-repeat; } /style几点说明第 2 种和第 4 种本质上都是走别名只是引用方式不同第 5 种在 Vite 下直接写可以生效如果你把这份代码搬到 Vue CLI 项目里背景图那行建议改成~/assets/logo.png这就是前面章节反复强调的环境差异。4.3 怎么看结果运行起来之后正常情况五张图都能显示。但光能显示还不够建议你打开浏览器开发者工具重点看两件事。第一看Elements面板里img标签编译后的src是什么。当使用相对路径和时你会发现src已经不是代码里写的那个路径而变成了 base64 长串或者带 hash 的文件名取决于图片大小和构建配置。这就是编译期路径换血最直观的证据。而绝对路径那一种src依然是/images/logo.png原样保留。第二可以试试执行一次构建。StackBlitz 的终端里跑npm run build然后看dist目录结构assets里的图片被处理进了dist/assets或类似目录文件带 hashpublic/images/logo.png则会原样出现在dist/images/logo.png。这个对比直接把两种存放姿势的差异摊开了。5. 常见问题与排查技巧5.1 问题一打包后图片全部 404这是被问得最多的一个问题。排查思路按顺序走基本一两分钟内能定位。第一步打开打包产物目录确认图片到底有没有被打包进去。如果dist目录里根本没有这个文件说明路径解析有问题检查代码里的路径是否存在、是否写错优先换成别名再试。如果文件在但页面 404问题大概率出在部署路径配置上。第二步看浏览器 Network 面板找那条 404 请求看它实际请求的 URL 是什么。比如你部署在https://example.com/myapp/而请求地址是https://example.com/images/logo.png那基本可以断定是代码里用了/开头的绝对路径同时项目的publicPath或base没配置子路径。5.2 问题二动态拼接路径不生效模板里写:src/assets/ name .png图片死活不显示控制台报 404 或者直接警告。原因已经重复好几次了编译期无法解析动态字符串资源。解决方案有三个方向。一是用 import 静态引入后再根据条件切换二是用 Vite 的new URL运行时解析三是 Webpack 环境用require拼接完整路径。如果你有一整个目录的图片要动态展示import.meta.globVite或require.contextWebpack是更优雅的方案。5.3 问题三 在 style 里不生效现象是 CSS 里写url(/assets/bg.png)报错或图片 404但同样是写在 template 里却没事。这本质上不是 Vue 的问题而是构建链路上 CSS 解析器对路径的理解不同。Webpack 项目里解决办法就是给加上~前缀写成url(~/assets/bg.png)。Vite 项目里先说确认resolve.alias配置正确再确认 Vite 版本对 CSS 别名的解析行为个别版本可能会对~和处理方式有细微差别直接换个写法试试就能定位。5.4 问题四部署到子目录后全崩项目要部署到https://example.com/myapp/这类子路径结果样式丢失、图片 404。这通常是构建配置里缺了publicPathVue CLI或baseVite。Vue CLI 项目在vue.config.js里设置// vue.config.js module.exports { publicPath: /myapp/ }Vite 项目在vite.config.js里设置// vite.config.js export default defineConfig({ base: /myapp/ })注意配置base或publicPath只会影响构建时生成的资源路径对于代码里手写的/images/logo.png这类绝对路径它是不会自动帮你加前缀的。所以最省心的做法是业务代码里少写站内绝对路径统一用或相对路径让构建工具统一控制资源地址。5.5 问题速查表现象可能原因解决方向打包后图片 404dist 中无此文件代码路径写错或未成功解析改用别名并确认文件存在打包后图片 404dist 中有文件部署在子路径publicPath/base 没配配置publicPath或base动态拼接 src 不生效编译期无法解析运行时字符串import、new URL、require、globstyle 中 失效css-loader 不识别别名Webpack 写~Vite 检查 alias本地正常上线全崩绝对路径 子目录部署少用/开头路径配置 baseVite 项目 require 报错require 是 Webpack 语法改用 import 或 new URL6. 一点实操心得路径问题的核心其实就是一句话先分清资源放哪再决定用哪种写法。我自己的习惯是业务图片一律放src/assetstemplate和script里统一用别名Webpack 项目的style里用~Vite 项目直接用。public目录只放需要原样访问的静态文件而且很少在代码里通过绝对路径引用它。另外还有个小技巧每次打包部署后别急着关终端先看一眼构建产物目录再打开浏览器 Network 检查图片请求。这两步加起来不超过一分钟但能让你在问题刚冒头时就发现不用等到线上用户反馈再手忙脚乱去复盘。路径这东西看着是小事但它几乎会出现在你写的每一个组件里。花半小时把原理和坑位搞清楚后续能省下大量排查时间。希望这篇笔记能给你省下这段弯路。
