JavaScriptNode.js大前端
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