Vercel 部署指南:从 GitHub 连接至自定义域名上线
介绍如何使用 Vercel 将前端项目从 GitHub 仓库快速部署到公网。涵盖账号注册、项目导入、构建配置、环境变量设置、自定义域名绑定及 DNS 解析步骤。同时提供常见部署错误排查方案(如路由 404、构建超时)及性能优化建议,帮助开发者实现零配置、全球 CDN 加速的自动化部署流程。

介绍如何使用 Vercel 将前端项目从 GitHub 仓库快速部署到公网。涵盖账号注册、项目导入、构建配置、环境变量设置、自定义域名绑定及 DNS 解析步骤。同时提供常见部署错误排查方案(如路由 404、构建超时)及性能优化建议,帮助开发者实现零配置、全球 CDN 加速的自动化部署流程。

在多种前端部署平台中,Vercel 具有以下核心优势:
| 特性 | Vercel | GitHub Pages | 传统服务器 |
|---|---|---|---|
| 免费额度 | ⭐⭐⭐⭐⭐ 个人用足够 | ⭐⭐⭐⭐ 静态网站 | ❌ 需付费 |
| 部署速度 | ⭐⭐⭐⭐⭐ 秒级 | ⭐⭐⭐ 分钟级 | ⭐⭐ 需手动 |
| CDN 加速 | ✅ 全球 CDN | ✅ GitHub CDN | ❌ 需自己配置 |
| 自动部署 | ✅ Git 推送即部署 | ✅ 推送到 gh-pages | ❌ 需 CI/CD |
| 环境变量 | ✅ 支持 | ❌ 不支持 | ✅ 支持 |
| 自定义域名 | ✅ 免费 SSL | ✅ 免费 SSL | ✅ 需自己配置 SSL |
| 框架支持 | ⭐⭐⭐⭐⭐ 智能识别 | ⭐⭐ 仅静态 | ⭐⭐⭐⭐ 任意 |
最大亮点:
💡 提示: 使用传统 VPS 部署前端,每次更新都要 SSH 登录、git pull、npm build、重启 Nginx…换到 Vercel 后,只需
git push,剩下的全自动!
Vercel 对以下框架有原生支持,可以零配置部署:
打开浏览器,访问 https://vercel.com
强烈推荐使用 GitHub 账号登录,这样可以直接授权访问你的仓库,省去后续连接的麻烦。
点击 'Continue with GitHub':
首次登录时,GitHub 会要求你授权 Vercel 访问你的仓库。
授权范围:✅ 读取仓库列表 ✅ 读取仓库代码 ✅ 添加部署状态 (在 PR 中显示部署预览)
点击 'Authorize Vercel' 完成授权。
⚠️ 隐私说明: Vercel 只会读取你主动导入的仓库,不会访问其他私有仓库。
登录成功后,你会看到 Vercel 的 Dashboard。点击 'Add New…' → 'Project'。
Vercel 会列出你 GitHub 账号下的所有仓库。找到你想部署的项目,点击 'Import'。
找不到你的仓库?
可能有以下原因:
❌ 仓库是私有的,但未授权 Vercel 访问 → 解决:去 GitHub Settings 重新授权
❌ 仓库属于 Organization,需要额外授权 → 解决:在 Organization 设置中授权 Vercel
❌ 仓库名称被搜索框过滤了 → 解决:清空搜索框或手动输入仓库名
导入项目后,会进入配置页面。Vercel 会自动检测你的项目类型和构建命令。
1. Project Name (项目名称)
默认:你的 GitHub 仓库名
用途:决定默认的 vercel 域名 (如 my-app.vercel.app)
建议:使用简洁、有意义的名称
2. Framework Preset (框架预设)
Vercel 会自动识别你的框架:
| 检测到的框架 | 自动配置 |
|---|---|
| Next.js | Build: next build, Output: .next |
| Create React App | Build: npm run build, Output: build |
| Vite | Build: npm run build, Output: dist |
| Vue CLI | Build: npm run build, Output: dist |
💡 智能识别: 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 (输出目录)
构建完成后,静态文件的输出位置。
常见框架的输出目录:
| 框架 | 默认输出目录 |
|---|---|
| Next.js | .next |
| Create React App | build |
| Vite | dist |
| Vue CLI | dist |
| Angular | dist/<project-name> |
如何确认输出目录?
在本地运行构建命令:
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_前缀 (如果要在客户端访问)。
配置完成后,点击底部的 'Deploy' 按钮。
点击部署后,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 分钟,取决于你的项目大小和依赖数量。
部署成功时会有个庆祝界面,恭喜,部署成功了!🎉
你会得到一个默认域名,格式为:
https://your-project-name.vercel.app
立即访问测试!
点击 'Visit' 按钮,或者直接在浏览器中打开这个 URL,看看你的项目是否正常运行。
如果部署失败,Vercel 会显示详细的错误信息:
常见错误及解决方案:
Command "npm run build" exited with 1原因:构建命令执行失败
解决:
1. 检查 package.json 中的 build 脚本是否正确
2. 在本地运行 `npm run build` 看是否有错误
3. 检查是否缺少必要的环境变量
Error: Cannot find module 'xxx'原因:缺少依赖包
解决:
1. 确认依赖包在 package.json 的 dependencies 中 (不是 devDependencies)
2. 本地删除 node_modules 重新安装测试
3. 检查 package-lock.json 是否提交到 GitHub
Build exceeded maximum duration of 45 minutes原因:构建超时 (免费版限制 45 分钟)
解决:
1. 优化构建配置,减少不必要的依赖
2. 使用 .vercelignore 排除不需要的文件
3. 考虑升级到 Pro 版 (300 分钟限制)
FATAL ERROR: Reached heap limit原因:Node.js 内存不足
解决:在项目根目录创建 vercel.json:
{
"builds": [
{
"src": "package.json",
"use": "@vercel/node",
"config": {
"maxLambdaSize": "50mb"
}
}
]
}
部署成功后,最酷的功能来了:自动部署!
工作流程:
你在本地修改代码 ↓
git commit & git push ↓
Vercel 检测到 GitHub 仓库更新 ↓
自动触发新的部署 ↓
几分钟后新版本自动上线!
完全不需要手动操作!
默认的 vercel.app 域名虽然能用,但不够专业。让我们配置一个自己的域名!
进入项目的 Settings → Domains:
输入你的域名,如 blog.example.com,然后点击 'Add'。
Vercel 会显示需要配置的 DNS 记录:
两种域名类型:
示例:example.com
需要配置:A 记录:example.com → 76.76.21.21
示例:blog.example.com 或 www.example.com
需要配置:CNAME 记录:blog → cname.vercel-dns.com
我以腾讯云 DNSPod为例,演示配置过程。(阿里云、Cloudflare 等平台操作类似)
访问 https://console.dnspod.cn,登录后选择你的域名:
点击 '添加记录':
配置示例 (子域名):
记录类型:CNAME
主机记录:blog (如果是 www 则填 www)
记录值:复制 Vercel 中添加的域名中的 CNAME 对应的 Value 指
TTL: 600 (10 分钟,可以默认)
配置示例 (根域名):
记录类型:A
主机记录:@ (@ 表示根域名)
记录值:76.76.21.21 (Vercel 提供的 IP 地址)
TTL: 600
点击 '保存'。
DNS 记录通常需要几分钟到几小时才能全球生效。
如何检查 DNS 是否生效?
在命令行中执行:
# 检查 CNAME 记录
nslookup blog.example.com
# 或使用 dig 命令
dig blog.example.com
# 应该看到返回:
# blog.example.com. IN CNAME cname.vercel-dns.com.
回到 Vercel 的 Domains 设置页面,等待系统自动验证:
验证成功后,会显示:域名配置成功,自动启用 HTTPS
Vercel 自动提供:
在浏览器中访问你的自定义域名:
https://blog.example.com
成功!🎉
同时你还会发现:
your-app.vercel.app 仍然可用在项目的 Deployments 页面,可以看到所有的部署记录:
每个部署都有:
如果新版本有问题,可以瞬间回退到任意历史版本:
回滚流程:
1. 找到你想回退到的版本
2. 点击右侧的 ⋯ 按钮
3. 选择 "Promote to Production"
4. 几秒钟后,旧版本重新上线!
在 Analytics 页面查看访问数据:
免费版数据:
问题现象:
访问首页: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,让前端路由接管。
问题现象:
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"}
问题现象:
console.log(import.meta.env.VITE_API_URL)// 输出:undefined
排查清单:
❌ 环境变量名称错误 (缺少前缀) → Vite: 必须以 VITE_开头 → CRA: 必须以 REACT_APP_开头 → Next.js: 必须以 NEXT_PUBLIC_开头 (客户端使用)
❌ 环境变量未在 Vercel 中配置 → 进入 Settings → Environment Variables 添加
❌ 配置后未重新部署 → 修改环境变量后需要触发新部署才能生效
优化策略:
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
}
}
]
}
问题现象:
浏览器显示 "您的连接不是私密连接"。
解决步骤:
1. 检查 DNS 是否生效 (nslookup your-domain.com)
2. 在 Vercel 中删除域名,重新添加
3. 等待几分钟让 Let's Encrypt 重新签发证书
4. 清除浏览器缓存和 SSL 状态
安装 Vercel CLI:
npm i -g vercel
在本地模拟 Vercel 环境:
# 链接到 Vercel 项目
vercel link
# 下载环境变量
vercel env pull
# 本地运行 (使用生产环境配置)
vercel dev
优势:
一个项目可以绑定多个域名:
example.com → 主域名
www.example.com → 自动跳转到主域名
blog.example.com → 独立访问
在 Vercel Domains 设置中添加多个域名即可。
优化构建速度:
// vercel.json
{
"build": {
"env": {
"ENABLE_EXPERIMENTAL_COREPACK": "1",
"NEXT_PRIVATE_CACHE_HANDLER": "1"
}
},
"crons": [
{
"path": "/api/clear-cache",
"schedule": "0 0 * * *"
}
]
}
SEO 优化和 URL 管理:
{
"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 调用 + 团队协作 (无限成员) + 优先级支持 + 密码保护 + 分析和日志保留更长
什么时候需要升级 Pro?
✅ 月访问量超过 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 都能访问 (如果需要)
官方文档:

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online