很多开发者问我：“部署 Vue 3 项目是不是一定要买服务器？”
答案是：完全不需要。
Vue 3 项目打包后就是一堆静态文件（HTML + CSS + JS），你只需要一个能托管静态文件的平台就够了。Vercel 是目前对 Vue 生态支持最好、配置最简单的免费平台。本文将带你一步步把 Vue 3 项目部署到 Vercel，并解决 SPA 路由 404 这个最大的坑。
一、前置准备
在开始部署之前，确保你已经有以下准备：
| 准备项 | 说明 |
|---|---|
| Vue 3 项目 | 一个已经开发完成的 Vue 3 + Vite 项目 |
| GitHub 账号 | Vercel 通过 GitHub 仓库自动部署 |
| 代码已推送到 GitHub | 项目需要在一个 GitHub 仓库中 |
还没有 GitHub 账号的话，先去 github.com 注册一个，免费的。
二、Vercel 注册与登录
- 打开 vercel.com
- 点击右上角 "Sign Up"
- 选择 "Continue with GitHub"，用你的 GitHub 账号授权登录
- 授权后，Vercel 会自动创建账号并跳转到 Dashboard
💡 提示：Vercel 免费套餐足够个人项目使用，不需要绑定信用卡。
三、部署 Vue 3 项目（三种方式）
方式一：通过 GitHub 自动部署（最推荐）
这是最常用的方式，配置一次后，每次 git push 都会自动重新部署。
步骤 1：在 Vercel 创建项目
- 登录 Vercel Dashboard，点击 "Add New..." → "Project"
- Vercel 会自动列出你 GitHub 账号下的所有仓库
- 找到你的 Vue 3 项目仓库，点击 "Import"
步骤 2：配置项目设置
Vercel 会自动检测到你的项目使用 Vite + Vue，并自动配置构建命令。你不需要手动修改任何配置。
如果项目根目录不在仓库根目录（比如前端代码在 frontend/ 下），点击 "Configure" 手动设置 Root Directory。
步骤 3：点击 Deploy
点击 "Deploy" 按钮，Vercel 会开始构建和部署。几秒到几分钟后，你会看到部署成功的页面。
部署完成后，Vercel 会分配一个 .vercel.app 域名，例如 https://your-project.vercel.app。这个链接可以直接分享给任何人访问。
方式二：通过 Vercel CLI 部署
适合喜欢命令行的开发者：
# 1. 全局安装 Vercel CLI
npm install -g vercel
# 2. 在项目根目录登录
vercel login
# 3. 部署（首次会引导配置）
vercel
# 4. 部署到生产环境
vercel --prod
方式三：通过 Git 推送自动部署（已配置后）
一旦 Vercel 项目创建完成，后续每次推送代码都会自动触发部署：
git add .
git commit -m "update"
git push
推送后，Vercel 会自动重新构建和部署，无需任何手动操作。
四、核心配置：解决 SPA 路由 404 问题（关键！）
4.1 问题现象
部署成功后，你会发现：
- 访问首页
/✅ 正常 - 点击路由跳转到
/login✅ 正常 - 刷新
/login页面 ❌ 出现 404
原因：Vue Router 使用 history 模式时，浏览器刷新会向服务器请求 /login 这个路径。但服务器上根本没有 login.html 这个文件，只有 index.html，所以返回 404。
4.2 解决方案：配置 vercel.json
在项目根目录创建 vercel.json 文件：
{
"rewrites": [
{
"source": "/(.*)",
"destination": "/index.html"
}
]
}
这个配置的作用：所有无法匹配到静态文件的请求，都返回 index.html，然后由 Vue Router 在前端接管路由。
配置好后，提交代码：
git add vercel.json
git commit -m "fix: add vercel.json for SPA routing"
git push
推送后 Vercel 会自动重新部署，刷新子路由就不会再 404 了。
4.3 进阶配置：完整 vercel.json
如果你的项目还需要配置安全响应头或自定义构建命令，可以参考这个完整版本：
{
"buildCommand": "npm run build",
"outputDirectory": "dist",
"devCommand": "npm run dev",
"installCommand": "npm install",
"framework": "vite",
"rewrites": [
{
"source": "/(.*)",
"destination": "/index.html"
}
],
"headers": [
{
"source": "/(.*)",
"headers": [
{
"key": "X-Content-Type-Options",
"value": "nosniff"
},
{
"key": "X-Frame-Options",
"value": "DENY"
}
]
}
]
}
五、环境变量配置
5.1 为什么需要环境变量
项目中的 API 地址、密钥等敏感信息，不应该硬编码在代码里。不同环境（开发/生产）的配置也不同。
5.2 Vite 环境变量规则
Vite 中，只有以 VITE_ 开头的变量才会暴露给前端：
// .env.production
VITE_API_URL=https://your-backend.onrender.com/api
VITE_SENTRY_DSN=xxx
// 代码中访问
const apiUrl = import.meta.env.VITE_API_URL // ✅ 可访问
const secret = import.meta.env.SECRET_KEY // ❌ undefined（未暴露）
5.3 在 Vercel 配置环境变量
非常重要：Vite 的环境变量在构建时就被替换到代码中了。所以必须在 Vercel 构建之前配置好环境变量。
操作步骤：
- 进入 Vercel 项目页面 → Settings → Environment Variables
- 添加变量（Key + Value）
- 选择环境（Production / Preview / Development）
- 点击 Save
- 重新触发部署（因为变量是在构建时注入的，保存后需要重新构建才会生效）
# 或者在命令行添加
vercel env add VITE_API_URL production
⚠️ 常见错误：很多人配置完环境变量后忘记重新部署，导致变量不生效。记住：配置变量 → 重新部署，两步缺一不可。
六、绑定自定义域名（可选）
Vercel 提供的 .vercel.app 域名可以直接使用，但如果想绑定自己的域名：
- 在 Vercel 项目 → Settings → Domains
- 输入你的域名（如
zswgxl.xyz） - 按照提示在域名注册商（如阿里云）添加 DNS 解析记录
- 等待 DNS 生效（几分钟到几小时）
- Vercel 会自动签发 SSL 证书
七、常见问题与踩坑
7.1 部署后页面空白
原因：静态资源路径不对。
解决方案：在 vite.config.js 中检查 base 配置：
export default defineConfig({
base: '/', // 部署到根路径时用 '/'
// 如果部署到子路径，比如 https://xxx.github.io/my-app/
// base: '/my-app/'
})
7.2 刷新页面 404
参考上面第四节，配置 vercel.json 的 rewrites 规则。
7.3 API 请求跨域
前端请求后端 API 时出现跨域错误。解决方案：
- 在后端配置 CORS（推荐）
- 或使用 Vercel 的 Rewrites 代理转发
{
"rewrites": [
{
"source": "/api/(.*)",
"destination": "https://your-backend.onrender.com/api/$1"
}
]
}
7.4 环境变量不生效
检查三点：
- 变量是否以
VITE_开头 - 是否在 Vercel Dashboard 中配置了
- 配置后是否重新触发了部署
八、总结
Vercel 部署 Vue 3 项目的核心流程：
- 代码推送到 GitHub
- Vercel 导入仓库 → 自动识别 Vite + Vue
- 点击 Deploy → 获得
.vercel.app域名 - 配置
vercel.json解决 SPA 路由 404 - 配置环境变量 → 重新部署
整个过程完全免费，不需要购买任何服务器。部署完成后，每次 git push 都会自动更新线上版本，非常方便。
