核心内容摘要
探索无限可能：www.色.com，开启您的精彩视界
Vite开发环境下图片、字体、图标等静态资源加载正常执行vite build打包部署到服务器后大量静态资源返回404 Not Found是前端工程化部署中最常见的问题。
这类问题与资源本身无关、与代码逻辑无关核心原因只有一个Vite开发环境与生产环境的静态资源解析规则不一致、打包配置与服务器部署路径不匹配、资源引用方式违反Vite规范。
本文按照你一贯的排查体系从核心原理、高频错误场景、本地验证、通用排查、服务器配置、避坑规范全流程讲解覆盖图片、字体、CSS背景图、动态资源所有404场景提供可直接复制的配置与代码彻底解决Vite打包后静态资源找不到的问题。
文章目录
核心认知Vite静态资源规则开发正常、打包404的根源
1 Vite两大静态资源目录必须严格区分混用必
4
2 核心铁律记住就不会
4
3 快速判断404是前端问题还是服务器问题
最高频7大场景原因错误示例正确代码全覆盖场景1public 与 src/assets 目录混用最常见占比60%错误表现错误写法正确写法场景2vite.config.js base 配置与部署路径不匹配错误表现核心原因正确配置vite.config.js场景3CSS中相对路径跳级错误打包后路径偏移错误表现错误写法最优写法永远不跑偏场景4JS动态拼接图片路径Vite无法解析必404错误表现错误写法正确写法Vite官方标准import.meta.glob场景5public多级子目录引用时漏写路径目录结构错误写法正确写法场景6字体文件未被Vite正确打包输出路径异常问题表现兜底配置vite.config.js场景7Nginx配置错误服务器找不到dist资源线上专属典型问题根路径部署 Nginx 正确配置子路径部署 Nginx 正确配置重点alias
本地模拟生产vite preview 提前排查404不用上线测试三步操作
通用排查流程三步定位所有场景通用步骤1本地preview验证步骤2前端核心三检查步骤3服务器配置检查
高频避坑点企业开发规范避免99%的404
六、
总结
核心认知Vite静态资源规则开发正常、打包404的根源Vite对静态资源有严格的目录划分与路径规则开发环境由devServer自动兼容错误路径打包后是纯静态文件无任何兼容能力写法不规范 → 开发正常 → 打包404这是90%问题的根源。
1 Vite两大静态资源目录必须严格区分混用必404Vite只有两个合法静态资源目录引用方式、打包行为完全不同混用是第一大死因。
目录位置处理方式适用资源正确引用方式打包后位置项目根目录 /publicVite不编译、不压缩、不重命名原样复制favicon、全局固定图片、不需要哈希的资源以 / 开头的绝对路径直接复制到 dist 根目录src/assetsVite编译、压缩、加哈希、自动处理路径业务图片、组件图片、字体、图标相对路径 或 别名打包到 dist/assets/xxx
2 核心铁律记住就不会404/public下的资源只能写/目录/文件不能加./、../、/、public/src/assets下的资源只能写相对路径或 别名不能写/xxx绝对路径打包后的路径由vite.config.js的base决定必须与服务器部署路径一致Vite不识别动态字符串拼接路径动态资源必须用import.meta.glob导入。
3 快速判断404是前端问题还是服务器问题本地vite preview运行 dist 也404 →前端配置/引用错误本地 preview 正常部署服务器404 →Nginx/服务器路径配置错误。
最高频7大场景原因错误示例正确代码全覆盖以下按出现概率从高到低排序覆盖图片、字体、CSS背景图、动态图片、子路径部署、Nginx配置所有404场景。
场景1public 与 src/assets 目录混用最常见占比60%错误表现开发正常打包后图片/字体404Network请求路径包含public、/public、/assets/xxx不匹配。
错误写法!-- public目录资源错误引用 --imgsrc./public/images/logo.pngimgsrc/public/images/logo.pngimgsrcpublic/images/logo.png!-- src/assets资源错误用绝对路径 --imgsrc/images/avatar.png/* CSS字体错误引用 */font-face{font-family:iconfont;src:url(/fonts/iconfont.ttf);/* 错误 */}正确写法!-- public资源根路径 / 开头 --imgsrc/images/logo.png!-- src/assets资源别名/相对路径 --imgsrc/assets/images/avatar.pngimgsrc./assets/images/bg.png/* 字体正确引用 */font-face{font-family:iconfont;src:url(/assets/fonts/iconfont.ttf)format(truetype);src:url(/assets/fonts/iconfont.woff
format(woff
;font-weight:normal;font-style:normal;}场景2vite.config.js base 配置与部署路径不匹配错误表现所有静态资源统一404不是个别资源是批量404。
核心原因项目部署在域名子路径如https://xxx.com/admin/Vite 默认base: /打包后所有资源都去根目录查找与实际路径不符。
正确配置vite.config.jsimport{defineConfig}fromviteimportvuefromvitejs/plugin-vueimportpathfrompathexportdefaultdefineConfig({// 三种部署场景三选一//
根路径部署 https://xxx.com/base:/,//
子路径部署 https://xxx.com/admin/// base: /admin/,//
CDN部署// base: https://cdn.xxx.com/project/,resolve:{alias:{:path.resolve(__dirname,src)}},build:{assetsDir:assets// 静态资源统一输出目录默认即可},plugins:[vue()]})重点子路径base必须以 / 开头、以 / 结尾。
场景3CSS中相对路径跳级错误打包后路径偏移错误表现组件内CSS背景图、字体开发正常打包后404。
原因CSS打包后会被提取到单独文件相对路径会以CSS最终位置为准不再以组件位置为准。
错误写法/* 组件在 src/views/home/index.vue */ style scoped .box { /* ../../ 跳级容易出错打包后路径偏移 */ background: url(../../assets/images/bg.png); } /style最优写法永远不跑偏style scoped .box { /* 统一用 别名与层级无关 */ background: url(/assets/images/bg.png); background-size: cover; } /style场景4JS动态拼接图片路径Vite无法解析必404错误表现循环图片、根据变量切换图片开发显示打包后路径是原字符串无哈希服务器找不到。
错误写法// 纯字符串拼接Vite打包时无法识别不会打包进distconstimgNametest.pngconsturl/assets/images/${imgName}正确写法Vite官方标准import.meta.glob// 提前静态导入所有图片Vite会全部打包constimgModulesimport.meta.glob(/assets/images/*.png,{eager:true})// 动态获取constgetImgUrl(name){returnimgModules[/assets/images/${name}]?.default||}// 使用constimgUrlgetImgUrl(test.png)public动态资源可直接拼接无需处理// public下的资源直接拼接 / 开头constpublicImg/images/banner/${name}.png场景5public多级子目录引用时漏写路径目录结构public/ images/ banner/ home.png错误写法imgsrc/images/home.png!-- 漏了 banner 层级 --正确写法imgsrc/images/banner/home.png!-- 完整根路径 --场景6字体文件未被Vite正确打包输出路径异常问题表现字体文件ttf/woff/woff2开发正常打包后在dist中找不到或路径错乱。
兜底配置vite.config.js确保Vite识别并打包字体build:{assetsDir:assets,assetsInlineLimit:4096,// 小于4kb内联大于生成文件rollupOptions:{output:{assetFileNames:assets/[ext]/[name]-[hash].[ext]}}}场景7Nginx配置错误服务器找不到dist资源线上专属典型问题root 指向错误没指向 dist子路径部署用了 root应该用 aliastry_files 配置错误导致资源路由被前端路由接管。
根路径部署 Nginx 正确配置server { listen 80; server_name xxx.com; root /usr/share/nginx/html/dist; # 必须指向dist index index.html; location / { try_files $uri $uri/ /index.html; } # 静态资源缓存 location ~* \.(png|jpg|jpeg|gif|ico|ttf|woff2|js|css)$ { expires 30d; add_header Cache-Control public; } }子路径部署 Nginx 正确配置重点aliasserver { listen 80; server_name xxx.com; index index.html; location /admin/ { alias /usr/share/nginx/html/admin/dist/; # 必须alias结尾加/ try_files $uri $uri/ /admin/index.html; } }重点子路径必须用alias不能用root且结尾必须加/。
本地模拟生产vite preview 提前排查404不用上线测试这是Vite官方提供的生产环境模拟器完全复现服务器行为是排查404最有效的工具。
三步操作先打包npmrun build启动预览服务vite preview# 自定义端口vite preview --port8080打开浏览器F12→Network查看是否404预览404 前端问题预览正常服务器404 Nginx/部署路径问题。
通用排查流程三步定位所有场景通用遇到Vite打包资源404按以下顺序排查1分钟定位根源步骤1本地preview验证运行vite preview判断是前端问题还是服务器问题排除干扰项。
步骤2前端核心三检查检查所有资源引用是否混用public与src/assets检查vite.config.js的base是否与部署路径一致检查动态图片是否用import.meta.glob而非字符串拼接。
步骤3服务器配置检查检查Nginx root/alias是否指向dist检查子路径是否用alias结尾是否加/检查服务器dist目录资源是否真实存在。
高频避坑点企业开发规范避免99%的404绝不混用目录public用/xxxassets用/xxx永远不交叉CSS统一用别名禁止使用多层../相对路径动态资源禁止拼接assets动态图必须用import.meta.globbase配置严格匹配子路径部署base必须首尾带/打包必preview上线前必须本地预览禁止直接部署Nginx子路径用alias严禁用root否则路径必错位public资源不加前缀永远不要写./public或public/。
六、
总结Vite打包后图片、字体404本质就是三件事不匹配资源引用方式不匹配 Vite 目录规则base基础路径不匹配 服务器部署路径Nginx配置不匹配 打包后dist目录结构。
只要严格遵循public根路径引用、assets别名引用、base与部署路径一致、动态资源用import.meta.glob、Nginx正确配置这五条规范就能彻底杜绝Vite打包后静态资源404问题实现开发、打包、部署三环境完全一致。
【专栏地址】更多 Vue实战BUG调试、Vite工程化、前端打包部署、网络请求解决方案欢迎订阅我的 CSDN 专栏全栈BUG解决方案