Vercel部署完全指南：从踩坑到成功的实战经验分享

前言

Vercel 是一个非常流行的前端部署平台，它支持静态站点、SSR 应用和各种前端框架（Vue、React、Next.js 等）的快速上线。很多人都被它的"一键部署"吸引，但实际操作中，新手很容易踩坑：认证错误、项目配置不当、构建失败......

这篇文章将从 Vercel 是什么 开始讲起，然后结合我的真实踩坑经历，给你一个 从零到上线 的 Vue.js 部署流程，并总结常见问题及解决方案。

1. Vercel 是什么？

Vercel 是一家专注于前端应用部署的云平台，它的特点是：

免运维：不用自己买服务器、配置 Nginx、管理 SSL。
自动化构建：支持从 GitHub、GitLab、Bitbucket 自动拉取代码并构建。
全球 CDN：部署完成后，项目会自动分发到全球边缘节点，访问速度快。
免费额度：个人开发者免费用，足够日常项目使用。

简单来说，Vercel 就是一个帮你"写好前端，点一下就上线"的平台。

2. 部署前的准备工作

在部署前，你需要准备好：

Vercel 账号（推荐用 GitHub 登录，方便项目同步）
Node.js ≥ 16.x
一个 Vue.js 项目（这里以 Vue 3 + Vite 为例）
Vercel CLI 工具（用于本地部署调试）

安装 CLI：

bash 复制代码

npm install -g vercel
# 或者临时使用（推荐）
npx vercel --version

3. Vue 项目部署到 Vercel 的流程

步骤 1：项目构建配置

确保 package.json 中的构建命令正确：

js 复制代码

{
  "scripts": {
    "build": "vite build",
    "preview": "vite preview"
  }
}

如果需要自定义部署参数，可以添加 vercel.json：

js 复制代码

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite"
}

步骤 2：登录 Vercel

bash 复制代码

npx vercel login

选择登录方式（建议 GitHub），按照提示完成授权。

步骤 3：首次部署（关键！）

首次部署时，很多人会误选 Link to existing project? → Yes，导致出现 "Project not found" 错误。

正确的做法：

js 复制代码

npx vercel --prod

部署时的选项：

js 复制代码

? Set up and deploy? → Yes
? Which scope? → 选择你的账号
? Link to existing project? → No  ✅（首次部署必须选 No）
? What's your project's name? → my-vue-blog
? In which directory is your code located? → ./

步骤 4：等待构建完成

成功后会看到：

js 复制代码

✅ Production: https://my-vue-blog.vercel.app

访问链接即可看到你部署好的 Vue 项目。

4. 部署常见问题与解决方案

1. "Account not found"

原因：

没有 Vercel 账号
登录方式选择错误
浏览器授权失败

解决：

js 复制代码

vercel logout
vercel login

重新选择 GitHub 登录。

2. "Project not found"（首次部署常见）

原因：首次部署时误选了"Link to existing project → Yes"。

解决：重新执行部署，并选择 No。

3. Token 验证失败

javascript 复制代码

Error: Invalid token

解决：

bash 复制代码

vercel logout
vercel login

4. 构建失败

本地先测试构建：

arduino 复制代码

npm run build

清理依赖并重新安装：

bash 复制代码

rm -rf node_modules package-lock.json
npm install

查看构建日志：

xml 复制代码

vercel logs <部署URL>

5. Vue Router 刷新 404

Vercel 默认是静态文件托管，刷新 SPA 页面会找不到路径，需要添加重写规则：

json 复制代码

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

5. 部署最佳实践

1. 项目结构

csharp 复制代码

project/
├── src/
├── public/
├── dist/           # 构建产物
├── package.json
├── vite.config.js
├── vercel.json
└── .vercelignore   # 忽略文件

2. 环境变量

bash 复制代码

# CLI 设置
vercel env add VITE_API_URL production

或者在 Vercel Dashboard 配置。

3. 自定义域名

csharp 复制代码

vercel domains add yourdomain.com
vercel alias set my-vue-blog.vercel.app yourdomain.com

6. 我的部署案例

项目类型：Vue 3 + Vite + TypeScript
构建时间：4.94 秒
部署时间：18 秒
访问地址 ：manong-blog.vercel.app

7. 总结

Vercel 的确是一个非常适合前端开发者的部署平台，但要注意几个核心点：

首次部署一定要选择创建新项目（No），不要链接不存在的项目。
本地先确保构建成功，避免部署时出错。
善用 vercel.json 配置，解决路由和资源路径问题。
CLI + Dashboard 配合，部署更高效。

按照这个流程，你的 Vue 项目基本可以一次性部署成功。

如果你也在部署过程中遇到问题，欢迎评论区交流！