接手过一个跑了三年的Vue2项目，技术栈是Vue CLI + Webpack，代码量不算小，图片资源更是散落各处。最近决定往Vue3 + Vite迁移，本以为换掉构建工具只是配置改改的事，结果刚把项目跑起来就开始怀疑人生：npm run dev一切正常，npm run build之后传到服务器，首页图片全挂，favicon也丢了，控制台里一串404。排查到最后发现，根子全出在public目录和路径配置上——Webpack和Vite对“public目录里的文件怎么引用”这件事的理解，压根儿不是一个逻辑。
这篇文章就把这次迁移踩过的坑拆开揉碎聊一聊。不管你是准备从Vue2迁到Vue3，还是新项目刚上手Vite，只要涉及public目录、静态资源、子路径部署，这几点必须搞清楚。写这篇的定位很明确：不扯原理大山，全部来自实际项目里的配置和实践，适合正在迁移老项目、或者部署时被资源路径折磨的团队参考。
1. Webpack的public目录是“拷贝”，Vite的public目录是“服务器根路径映射”
1.1 两个工具对public目录的底层理解完全不同
在Webpack项目里，public目录的本质是“复制粘贴”。你用Vue CLI脚手架新建项目，public/目录里的文件会被原样复制到dist/的根目录，不经过任何loader处理，不参与打包，也不会有hash后缀。这个逻辑很直观，像个搬运工，把public文件夹整体搬到dist文件夹里就完事。
Vite的public目录看起来也是这个作用，官方文档写得也很像——public目录下的文件会被原样复制到构建输出目录的根目录。但实际使用时的行为差异很大：在Vite项目中，public目录更像是“服务器根路径的映射”。开发环境里，public/logo.png直接等于http://localhost:5173/logo.png；构建之后，public/logo.png等于部署服务器根路径下的/logo.png。这一个细微的思维差异，后面会引发一串连锁问题。
我之前习惯性地在Webpack项目里这么写：
<!-- Vue2 + Webpack 项目里的老写法 --> <img src="/img/logo.png" />然后public/img/logo.png放在那里，一切安好。同样一行代码放进Vite项目，本地开发也没问题，但等你把base一改、部署到子路径下，这行代码就变成指向服务器根路径的“死链”。
1.2 能不能被模块系统处理，是第一个分水岭
Webpack项目中，public目录下的文件有一个重要特点：不能通过import引入。你在组件里写import logo from '@/public/img/logo.png'，Webpack会试图把它当模块处理，要么走file-loader要么走url-loader，最后生成的文件会被重新命名、加上hash，路径也会变。想要原样引用，就必须用/img/logo.png这种绝对路径，或者动态拼接process.env.BASE_URL。
Vite这边也差不多，public目录下的文件同样不能通过import方式引入。如果你试图import logo from '/public/img/logo.png'，Vite会直接报错或者把它当成普通静态资源处理，行为非常别扭。Vite的推荐做法是用根路径引用/img/logo.png，或者用new URL('./img/logo.png', import.meta.url)这种方式把资源交给构建器处理。
但这里有个关键区别需要重点划一下：
| 操作场景 | Webpack项目 | Vite项目 |
|---|---|---|
| public下文件的引用方式 | 绝对路径/img/logo.png | 绝对路径/img/logo.png |
| 能否import public下的文件 | 不能 | 不能 |
| 绝对路径会跟随publicPath/base变化吗 | index.html中会，JS中不一定 | 不会自动加base前缀，原样保留 |
| 建议放public的文件 | favicon、robots.txt、外部配置文件 | 同上 |
| 代码中资源走import相对路径 | 会加hash并自动处理 | 会加hash并自动处理 |
最坑的就是标红的那一行：Vite构建时，代码里手写的/xxx.png这种绝对路径，不会被加上base前缀。Webpack中你还能靠publicPath在某些场景下兜底，Vite直接不惯着你，写在哪就是哪。
2. 迁移时最先炸掉的三个资源：图片、favicon、CSS背景图
2.1 图片资源：少用“/”开头的绝对路径，能import就import
如果你只是从Vue2迁移到Vue3，且构建工具还是Webpack，那路径可能不会出大问题。但既然换成了Vite，第一个要改的习惯就是把“资源全放public里、路径直接写死”的思路抛弃掉。
我的建议很简单：**项目内使用的图片、图标、小体积静态资源，尽量放在src/assets目录下，通过import或相对路径引入，交给Vite做打包处理。**这样做的好处是Vite会给文件加hash，解决缓存问题，同时会依据base自动生成正确的路径前缀，你根本不用关心最后部署到哪。
只有这几种文件建议放public：
- favicon、robots.txt、manifest.json这类入口文件
- 需要被外部系统直接通过固定URL访问的文件，比如第三方对接的xml、txt、html页面
- 体积大且不频繁变动的二进制文件，比如某些部署后还会手工替换的包
打个比方，public目录就像你家门口的公共邮箱，谁都能用固定地址看到里面的东西；src/assets里打包的文件就像快递柜里的包裹，地址是动态分配的，外人没法预知。能用快递柜的东西，就别堆在公共邮箱门口。
2.2 favicon：index.html里别再用死路径
favicon是迁移时命中率最高的404资源。Vue2的Vue CLI项目里，你大概率见过这种写法：
<link rel="icon" type="image/png" href="<%= BASE_URL %>favicon.ico">Vue CLI通过EJS模板，把BASE_URL替换成publicPath的值。如果publicPath是/，那结果就是/favicon.ico；如果部署到子路径/admin/，这个值会自动变成/admin/favicon.ico。
换成Vite之后，很多人直接改成：
<link rel="icon" type="image/png" href="/favicon.ico">本地开发没事，因为dev server根路径就是项目根；但一旦base设置为/admin/，构建后的HTML里还是这个/favicon.ico，浏览器会请求http://你的域名/favicon.ico，404是必然的。
Vite其实提供了和Webpack的BASE_URL位置相近的用法，就是HTML环境变量替换。在index.html里可以这么写：
<link rel="icon" type="image/png" href="%BASE_URL%favicon.ico">%BASE_URL%会在构建时被替换成base配置的值（注意Vite的base值会保证以斜杠开头和结尾），这样不管是开发还是子路径部署，favicon都能正确加载。
2.3 CSS背景图：绝对路径和相对路径待遇不同
CSS里引用背景图也是重灾区。许多人喜欢在全局CSS里写：
.login-page { background-image: url('/img/login-bg.png'); }在Webpack+Vue CLI里，这个路径在构建时会被尝试解析成模块，通常也能正确打包。但Vite对CSS的处理有一个我很早就发现的行为差异：以/开头的绝对路径，在构建时不会自动加base前缀；而相对路径会被Vite当作静态资源处理，构建后加上hash和base前缀。
我实测过Vite 4的一个项目，CSS里写url(/fonts/iconfont.woff2)，构建后的CSS文件里原样保留了这个绝对路径，改了base也纹丝不动；改成url(../fonts/iconfont.woff2)之后，构建产物里文件名带了hash，路径也自动加上了base前缀和资源目录。
所以，CSS里面引用资源，尽量用相对路径。这里说的相对路径是相对于CSS文件所在位置。如果你非要写绝对路径，就得做好“永远挂在服务器根路径下”的心理准备。
3. base配置：Webpack的publicPath到Vite的base，改一处动全身
3.1 怎么改base才不影响本地开发
Vite中控制所有资源路径前缀的核心配置是server.base，也就是base。webpack那边对应的叫output.publicPath，在Vue CLI里则是publicPath。两者职责接近：给构建出的静态资源URL加统一前缀。
默认情况下，Vite的base是/，所以本地开发完全不需要管它。但你要把项目部署到http://example.com/admin/这种子路径下，就得改：
// vite.config.js import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ base: '/admin/', // 注意首尾都要有斜杠 plugins: [vue()] })改完base之后，构建产物的JS、CSS、图片等资源引用都会带上/admin/前缀。但你很快会发现，光是改这个还不够——public目录里的资源引用、路由的history配置、nginx的转发规则，每一环都得跟上，这个下面实操章节细说。
很多人在开发环境也会被base干扰，明明base: '/admin/'是给生产环境用的，本地一跑起来整个项目乱了。这里有个常见的经验做法是区分环境：
export default defineConfig(({ mode }) => { const isProd = mode === 'production' return { base: isProd ? '/admin/' : '/', } })开发时保持根路径，构建时使用子路径，两不耽误。
3.2 三个“base”必须分开记，别混淆
迁移过程中我见过太多人把静态资源的base、路由的base、接口请求的baseURL混为一谈，结果改了vite.config.js里的base，发现接口也变了、路由也乱了，最后全盘推翻重来。这里必须用一张表把三者的定位钉死：
| 名称 | 所在位置 | 控制范围 | 典型值 |
|---|---|---|---|
| 静态资源base | vite.config.js中的base | HTML、JS、CSS中由构建器生成的资源路径前缀 | /admin/ |
| 路由base | createWebHistory()的第一个参数 | 前端路由的history模式根路径 | /admin/ |
| 接口baseURL | axios等请求库的baseURL | 所有HTTP请求的URL前缀 | '/api'或完整域名 |
路由base的作用是告诉Vue Router“当前应用挂在哪个路径下”。你部署在/admin/，路由的history模式就得用/admin/作为根基，否则刷新页面时路由会直接404。而接口baseURL纯粹是请求层的拼接，和静态资源、路由没有直接关系。
有过一次惨痛经历：我同事把vite.config.js里base配成了/api，以为这样前端请求/api/user就顺理成章拿到数据了。结果构建后页面上的JS和CSS全变成了/api/assets/xxx.js，页面整个白屏。改静态资源base的时候一定要意识到，它会影响所有构建产物的加载路径，不是单纯的“请求前缀”，别拿它当代理用。
3.3 别把public目录当成后端返回路径的替代品
还有一种常见误区是，把后端需要动态读取的配置文件塞进public目录里，比如public/config.json，然后前端代码用fetch('/config.json')去加载。开发时没问题，但一旦部署到子路径，这个请求就会打到域名根路径上去，404没跑。
如果只是需要一份配置文件，正确的做法是在代码里拼接import.meta.env.BASE_URL：
const config = await fetch(`${import.meta.env.BASE_URL}config.json`).then(res => res.json())import.meta.env.BASE_URL在开发环境默认是/，构建时取的是vite.config.js里base的值。Vite官方保证这个值始终以斜杠开头和结尾，拼接的时候不用顾虑多斜杠少斜杠的问题。
另外提一句，process.env.VUE_APP_XXX在Vue3 + Vite里也别用了，Vite自定义环境变量需要以VITE_开头，访问方式改用import.meta.env.VITE_XXX。BASE_URL本身也是挂在import.meta.env下的，算是迁移时最不起眼但最容易报错的差异点之一。
4. 实操案例：把Vue2后台管理系统迁移到Vue3，部署到/admin/子路径
4.1 迁移前先理清项目现状
用我实际迁移的一个后台系统来说，它原先是Vue2 + Vue CLI 4，登录后进入一个控制台，图片资源一部分放在public/img/下，一部分放在src/assets下。打包部署的路径打算改成/admin/，因为服务器上这个域名下面还要跑另外一个项目。
迁移前我先把现状盘了一遍，核心文件有这些：
public/ ├── config.json ├── favicon.ico └── img/ ├── logo.png └── login-bg.png src/ ├── assets/ │ ├── icons/ │ └── avatar.png ├── router/index.js ├── views/ └── main.js之前Webpack项目里，路由用的是createWebHistory()不传参数，图片到处都是/img/logo.png这种死路径。要平滑迁移到Vite并部署到子路径，下面几步缺一不可。
4.2 six步迁移配置法（可直接套用）
第一步：vite.config.js里配置base和alias
先安装@vitejs/plugin-vue，然后把基础配置写好。这里除了base，还要把@别名配好，因为Vue CLI默认自带@指向src，Vite可不会自动给你加。
import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import path from 'path' export default defineConfig(() => { const isProd = process.env.NODE_ENV === 'production' return { base: isProd ? '/admin/' : '/', plugins: [vue()], resolve: { alias: { '@': path.resolve(__dirname, 'src') } } } })第二步：路由base跟着改
Vue Router 4的createWebHistory接收一个可选的base参数。最省心的写法是直接传入import.meta.env.BASE_URL，这样它会自动同步vite.config.js里的base设置：
import { createRouter, createWebHistory } from 'vue-router' const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes })这一步不配的话，本地开发看不出问题，一上线刷新/admin/login这种二级路由页面，nginx会直接返回404，因为服务器不知道应该把请求回退到index.html。
第三步：index.html里的资源引用换成%BASE_URL%
回到favicon的例子：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <link rel="icon" type="image/png" href="%BASE_URL%favicon.ico" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>后台管理系统</title> </head> <body> <div id="app"></div> <script type="module" src="/src/main.js"></script> </body> </html>第四步：组件和CSS里的死路径清理
项目里搜一遍/img/、/assets/这种“根绝对路径”，能改成import的就改掉。组件里动态拼接路径的，统一用import.meta.env.BASE_URL拼接：
const logoUrl = `${import.meta.env.BASE_URL}img/logo.png`CSS里的背景图改成相对路径，或者挪到src/assets里用import引入。
第五步：接口请求baseURL单独设置
这一步不归Vite管，但很容易被连带误改。我的建议是axios实例单独维护，部署环境用VITE_API_BASE这个环境变量控制：
# .env.production VITE_API_BASE=/admin/apiconst request = axios.create({ baseURL: import.meta.env.VITE_API_BASE || '/api' })注意，这里VITE_API_BASE是给代理或后端网关用的，跟Vite的base完全无关，不要写进vite.config.js。
第六步：nginx配置配合
这是最后一块拼图。子路径部署时，nginx要保证两点：一是/admin/下的请求能精准转发到前端；二是history模式下没有匹配到物理文件的请求全部回退到index.html。配置示例：
location /admin/ { alias /var/www/admin/; try_files $uri $uri/ /admin/index.html; }这里用alias而不是root，是因为root会把/admin/拼接到磁盘路径后面，很容易出现/var/www/admin/admin/index.html这种多一层目录的问题。用alias能直接映射到部署目录。
4.3 迁移时最容易翻车的几个配置点
在实际操作里，我发现很多人改完vite.config.js就急着打包，结果往往在几个不起眼的地方翻车。第一个是base值首尾斜杠，写成'admin'直接不行，Vite要求要么以/开头结尾的绝对路径，要么是'./'这种相对路径；第二个是路由的history mode，Vue2迁移过来时容易把mode: 'history'这套老写法照搬进Vue Router 4，然后报错，其实Vue Router 4里直接用createWebHistory就行；第三个是nginx缓存，改了静态资源后浏览器还是旧的CSS和JS，排查时先做一次强制刷新，或者让前端资源带hash。
这里还要提醒一个困扰过我的点：部署到子路径后，vite preview本地预览的路径和服务器不一定一致。vite preview默认还是从/去访问，如果你base配了/admin/，构建产物用vite preview预览时，直接访问http://localhost:4173/反而可能404，得访问http://localhost:4173/admin/才行。第一次遇到时以为构建有问题，排查了半天，其实只是预览命令对base的处理方式不同。
5. 常见路径问题速查表与排查思路
5.1 一张表对清楚症状和处理办法
迁移过程中我把自己踩过的坑整理成了一张速查表，基本覆盖了public目录和路径配置的绝大多数问题：
| 问题症状 | 根本原因 | 解决办法 |
|---|---|---|
| 本地正常，打包后图片全挂 | 代码里写死了/img/xxx.png绝对路径 | 改成import方式，或用import.meta.env.BASE_URL拼接 |
| 部署到子路径后favicon丢失 | index.html里href="/favicon.ico"没有跟随base | 改用%BASE_URL%favicon.ico |
| 刷新页面404 | 路由history模式没有传入base | createWebHistory(import.meta.env.BASE_URL) |
| CSS背景图404 | CSS里用了url(/images/xx.png)绝对路径 | 改成相对路径或移入src/assets |
| public下配置文件请求404 | fetch('/config.json')不支持子路径 | 用fetch(import.meta.env.BASE_URL + 'config.json') |
process.env直接报错 | Vue2迁移代码没有改完 | 替换为import.meta.env对应写法 |
@别名找不到模块 | Vite没有自动配置@指向src | resolve.alias手动配置 |
vite preview打开白屏 | base为/admin/，但预览时直接访问/ | 访问/admin/地址，或临时改base为/ |
这些坑不是一个个孤立的事件，它们背后就是同一个逻辑：**Vite对绝对路径的“容忍度”比Webpack低得多，构建器能帮你的地方都预设了你走模块系统。**你只要写死一个斜杠开头的手工路径，Vite默认它指向服务器根路径，不会做任何加法。
5.2 一条高效的排查路径
如果你现在项目里已经有资源404，按这个顺序排查最快：
第一步，打开浏览器DevTools的Network面板，看那个失败请求的URL是什么。如果URL里看不到/admin/（或你设置的base），说明这是手写的绝对路径，Vite没管它，直奔代码里搜索对应字符串。
第二步，看URL里有没有hash。如果文件名带了?hash之类的内容，说明资源走了构件器，那么问题大概率出在nginx没把文件配好，比如静态资源目录指向不对。如果URL里没有hash，大概率是public目录下手工引用的东西，检查文件在不在dist根目录下。
第三步，检查index.html开头部分，看<link rel="stylesheet">引用的CSS路径前缀对不对。这里是Vite正确性的第一道门，如果这里都错，后面JS、图片全免谈。
第四步，有nginx先看nginx配置，没有就本地起一个vite preview配合子路径访问，排除服务端干扰。
第五步，翻构建日志。vite build输出的文件列表里能看到public下文件是否有被拷贝，也有助于确认是否删错文件。
5.3 写路径的三个长期习惯
最后分享三个我实践下来能大幅减少路径问题的习惯。第一个，代码里所有“以斜杠开头的URL字符串”都要引起警惕，不管是img的src、link的href、fetch的url还是a标签的to属性，写之前问自己一句：这个路径要不要跟随base？如果答案是要，就别写死。
第二个，能用import/import.meta.url方式，就不要手动拼字符串。Vite原生支持new URL('./xxx.png', import.meta.url)，它会自动帮你把URL转成正确的资源地址。尤其是动态拼接图片URL的场景，这个写法比${import.meta.env.BASE_URL}images/${name}.png可靠得多。
第三个，创建一个工具函数统一处理资源路径。项目里如果实在避免不了拼接public目录下的资源，建议抽一个函数：
// src/utils/asset.js export function asset(url) { return new URL(`../public/${url}`, import.meta.url).href }或者简单一点：
export function asset(url) { return `${import.meta.env.BASE_URL}${url.replace(/^\//, '')}` }这样至少全项目的资源路径处理逻辑是统一的，后期迁移、改部署路径时不用满世界找散落的斜杠字符串。
从Vue2的Webpack到Vue3的Vite，这项迁移真正颠覆的不是语法，而是你对“资源路径”这件事的心智模型。Webpack给开发者留了很多“手工拼绝对路径”的空间，Vite则坚定地把一切交给模块系统。我在多次迁移过程中最深的一点体会就是：当你在Vite项目里想手写一个以斜杠开头的URL时，一定要停下来多问一句，这个路径在子路径部署下还能不能成立。把这个习惯养成了，public目录、base、路由三者的协同关系自然就顺了。
