Vercel 部署指南：从 GitHub 连接至自定义域名上线

打开浏览器，访问 https://vercel.com

1.2 使用 GitHub 账号登录

强烈推荐使用 GitHub 账号登录,这样可以直接授权访问你的仓库，省去后续连接的麻烦。

点击 'Continue with GitHub':

1.3 授权 Vercel 访问 GitHub

首次登录时，GitHub 会要求你授权 Vercel 访问你的仓库。

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

点击 'Authorize Vercel' 完成授权。

⚠️ 隐私说明: Vercel 只会读取你主动导入的仓库，不会访问其他私有仓库。

第二步：导入 GitHub 项目到 Vercel

2.1 进入项目导入页面

登录成功后，你会看到 Vercel 的 Dashboard。点击 'Add New…' → 'Project'。

2.2 选择要部署的仓库

Vercel 会列出你 GitHub 账号下的所有仓库。找到你想部署的项目，点击 'Import'。

找不到你的仓库？

可能有以下原因：

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

2.3 配置项目设置

导入项目后，会进入配置页面。Vercel 会自动检测你的项目类型和构建命令。

核心配置项说明

1. Project Name (项目名称)

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

2. Framework Preset (框架预设)

Vercel 会自动识别你的框架：

💡 智能识别: Vercel 会读取你的 package.json 来判断框架类型。

3. Root Directory (根目录)

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

4. Build Command (构建命令)

这是最重要的配置!Vercel 会执行这个命令来构建你的项目。

常见框架的构建命令:

# 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

如何确认你的构建命令?

打开项目的 package.json,查看 scripts 字段：

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

在 Vercel 配置中填写：npm run build

5. Output Directory (输出目录)

构建完成后，静态文件的输出位置。

常见框架的输出目录:

如何确认输出目录?

在本地运行构建命令：

npm run build

查看生成的文件夹名称，那就是输出目录!

6. Install Command (安装命令)

默认情况下，Vercel 会自动检测并使用：

• npm install (如果有 package-lock.json)
• yarn install (如果有 yarn.lock)
• pnpm install (如果有 pnpm-lock.yaml)

通常不需要修改。

环境变量配置 (可选)

如果你的项目需要环境变量 (如 API 密钥、后端地址),在这里配置：

示例:

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

💡 提示: Vite 项目的环境变量需要 VITE_ 前缀，Create React App 项目需要 REACT_APP_ 前缀，Next.js 项目需要 NEXT_PUBLIC_ 前缀 (如果要在客户端访问)。

2.4 开始部署

配置完成后，点击底部的 'Deploy' 按钮。

第三步：等待构建和部署

3.1 构建过程实时日志

点击部署后，Vercel 会显示实时构建日志。

构建流程:

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

首次部署通常需要 2-5 分钟,取决于你的项目大小和依赖数量。

3.2 部署成功!

部署成功时会有个庆祝界面，恭喜，部署成功了！🎉

你会得到一个默认域名，格式为：

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

立即访问测试!

点击 'Visit' 按钮，或者直接在浏览器中打开这个 URL，看看你的项目是否正常运行。

3.3 部署失败？别慌，看日志!

如果部署失败，Vercel 会显示详细的错误信息：

常见错误及解决方案:

错误 1: Command "npm run build" exited with 1

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

错误 2: Error: Cannot find module 'xxx'

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

错误 3: Build exceeded maximum duration of 45 minutes

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

错误 4: FATAL ERROR: Reached heap limit

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

第四步：配置自动部署

部署成功后，最酷的功能来了：自动部署!

4.1 Git 自动部署原理

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

完全不需要手动操作!

第五步：配置自定义域名 (进阶)

默认的 vercel.app 域名虽然能用，但不够专业。让我们配置一个自己的域名!

5.1 前置条件

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

5.2 在 Vercel 中添加域名

进入项目的 Settings → Domains:

输入你的域名，如 blog.example.com,然后点击 'Add'。

Vercel 会显示需要配置的 DNS 记录：

两种域名类型:

类型 1: 根域名 (Apex Domain)

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

类型 2: 子域名 (Subdomain)

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

5.3 在腾讯云 DNS 配置域名解析

我以腾讯云 DNSPod为例，演示配置过程。(阿里云、Cloudflare 等平台操作类似)

步骤 1: 登录腾讯云 DNSPod

访问 https://console.dnspod.cn，登录后选择你的域名：

步骤 2: 添加 CNAME 记录

点击 '添加记录':

配置示例 (子域名):

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

配置示例 (根域名):

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

点击 '保存'。

步骤 3: 等待 DNS 生效

DNS 记录通常需要几分钟到几小时才能全球生效。

如何检查 DNS 是否生效?

在命令行中执行：

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

5.4 在 Vercel 中验证域名

回到 Vercel 的 Domains 设置页面，等待系统自动验证：

验证成功后，会显示：域名配置成功，自动启用 HTTPS

Vercel 自动提供:

• ✅ 免费 SSL 证书 (Let's Encrypt)
• ✅ 自动续期
• ✅ 强制 HTTPS 跳转

5.5 测试自定义域名

在浏览器中访问你的自定义域名：

https://blog.example.com

成功！🎉

同时你还会发现:

• 默认域名 your-app.vercel.app 仍然可用
• HTTP 自动跳转到 HTTPS
• 加载速度飞快 (全球 CDN 加速)

第六步：项目管理和运维

6.1 查看部署历史

在项目的 Deployments 页面，可以看到所有的部署记录：

每个部署都有：

• 唯一的 URL
• 部署时间
• Git commit 信息
• 构建日志
• 访问统计

6.2 一键回滚

如果新版本有问题，可以瞬间回退到任意历史版本：

回滚流程:

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

6.3 访问统计

在 Analytics 页面查看访问数据：

免费版数据:

• 访问量 (PV/UV)
• 地理分布
• 设备类型
• 浏览器类型

常见问题排查

Q1: 部署成功但页面 404

问题现象:

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

原因: 前端路由 (React Router/Vue Router) 需要服务器配置支持。

解决方案:

在项目根目录创建 vercel.json:

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

这会将所有请求重定向到 index.html,让前端路由接管。

Q2: 静态资源加载失败 (404)

问题现象:

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

原因: 静态资源路径配置错误。

解决方案:

Vite 项目:

修改 vite.config.js:

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

Create React App:

修改 package.json:

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

Q3: 环境变量未生效

问题现象:

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

排查清单:

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

Q4: 构建时间过长

优化策略:

1. 使用 .vercelignore 排除不必要文件

创建 .vercelignore:

.git *.md .vscode .idea tests docs

2. 启用依赖缓存

Vercel 默认会缓存 node_modules,但可以优化：

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

3. 并行构建

如果是 monorepo，可以配置并行构建：

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

Q5: 自定义域名 HTTPS 证书错误

问题现象:

浏览器显示 "您的连接不是私密连接"。

解决步骤:

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

进阶技巧

技巧 1: 使用 Vercel CLI 本地开发

安装 Vercel CLI:

npm i -g vercel

在本地模拟 Vercel 环境:

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

优势:

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

技巧 2: 配置多域名

一个项目可以绑定多个域名：

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

在 Vercel Domains 设置中添加多个域名即可。

技巧 3: 自定义构建缓存

优化构建速度：

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

技巧 4: 配置 Redirect 规则

SEO 优化和 URL 管理：

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

技巧 5: 配置 HTTP Headers

安全和性能优化：

{
  "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"
        }
      ]
    }
  ]
}

成本和限制

Hobby(免费) 计划

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

Pro 计划 ($20/月)

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

什么时候需要升级 Pro?

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

对于个人项目和小型网站，免费计划完全够用!

总结：Vercel 部署检查清单

部署前检查

✅ 代码已推送到 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 都能访问 (如果需要)

相关资源

官方文档:

• Vercel 官方文档
• Vercel CLI 文档
• 部署配置指南