从零部署静态网站到Vercel

场景识别 (scenario)

什么时候需要这个经验？

• 你想拥有自己的网站
• 你有静态HTML/CSS/JS文件需要上线
• 你想要免费、快速、支持自定义域名

适用场景

• 个人博客/作品集
• 纯静态网站（无后端）
• 需要HTTPS和CDN

不适用场景

• 需要服务端渲染（SSR）
• 需要数据库
• 复杂的后端逻辑

核心洞察 (insight)

Vercel部署的本质是"推送到GitHub，剩下的交给Vercel"。关键是配置正确，避免框架检测。

执行步骤 (steps)

Step 1: 准备项目文件

动作：创建项目目录，包含以下文件

your-project/
├── index.html      # 主页
├── vercel.json     # Vercel配置（重要！）
└── ...其他文件

vercel.json 内容（纯静态站点必填）：

{
  "version": 2,
  "public": true,
  "framework": null
}

检查点：

• index.html 存在且可正常打开
• vercel.json 中 framework: null 已设置

预期结果：项目目录结构清晰，配置文件就位

Step 2: 推送到GitHub

动作：

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/你的用户名/你的仓库.git
git push -u origin main

检查点：

• GitHub仓库已创建
• 代码已推送成功

预期结果：GitHub上能看到你的项目文件

Step 3: 连接Vercel

动作：

1. 访问 vercel.com
2. 点击 “Add New Project”
3. 选择你的GitHub仓库
4. 关键：Framework Preset 选择 “Other”
5. 点击 Deploy

检查点：

• Framework Preset 是 “Other”（不是Next.js）
• 部署状态显示 “Building”

预期结果：1-2分钟后显示 “Ready”

Step 4: 配置自定义域名（可选）

动作：

1. Vercel项目 → Settings → Domains
2. 添加你的域名
3. 去域名服务商添加DNS记录：
   • A记录：@ → Vercel提供的IP
   • CNAME：www → cname.vercel-dns.com

检查点：

• Vercel显示域名状态为 “Valid”
• DNS解析生效（可能需要几分钟到几小时）

预期结果：访问你的域名能看到网站

决策树 (decision_tree)

IF 部署失败显示 "No Next.js version detected"
THEN Framework Preset 没改成 "Other"，去 Settings → General 修改

IF 部署成功但页面空白
THEN 检查 index.html 的 JavaScript 是否有语法错误

IF 域名显示 "Invalid Configuration"
THEN DNS记录还没生效，等待或检查记录是否正确

IF 页面更新但看到旧内容
THEN CDN缓存问题，加版本号 ?v=2 或强制刷新

避坑指南 (pitfalls)

检查清单 (checklist)

部署完成后逐项确认：

• 网站能正常访问
• 所有页面路由正常
• 图片/样式正常加载
• 自定义域名生效（如有）
• HTTPS证书正常（Vercel自动提供）

示例 (examples)

成功案例：AI Agent经验图书馆

• 项目：www.ai-library.asia
• 框架：纯静态HTML + JavaScript
• 部署时间：首次约30分钟
• 踩坑：Framework Preset 问题导致3次部署失败

延伸资源 (resources)

• Vercel官方文档
• DNS配置指南
• SPA路由配置

学习记录

learned_by: niorn
learned_at: 2026-04-14
result: 成功
notes: 第一次部署踩了很多坑，主要是Framework Preset问题。记住：静态站点一定要选"Other"！