文档
开发指南部署指南

部署指南

🚀 Cheatsheet (快速执行)

目标: 5分钟内把代码部署到线上，拥有自己的域名

最快部署方式:

# 1. 推送代码到 GitHub
git add .
git commit -m "ready to deploy"
git push

# 2. 连接到 Vercel (一次性设置)
# 访问 vercel.com/new，选择你的项目仓库

# 3. 设置环境变量，点击 Deploy

3分钟访问链接: https://your-project.vercel.app

❓ 为什么要做部署

对 MVP 的价值:

  • 真实用户测试: 只有上线才能获得真实反馈
  • 分享演示: 给投资人、合作伙伴展示产品
  • SEO 开始: 搜索引擎开始索引你的网站
  • 域名占坑: 抢注好域名，建立品牌

不部署的问题: 永远只是本地项目，没人能看到，等于没做。

🤔 为什么选择 Vercel

我们的使用体验:

  • 零配置: 连接 GitHub 后自动构建部署
  • 速度快: 全球 CDN，国内访问也不慢
  • 免费额度: 个人项目完全够用
  • Next.js 原生: 专为 Next.js 优化的平台

对比其他平台:

# Vercel    - ⭐ 推荐，Next.js 原生支持
# Netlify   - 备选，功能类似
# Railway   - 适合需要数据库的项目  
# Render    - 欧美用户友好

🧠 部署原理 & 最简流程

Vercel 工作原理: GitHub 代码更新 → 自动触发构建 → 部署到全球 CDN → 用户访问

一键部署流程:

  1. 连接 GitHub: Vercel 读取你的代码
  2. 自动构建: 运行 bun run build 命令
  3. 部署上线: 生成 .vercel.app 域名
  4. 持续部署: 每次推送代码自动更新

🛠️ 实际操作步骤

1. 准备工作 (2分钟)

确保代码可以构建:

# 本地测试构建
bun run build

# 如果成功，推送到 GitHub
git add .
git commit -m "ready for deployment"
git push

2. Vercel 部署 (3分钟)

步骤:

  1. 访问 vercel.com/new
  2. 用 GitHub 账号登录
  3. 选择你的项目仓库
  4. 点击 "Deploy" (第一次自动检测配置)

自动检测的配置:

{
  "buildCommand": "bun run build",
  "outputDirectory": ".next",
  "installCommand": "bun install"
}

3. 环境变量配置 (5分钟)

必需的环境变量:

NEXTAUTH_URL=https://your-project.vercel.app
NEXTAUTH_SECRET=your-secret-here
DATABASE_URL=your-database-url

# 如果使用邮件服务
RESEND_API_KEY=your-resend-key

# 如果使用支付
STRIPE_SECRET_KEY=your-stripe-key

设置方法:

  1. Vercel Dashboard → 项目设置 → Environment Variables
  2. 添加每个变量的 Name 和 Value
  3. 选择环境: Production + Preview + Development

4. 自定义域名 (可选, 5分钟)

连接自己的域名:

# 1. 在 Vercel 项目设置中添加域名
# 2. 在域名注册商处设置 DNS
# 类型: CNAME, 名称: www, 值: your-project.vercel.app
# 类型: A, 名称: @, 值: 76.76.19.61

🔧 常用部署命令

Vercel CLI 命令 (可选):

# 安装 Vercel CLI
npm i -g vercel

# 本地部署到预览环境
vercel

# 部署到生产环境
vercel --prod

# 查看部署状态
vercel ls

项目管理:

# 查看项目信息
vercel inspect your-project.vercel.app

# 查看部署日志
vercel logs your-project.vercel.app

💡 部署优化技巧

构建优化

# 1. 减少包大小
bun run build-analyze

# 2. 启用压缩 (next.config.ts 已配置)
compress: true,

# 3. 图片优化 (自动)
# Vercel 自动优化图片格式和大小

性能监控

# Vercel Analytics (免费)
# 在项目设置中启用 Analytics

# Core Web Vitals 监控
# 自动在 Vercel Dashboard 显示

分支部署

# 主分支 → 生产环境
git push origin main

# 功能分支 → 预览环境 
git push origin feature/new-feature
# 自动生成预览链接: https://your-project-git-feature-new-feature.vercel.app

🆘 常见部署问题

问题 1: 构建失败

# 错误: "Module not found"
# 解决: 检查 import 路径是否正确

# 错误: "Environment variable missing"  
# 解决: 在 Vercel 设置中添加缺失的环境变量

# 错误: "Build timeout"
# 解决: 优化构建过程，移除大文件

问题 2: 页面 404

# 动态路由 404
# 解决: 检查文件名是否使用 [...slug].tsx 格式

# API 路由 404
# 解决: 确保 API 文件在 app/api/ 目录下

问题 3: 数据库连接失败

# 检查环境变量
vercel env ls

# 测试数据库连接
# 在 Vercel Functions 中运行数据库查询测试

🚀 其他部署平台

Netlify (备选方案)

# 优势: 免费表单处理、边缘函数
# 劣势: Next.js 支持不如 Vercel 完善
# 适合: 静态网站 + 简单后端功能

Railway (数据库友好)

# 优势: 内置数据库、简单配置
# 劣势: 免费额度较少
# 适合: 需要托管数据库的项目

自建服务器 (高级)

# Docker 部署
docker build -t my-app .
docker run -p 3000:3000 my-app

# 适合: 对性能和控制有特殊要求

📊 部署后检查

基础功能测试

# ✅ 首页加载正常
# ✅ 注册/登录流程
# ✅ API 接口响应  
# ✅ 数据库读写
# ✅ 邮件发送

性能检查

# Google PageSpeed Insights
# https://pagespeed.web.dev/

# Vercel Analytics
# 在项目 Dashboard 查看

# 检查 Core Web Vitals
# LCP < 2.5s, FID < 100ms, CLS < 0.1

📎 延伸阅读

官方文档:

替代平台:

域名服务:

下一步: 部署成功后，查看 [生产环境]./production) 完成上线前的最后检查。

SEO优化指南

Previous Page

生产环境

Next Page