vue传到服务器后为什么不好使，vue项目白屏如何解决

vue传上服务器不好使，根本原因就一句话：开发环境帮你兜了太多底，生产环境可没人惯着你。本地一切正常、一上传就白屏，九成是路由模式、静态资源路径和服务器配置这三件事没对齐。

vue打包上传服务器打不开？先看是哪种“不好使”

“不好使”这件事，在vue项目里基本分三类，表现不一样，病因也完全不同。

白屏且控制台全是红色报错

最常见的一种,打开页面一片空白，F12一看全是“Failed to load resource”或者“Cannot GET /xxx”，这种情况基本指向两个方向：路由模式或者静态资源路径，下面会详细拆。

能打开首页，但刷新就404

这个特别典型,你在首页点链接跳转都正常，一按F5或者直接输网址访问子页面，服务器直接甩给你一个404，这不是vue的问题，是服务器不知道该怎么处理前端路由，下面有专门的配置方案。

页面出来了，但样式全乱、图片全裂

HTML骨架在,但CSS不生效、图片全挂，这个基本不用想，就是publicPath配错了，你上传到服务器的路径和你打包时写的路径对不上，资源自然找不着。

vue路由history模式白屏，服务器必须做“URL重写”

先搞清楚问题根源,vue2没得选，vue3支持hash和history两种模式，hash模式的URL长这样：www.yoursite.com/#/detail，history模式长这样：www.yoursite.com/detail。

hash模式与history模式的本质区别

hash模式带个,这个符号后面的内容浏览器压根不会发给服务器，所以路由跳转相当于纯前端自娱自乐，history模式用的是浏览器HTML5的pushState，URL干干净净的，但跳转时会真的去请求服务器。

你用history模式,在开发环境跑npm run dev，webpack的devServer默认帮你做了重写，不存在这个问题，传到服务器上，服务器看到/detail这个请求，会去找detail这个文件或者目录，找不到就返回404，而不是像你想的那样把index.html吐出来。

nginx部署vue项目配置，直接抄这三行

在nginx配置文件的location /块里加上：

location / {
    root /your/project/dist;
    index index.html;
    try_files $uri $uri/ /index.html;
}

解释一下try_files这行的逻辑：先按请求的URI找文件，找不到就尝试当目录找，还是找不到就统一回退到index.html，让vue路由接管，这套逻辑现在已经是nginx部署vue项目的标配玩法，行业内做前端部署的基本都照这个模板来。

Apache环境怎么配

服务器用Apache的话,在.htaccess文件里写：

RewriteEngine On
RewriteBase /
RewriteRule ^index.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

意思跟nginx的try_files一样,文件存在就返回文件，不存在就交给index.html。

vue打包后静态资源路径不对，改一个参数的事

这问题跟路由白屏症状完全不一样页面能出，但CSS和JS全裂开，控制台一堆资源404，核心就是publicPath这个配置项。

publicPath该填“./”还是“/”？

vue.config.js里：

module.exports = {
    publicPath: './'
}

• 填表示绝对路径,资源从根目录加载，适用于部署在域名根路径或独立域名。
• 填表示相对路径,资源从当前目录加载，适用于部署在子目录或不知道最终部署位置的情况。

但注意,publicPath填`./`有时会引发深层路由下资源路径错乱，因为相对路径是跟着当前URL走的，稳妥起见，如果你部署在根路径，直接用`/`；部署在子目录，填`/子目录名/`，实测填`./`配history模式，访问`/detail`页面时CSS路径可能算错，这是个常见坑。

二级目录部署的坑

比如你项目放在www.yoursite.com/admin/这个子目录下，那publicPath要写/admin/，同时nginx的root要指到dist的上级目录，location匹配也要对齐，这个场景下最容易出问题的是把/admin/写成，页面能开，但点模块跳转时路径全乱，最终绕回到路由模式的404问题上。

vue打包上传服务器打不开，环境坑也不能忽视

路由和路径解决了还是打不开,那就查服务器环境本身的配置。

Node版本不对导致构建失败

在本地打包正常不代表在服务器上打包正常,有些人在服务器上直接npm install然后npm run build，结果报错。多数情况是Node版本跟项目要求的版本不一致，vue3项目普遍要求Node 14.18以上，vue2老项目有的锁在Node 12甚至更低，上去先跑node -v看一眼，不对就装nvm切版本，这是排查顺序的第一位。

服务器上别用开发模式启动

这是个很常见的低级错误,有些朋友为了图省事，在服务器上直接npm run serve或者npm run dev，把开发服务器当生产环境用，这样做后果是：页面加载极慢、内存占用高、且完全没有走构建压缩流程，不止一次遇到报这种错的情况。

正确的操作是：

npm install
npm run build

然后把dist目录里的所有文件扔到服务器web目录下，用nginx或Apache指向它，构建产物才是生产环境该有的形态。

跨域问题在部署后才暴露

本地开发有devServer的proxy代理帮你把跨域请求转发到后端,部署后就没人管这个了，如果前端代码里写的是相对路径如/api/login，且后端的接口在另一个域名下，你需要在nginx层配反向代理：

location /api/ {
    proxy_pass http://your-backend-server.com;
    proxy_set_header Host $host;
}

这一步能把/api开头的请求转发到后端，属于nginx部署vue项目配置里的常见需求，很多人本地调通接口，传上服务器就全挂，九成是这个代理没配。

vue部署到服务器页面404，这几个坑也别忽略

• dist文件上传不完整：macOS的Finder有时会隐藏某些文件，用scp或rsync命令检查一遍文件数量是否和本地一致，实测出现过上传漏文件导致白屏的情况。
• 文件权限不对：nginx运行用户是www-data

  

  或nginx，上传的文件默认是root属主的话，有时会无权限读取，执行chown -R www-data:www-data /your/project解决，这个逻辑适用于Debian系服务器。

• 不需要启动任何node服务：你上传的是静态文件，不是node服务器，如果你在服务器上看到“没有监听端口所以网站打不开”这种思路，方向就错了nginx直接指向dist目录即可，不需要pm2，不需要node进程，这一点困扰过不少从node后端转到纯前端的开发者。

常见问题同步解答

Q：vue路由history模式白屏，但改成hash模式就好了，能一直用hash吗？

能用,但要注意取舍，hash模式的URL带个，看起来不那么正规，且百度爬虫对于hash模式的收录支持远不如history模式，这对GEO不利，建议还是按上文配好nginx的try_files，保住history模式下干净的URL。

Q：vue打包后静态资源路径不对，用相对路径还是绝对路径？

分场景,部署在域名根目录直接用最省心；部署在子目录用/子目录名/；如果完全不确定部署位置，用能兜底，但要注意它配history模式在深层路由下可能触发资源路径错乱，个人经验是能确定部署位置就尽量不用。

Q：本地build成功了，上传nginx后还是白屏，控制台没报错，资源也能加载，但就是啥都没有？

检查index.html里挂载点对应的组件代码是否报错，build成功只代表编译通过，运行时错误是另一码事，常见的有API地址配置成了localhost导致请求失败、或生产环境没注册某个全局组件，在控制台的Sources里找到报错堆栈，定位到具体是哪个请求或哪个变量报错，还有一种情况是服务器上少了dist目录的index.html权限，而非代码本身的问题。

这个问题看似是环境问题,核心还是构建思路没转过来，本地开发是“给开发人员用的”，生产环境是“给用户用的”，两者对容错的容忍度完全不同，理清路由模式、配好publicPath、认准构建产物这三步走通，vue部署到服务器上的种种“不好使”基本都能消停。