Vue3开发完不知道怎么部署上线？看完这篇全流程避坑指南

terry 1小时前阅读数 22 #Vue

先别急着找服务器，首先得搞明白——Vue3项目不管是用vite还是webpack搭的，本质都是单页应用（SPA）？或者你会不会碰巧做了SSR？先分清楚SPA和SSR的部署方向，90%刚入门的人先接触的都是SPA,咱们就从这个最核心的场景讲起。

第一步：先给Vue3项目“打包瘦身”，别把开发环境的累赘带上线

很多同学直接点vscode终端的build就完事儿，结果上线后发现首屏加载要5秒+，这就是打包没做好，不管你是用vite还是Vue CLI（底层webpack）,都得做这几件基础但关键的事。

vite项目的打包优化细节

vite默认打包出来的产物比Vue CLI要小,但还是有提升空间：

开启自动路由和按需导入，如果你用的是Element Plus、Ant Design Vue这种UI库，记得装对应的unplugin插件，比如unplugin-vue-components、unplugin-auto-import，这样不用每次手动import组件和hooks，打包时也只会把你用到的模块塞进去，举个例子，之前用过Element Plus的小白，不装自动导入的话，首屏可能会带整个2MB左右的UI库，装完以后如果只用了Button、Input,这部分体积可能降到几十KB。
配置图片压缩，用vite-plugin-imagemin插件，记得选国内的镜像源安装（因为原插件的依赖在npm上拉可能会超时），压缩级别选8-9就行,再高图片会模糊。
开启gzip或者brotli压缩的前置打包，用vite-plugin-compression插件，生成.gz或者.br文件，后面部署到nginx或者CDN的时候直接用，比服务器实时压缩省CPU资源,速度也更快。
清理console.log和debugger语句，vite默认生产环境不会自动删这些，要在vite.config.ts或者js里加配置，比如用terserOptions的compress选项设置drop_console: true，drop_debugger: true，不然别人打开你的网站控制台，能看到一堆测试用的代码,既不专业也占点小体积。

Vue CLI项目的打包优化细节

虽然现在很多人转vite了，但还是有不少老项目在用Vue CLI升级到Vue3的情况，优化思路和vite差不多,只是插件和配置文件不一样：

按需导入同样重要，比如用babel-plugin-component、babel-plugin-import这种老插件，或者装新版的unplugin全家桶，也支持Vue CLI。
配置splitChunks，把node_modules里的第三方库单独拆出来，比如把Vue、Vue Router、Pinia拆成一个vendors chunk，UI库单独拆一个ui chunk，这样用户第一次加载会慢一点点，但以后更新代码的时候，只要第三方库没换，vendors和ui chunk就不会变，浏览器可以直接用缓存的文件,后续访问速度会快很多。
同样开启gzip/brotli前置压缩，用compression-webpack-plugin插件。
清理console.log和debugger，在vue.config.js里configureWebpack的optimization.minimizer里配置terser-webpack-plugin的选项,和vite的terserOptions类似。

打包完成后，不管是vite的dist目录还是Vue CLI的dist目录，里面就是你要部署的静态文件了——一般就是index.html、css文件夹、js文件夹、assets文件夹这些，先别删，检查一下index.html里的资源路径对不对,很多新手在这里踩第一个坑。

第二步：避坑！dist目录里的静态资源路径怎么配才不会404？

这是最常见的部署问题，没有之一！很多人打包完上传到服务器，打开网站一片空白，F12一看全是404，都是路径惹的祸，资源路径有两种配置方式：绝对路径和相对路径,得根据你的部署场景选。

部署到根域名或者子域名的根目录

比如你的域名是www.example.com，或者子域名是admin.example.com，这种情况不管是vite还是Vue CLI，默认的路径配置就行，但为了保险起见,还是可以确认一下：

vite.config.ts/js里，base设置为'/'（或者直接不写，默认就是'/'）；
vue.config.js里，publicPath设置为'/'（同样默认是'/'，但要注意Vue CLI 4.x和5.x的写法都是publicPath，不要写成3.x的baseUrl了）。

部署到根域名或子域名的子目录

比如你的域名是www.example.com/myapp，或者admin.example.com/backend，这种情况必须改路径配置,不然服务器找不到资源：

vite.config.ts/js里，base设置为'/myapp/'（注意前后都要有斜杠！）；
vue.config.js里，publicPath设置为'/myapp/'（同样前后斜杠）。

改完配置后重新打包，再检查index.html里的link和script标签的href/src属性，是不是都加上了子目录的前缀，比如原本的/assets/logo.png变成了/myapp/assets/logo.png,这样就对了。

还有一种特殊情况：你想把dist目录放到本地的某个文件夹里双击打开index.html就能看，这种情况要把base或者publicPath设置为相对路径，也就是'./'（注意只有前面的点和斜杠，后面不要额外加了），但这种方式一般只适合本地预览测试，不建议部署到服务器，因为有些服务器对相对路径的支持不太好,尤其是做路由跳转的时候。

第三步：静态文件准备好了，选什么服务器部署？

常用的部署方式有三种：nginx部署、云存储+CDN部署、GitHub Pages/Gitee Pages部署，各有各的优缺点,咱们一个一个说。

第一种：nginx部署（最常用，适合所有项目，尤其是有后端接口的）

如果你有自己的云服务器（比如阿里云、腾讯云、华为云的ECS、轻量应用服务器），那nginx是首选，因为它性能好、配置简单、支持反向代理（可以解决前后端分离的跨域问题，不用后端改CORS配置了）。

部署步骤大概是这样的：

先在云服务器上安装nginx，不同的Linux发行版安装命令不一样，比如Ubuntu/Debian用apt install nginx，CentOS用yum install nginx或者dnf install nginx，安装完成后可以用nginx -v检查版本，用systemctl start nginx启动nginx，用systemctl enable nginx设置开机自启。
把本地打包好的dist目录上传到云服务器的某个文件夹里，var/www/myapp，上传工具可以用FileZilla（图形化界面，适合新手），也可以用scp命令（适合会用命令行的人）。
修改nginx的配置文件，配置文件的位置一般是/etc/nginx/nginx.conf，或者/etc/nginx/sites-available/default（Ubuntu/Debian），或者/etc/nginx/conf.d/default.conf（CentOS），修改前记得先备份一下原配置文件，比如cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak,免得改坏了找不到恢复的办法。
配置文件的修改主要分两部分：一是静态资源的路径配置，二是SPA的路由重定向（因为Vue3的路由不管是history模式还是hash模式，都需要服务器配合，不然刷新页面会404）。

举个根域名部署history模式的配置例子（假设静态文件在/var/www/myapp）：

server {
    listen 80;
    server_name www.example.com example.com; # 换成你自己的域名
    root /var/www/myapp; # 换成你上传dist目录的路径，注意这里是dist的父目录？不对，等下，如果是直接把dist里的文件上传到/var/www/myapp，那root就是/var/www/myapp；如果是把整个dist文件夹上传到/var/www，那root就是/var/www/dist，别搞混了，刚才第一步的时候建议把dist里的文件单独拿出来上传，这样更清晰。
    index index.html;
    location / {
        try_files $uri $uri/ /index.html; # 这个是history模式的关键！意思是如果找不到请求的文件或者目录，就返回index.html，让Vue3的前端路由接管。
    }
    # 如果有后端接口，比如接口都以/api开头，就加个反向代理配置，解决跨域问题
    location /api/ {
        proxy_pass http://localhost:3000/; # 换成你后端接口的地址，注意末尾的斜杠！如果后端接口本身没有/api前缀，加斜杠的话会把前端的/api去掉，比如前端请求/api/user，代理后变成http://localhost:3000/user；如果后端接口有/api前缀，就不要加斜杠。
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    # 如果之前打包生成了.gz或者.br文件，加个配置让nginx优先用压缩文件
    gzip_static on;
    brotli_static on; # 如果nginx没装brotli模块，这行可以删掉，或者先装模块。
}

如果是部署到子目录,配置文件要稍微改一下：

server {
    listen 80;
    server_name www.example.com;
    location /myapp/ { # 这里加上子目录的前缀，前后都要有斜杠
        alias /var/www/myapp/; # 注意这里用的是alias不是root！因为root会把location的前缀拼接到路径后面，比如location /myapp/，root /var/www/，那访问www.example.com/myapp/index.html，nginx会找/var/www/myapp/index.html，其实也能用，但alias更适合子目录部署，尤其是try_files的配置。
        index index.html;
        try_files $uri $uri/ /myapp/index.html; # 这里也要加上子目录的前缀
    }
    # 反向代理配置和根域名的一样
}

修改完配置文件后，用nginx -t检查配置文件有没有语法错误，如果显示syntax is ok和test is successful，就用systemctl reload nginx重新加载配置，不用重启nginx,这样不会影响正在访问的用户。

第二种：云存储+CDN部署（性能最好，适合纯静态项目，或者后端接口已经单独部署的）

如果你的项目是纯静态的（比如个人博客、公司官网、产品介绍页），或者后端接口已经单独部署到了其他地方（比如云函数、API网关），那云存储+CDN部署是首选，因为CDN可以把静态文件缓存到离用户最近的节点，首屏加载速度会比只用云服务器快很多，而且云存储的费用比云服务器便宜得多,新手也能操作。

常用的云存储有阿里云OSS、腾讯云COS、七牛云Kodo、又拍云USS，CDN一般和云存储是配套的,直接在云存储控制台开启就行。

部署步骤大概是这样的（以阿里云OSS+CDN为例，其他云平台类似）：

先注册阿里云账号，开通OSS服务，创建一个Bucket（存储空间），Bucket的名称要全局唯一，地域选离你的目标用户最近的，存储类型选标准存储（适合频繁访问的文件），读写权限选公共读（因为是静态文件，要让所有人都能访问）,其他配置默认就行。
把本地打包好的dist目录里的所有文件上传到Bucket里，上传工具可以用OSS控制台的图形化界面，也可以用ossutil命令行工具,或者在vscode里装个阿里云OSS的插件直接上传。
在OSS控制台开启CDN加速，绑定你自己的域名（如果没有域名，可以先试用CDN提供的测试域名，但测试域名有流量限制，不适合正式上线）,然后去域名注册商那里把域名的CNAME解析到CDN提供的CNAME地址上。
同样要配置SPA的路由重定向，不然刷新页面会404，不同的云存储配置方式不一样，阿里云OSS是在Bucket的“数据管理”->“静态页面”里设置，默认首页设置为index.html，默认404页也设置为index.html，然后保存就行；腾讯云COS是在“基础配置”->“静态网站”里设置，索引文档设置为index.html，错误文档设置为index.html，状态码设置为200；七牛云Kodo是在“空间设置”->“静态页面”里设置，首页索引设置为index.html，404跳转设置为/index.html。
如果之前打包生成了.gz或者.br文件，要在云存储和CDN里开启压缩支持，阿里云OSS是在上传文件的时候设置Content-Encoding为gzip或者br，CDN会自动识别；腾讯云COS和七牛云Kodo类似，也是上传时设置,或者用批量工具设置。

第三种：GitHub Pages/Gitee Pages部署（免费，适合个人项目、开源项目演示）

如果你没有云服务器，也不想花钱买云存储和CDN，那GitHub Pages或者Gitee Pages是个不错的选择，完全免费，而且可以绑定自己的域名，不过要注意，GitHub Pages的服务器在国外，国内访问速度可能会慢一些，Gitee Pages的服务器在国内，速度快，但需要实名认证，而且免费版有一些限制（比如单个仓库的大小不能超过1GB，每月流量不能超过10GB）。

部署步骤大概是这样的（以GitHub Pages为例，Gitee Pages类似）：

先把你的Vue3项目推送到GitHub上的一个仓库里，仓库名可以随便取，但如果想用仓库名作为子目录部署（比如username.github.io/myapp），那base或者publicPath要设置为'/myapp/'；如果想用username.github.io作为根域名部署，那仓库名必须是username.github.io，base或者publicPath设置为'/'。
在本地安装gh-pages工具，用npm install gh-pages --save-dev或者yarn add gh-pages -D。

在package.json里加两个脚本命令：

"scripts": {
    "build": "vite build", // 或者vue-cli-service build，根据你的项目来
    "deploy": "gh-pages -d dist" // 这里的dist是打包后的目录名，默认就是dist
}

运行npm run build或者yarn build打包项目，然后运行npm run deploy或者yarn deploy，gh-pages工具会自动把dist目录里的文件推送到GitHub仓库的gh-pages分支上。
去GitHub仓库的“Settings”->“Pages”里，Source选择Deploy from a branch，Branch选择gh-pages，Folder选择/（根目录），然后保存，等几分钟后，你的项目就可以通过username.github.io/myapp或者username.github.io访问了。
同样要配置SPA的路由重定向，不然刷新页面会404，GitHub Pages没有直接的路由重定向设置，我们可以用一个叫spa-github-pages的小工具，在dist目录里生成一个404.html文件，这个文件的作用是当GitHub Pages找不到请求的文件时，返回404.html，然后404.html会自动跳转到index.html，并把原始的URL参数传递过去，具体操作是：在打包完成后，手动把spa-github-pages的404.html文件复制到dist目录里，或者在vite.config.ts/js或者vue.config.js里加个插件,自动复制。

第四步：部署完了怎么测试？有没有什么要注意的？

部署完成后，别急着发朋友圈,先做这几件事测试一下：

打开网站，看看能不能正常显示，F12检查有没有404错误，有没有console.log和debugger语句残留。
测试所有的路由跳转，包括刷新页面、后退、前进,看看会不会404。
测试所有的图片、视频、音频等静态资源,看看能不能正常加载。
如果有后端接口，测试一下接口能不能正常调用,有没有跨域问题。
用手机、平板、不同的浏览器（Chrome、Firefox、Safari、Edge）测试一下,看看有没有兼容性问题。
用Lighthouse或者PageSpeed Insights测试一下网站的性能，看看首屏加载速度、可交互时间等指标有没有达标，如果没达标,再回去优化打包或者调整部署方式。

还有几个要注意的点：

记得给网站加HTTPS证书，现在浏览器都会标记HTTP网站为不安全，HTTPS证书可以免费申请，比如Let's Encrypt，或者云服务器、云存储、CDN平台都会提供免费的证书。
如果是用nginx部署，记得开启防火墙的80和443端口,不然外面的用户访问不了。
如果是用GitHub Pages/Gitee Pages部署，记得定期更新仓库,不然项目内容不会变。
记得备份你的项目代码和静态文件,以免丢失。

就是Vue3 SPA项目部署上线的全流程避坑指南，只要按照这个步骤来，应该不会有什么大问题，如果遇到了其他问题，可以在评论区留言,咱们一起讨论解决。

版权声明

本文仅代表作者观点，不代表Code前端网立场。
本文系作者Code前端网发表，如需转载，请注明页面地址。

上一篇：或者用yarn