Vercel部署全攻略:从GitHub到上线,10分钟让你的前端项目免费拥有自己的域名

你: 熬夜做了个酷炫的前端项目
朋友: 能给我看看吗?
你: 呃...你先在本地clone下来,然后npm install,再npm run dev...
朋友: 算了算了 (转身离开)

✅ 一个GitHub账号
✅ 一个前端项目(React/Vue/Next.js等)
✅ 项目代码已推送到GitHub仓库
✅ (可选)一个自己的域名

授权范围:
✅ 读取仓库列表
✅ 读取仓库代码
✅ 添加部署状态(在PR中显示部署预览)

❌ 仓库是私有的,但未授权Vercel访问
   → 解决: 去GitHub Settings重新授权
 
❌ 仓库属于Organization,需要额外授权
   → 解决: 在Organization设置中授权Vercel
 
❌ 仓库名称被搜索框过滤了
   → 解决: 清空搜索框或手动输入仓库名

默认: 你的GitHub仓库名
用途: 决定默认的vercel域名 (如 my-app.vercel.app)
 
建议: 使用简洁、有意义的名称

默认: ./
用途: 如果你的前端代码在子目录(如monorepo),在这里指定
 
示例:
monorepo-project/
├── packages/
│   ├── frontend/   ← 前端代码在这里
│   └── backend/
└── package.json
 
配置: ./packages/frontend

# Next.js
next build
 
# Create React App
npm run build
 
# Vite (React/Vue)
vite build
# 或
npm run build
 
# Vue CLI
vue-cli-service build
 
# 自定义脚本
npm run build:prod

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",    ← 这就是构建命令
    "preview": "vite preview"
  }
}

npm run build

Name: VITE_API_URL
Value: https://api.example.com
 
Name: VITE_APP_TITLE
Value: My Awesome App

1. Cloning repository       ← 从GitHub克隆代码
2. Analyzing dependencies    ← 分析依赖关系
3. Installing dependencies   ← 安装npm包 (最耗时)
4. Building application      ← 执行构建命令
5. Uploading build output    ← 上传到CDN
6. Deploying to production   ← 部署完成!

https://your-project-name.vercel.app

原因: 构建命令执行失败
解决:
1. 检查package.json中的build脚本是否正确
2. 在本地运行`npm run build`看是否有错误
3. 检查是否缺少必要的环境变量

原因: 缺少依赖包
解决:
1. 确认依赖包在package.json的dependencies中(不是devDependencies)
2. 本地删除node_modules重新安装测试
3. 检查package-lock.json是否提交到GitHub

原因: 构建超时(免费版限制45分钟)
解决:
1. 优化构建配置,减少不必要的依赖
2. 使用.vercelignore排除不需要的文件
3. 考虑升级到Pro版(300分钟限制)

原因: Node.js内存不足
解决:
在项目根目录创建vercel.json:
{
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/node",
      "config": {
        "maxLambdaSize": "50mb"
      }
    }
  ]
}

工作流程:
你在本地修改代码
    ↓
git commit & git push
    ↓
Vercel检测到GitHub仓库更新
    ↓
自动触发新的部署
    ↓
几分钟后新版本自动上线!

✅ 你已经拥有一个域名(如从腾讯云、阿里云、GoDaddy购买)
✅ 能够访问域名的DNS管理后台

示例: example.com
 
需要配置:
A记录: example.com → 76.76.21.21

示例: blog.example.com 或 www.example.com
 
需要配置:
CNAME记录: blog → cname.vercel-dns.com

记录类型: CNAME
主机记录: blog    (如果是www则填www)
记录值: 复制Vercel中添加的域名中的CNAME对应的Value指
TTL: 600 (10分钟,可以默认)

记录类型: A
主机记录: @      (@ 表示根域名)
记录值: 76.76.21.21  (Vercel提供的IP地址)
TTL: 600

# 检查CNAME记录
nslookup blog.example.com
 
# 或使用dig命令
dig blog.example.com
 
# 应该看到返回:
# blog.example.com.   IN  CNAME   cname.vercel-dns.com.

https://blog.example.com

1. 找到你想回退到的版本
2. 点击右侧的 ⋯ 按钮
3. 选择"Promote to Production"
4. 几秒钟后,旧版本重新上线!

访问首页: https://my-app.vercel.app  ✅ 正常
访问子页面: https://my-app.vercel.app/about  ❌ 404

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

Console错误:
GET https://my-app.vercel.app/assets/logo.png 404

export default {
  base: '/',  // 确保base是 '/' 而不是相对路径
  build: {
    outDir: 'dist',
  }
}

{
  "homepage": "https://my-app.vercel.app"
}

console.log(import.meta.env.VITE_API_URL)
// 输出: undefined

❌ 环境变量名称错误(缺少前缀)
   → Vite: 必须以VITE_开头
   → CRA: 必须以REACT_APP_开头
   → Next.js: 必须以NEXT_PUBLIC_开头(客户端使用)
 
❌ 环境变量未在Vercel中配置
   → 进入Settings → Environment Variables添加
 
❌ 配置后未重新部署
   → 修改环境变量后需要触发新部署才能生效

.git
*.md
.vscode
.idea
tests
docs

// vercel.json
{
  "github": {
    "silent": true
  },
  "build": {
    "env": {
      "NODE_OPTIONS": "--max_old_space_size=4096"
    }
  }
}

{
  "builds": [
    { "src": "package.json", "use": "@vercel/static-build", "config": { "parallel": 3 } }
  ]
}

1. 检查DNS是否生效 (nslookup your-domain.com)
2. 在Vercel中删除域名,重新添加
3. 等待几分钟让Let's Encrypt重新签发证书
4. 清除浏览器缓存和SSL状态

npm i -g vercel

# 链接到Vercel项目
vercel link
 
# 下载环境变量
vercel env pull
 
# 本地运行(使用生产环境配置)
vercel dev

✅ 本地使用Vercel的环境变量
✅ 模拟Vercel的Serverless Functions
✅ 测试rewrite/redirect规则

example.com          → 主域名
www.example.com      → 自动跳转到主域名
blog.example.com     → 独立访问

// vercel.json
{
  "build": {
    "env": {
      "ENABLE_EXPERIMENTAL_COREPACK": "1",
      "NEXT_PRIVATE_CACHE_HANDLER": "1"
    }
  },
  "crons": [
    {
      "path": "/api/clear-cache",
      "schedule": "0 0 * * *"
    }
  ]
}

{
  "redirects": [
    {
      "source": "/old-blog/:slug",
      "destination": "/blog/:slug",
      "permanent": true
    },
    {
      "source": "/docs",
      "destination": "/documentation",
      "permanent": false
    }
  ]
}

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        },
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

✅ 无限项目
✅ 无限部署
✅ 100GB带宽/月
✅ 1000次Serverless Function调用/天
✅ 自动SSL证书
✅ 全球CDN
 
❌ 团队协作(仅限个人)
❌ 商业使用

+ Hobby所有功能
+ 1TB带宽/月
+ 无限Serverless调用
+ 团队协作(无限成员)
+ 优先级支持
+ 密码保护
+ 分析和日志保留更长

✅ 月访问量超过100GB带宽
✅ 需要团队协作开发
✅ 需要密码保护预览环境
✅ 需要更详细的访问分析

✅ 代码已推送到GitHub
✅ package.json中的dependencies正确
✅ 本地执行npm run build成功
✅ 构建产物在正确的输出目录
✅ 环境变量整理完毕
✅ .gitignore包含node_modules和构建产物

✅ Framework Preset正确识别
✅ Build Command配置正确
✅ Output Directory配置正确
✅ Root Directory配置正确(如果不是根目录)
✅ Environment Variables添加完整

✅ 首页能正常访问
✅ 前端路由跳转正常(多页应用)
✅ 静态资源加载正常
✅ API请求正常(如果有后端)
✅ 环境变量生效
✅ 移动端响应式正常

✅ DNS记录配置正确
✅ DNS已生效(nslookup检查)
✅ Vercel中域名验证成功
✅ HTTPS证书自动签发
✅ HTTP自动跳转HTTPS
✅ www和非www都能访问(如果需要)