vercerl_test：Vercel 静态页面部署记录

用 Vercel 部署一个最简单的 HTML 页面 —— vercerl_test 上手记录

菜牙爱吃菜 · 2026-10-20

大家好，我是菜牙。

今天想聊一个特别简单但对我们开发者来说非常实用的话题：如何把一个纯静态 HTML 页面用 Vercel 部署到公网上。别看这事儿简单，对于没接触过 CI/CD 和 Serverless 部署的新手来说，第一次踩坑的感觉我还记忆犹新。

这篇文章以我刚部署的一个小项目 vercerl_test 为例，完整记录从零到上线的过程。

一、项目介绍：vercerl_test 是什么？

一句话概括：一个纯 HTML 的静态测试页面。

它没有复杂的框架、没有后端服务、没有数据库。整个项目就 4 个文件：

vercerl_test/
├── index.html      # 页面结构
├── index.js        # 交互逻辑（如果有）
├── package.json    # Node.js 项目描述
└── vercel.json     # Vercel 部署配置

项目地址：guyib.vercel.app

虽然简单，但它是我用来验证 Vercel 部署流程的一个" Hello World "——毕竟在学任何新平台的时候，先跑通一个最小可用的东西最重要。

二、技术栈：简单到不能再简单

层面	选型	说明
前端	原生 HTML + CSS + JS	不依赖任何框架
运行时	Node.js（仅用于项目声明）	实际上纯静态不需要 Node
部署平台	Vercel	全球 CDN，自动 HTTPS
版本控制	GitHub	与 Vercel 无缝集成

是的，你没有看错——技术上就是最基础的 HTML。Vercel 对静态站点有原生支持，不需要构建步骤就能直接部署。

package.json 的作用

有人可能会问：纯静态页面为什么还要 package.json？

{
  "name": "vercerl_test",
  "version": "1.0.0",
  "private": true,
  "description": "Simple HTML page deployed on Vercel"
}

主要是为了告诉 Vercel（和工具链）这是一个 Node.js 项目，方便后续扩展。即使不写任何依赖，Vercel 也能识别并正确处理。

三、最小静态部署配置

纯静态目录可在 Vercel 选择合适的静态/Other 项目设置，明确根目录和输出目录，无需为了只有 index.html 的页面引入 Node 构建。package.json 仅在需要项目元数据或脚本时保留。

原稿 builds/routes 属于旧配置方式。不要把所有路径无条件返回 index.html，否则 JS、图片或缺失文件也可能得到 HTML。需要 SPA 回退时，按当前路由配置保留真实静态资源与 404 语义。

四、部署体验：3 分钟上线

整个部署流程比我预想的快很多：

第 1 步：推到 GitHub

git init -b main
git add .
git commit -m "init: vercerl_test"
git remote add origin git@github.com:huc-a/vercerl_test.git
git push -u origin main

因为是私有仓库，Vercel 需要授权访问。在 Vercel Dashboard 里点几下就行。

第 2 步：Vercel Dashboard 配置

登录 vercel.com（用 GitHub 账号一键登录）
点击 “Add New Project”
选择 huc-a/vercerl_test 仓库
检查 Root Directory、Framework Preset 与输出目录，确认部署包含所需静态文件
点击 Deploy

第 3 步：等待部署完成

大概 30 秒到 1 分钟，Vercel 就完成了构建和部署。访问 https://guyib.vercel.app，页面直接就出来了。

自动获得的能力：

✅ 全球 CDN 加速（Vercel Edge Network）
✅ 自动 HTTPS 证书
✅ 每次 push 自动重新部署（CI/CD）
✅ 每次 PR 自动生成预览环境

五、踩坑与经验总结

坑 1：文件名大小写

一开始我把入口文件写成了 Index.html（大写 I），在 Windows 本地开发没问题，但部署到 Vercel（Linux 环境）后就 404 了。

教训：Linux 文件系统区分大小写，团队协作或跨平台部署时，文件名统一用全小写。

坑 2：vercel.json 的版本号

早期 Vercel 配置用的 version 字段值是 1，旧配置中使用 2；新项目应按当前项目设置与文档配置。版本 2 支持更多特性，比如更灵活的路由规则。

坑 3：不要忽略 package.json

虽然没有 package.json 也能部署，但加上它能：

让 IDE 和工具链正确识别项目类型
方便以后加构建步骤（比如需要 minify、打包的时候）
声明项目元数据（名称、版本、描述）

六、一点思考

很多人觉得"这么简单的东西有什么好写的"。但我觉得恰恰相反——简单的东西写清楚了，才能帮到更多人。

Vercel 这类 Serverless 部署平台的核心价值就是：让开发者专注于代码本身，而不是运维。不需要买服务器、不需要配 Nginx、不需要管 SSL 证书。写代码，push，完事儿。

对于个人项目、博客、文档站点、原型验证，Vercel 是目前我用过最省心的方案。免费额度对于个人使用也完全够用。

七、后续计划

vercerl_test 目前只是个起点，后面打算：

[ ] 加上一些 CSS 美化，让它不那么"素颜"
[ ] 加入简单的 JavaScript 交互
[ ] 写一篇进阶版：如何在 Vercel 上部署带后端的 Full-stack 应用
[ ] 对比 Vercel / Netlify / Cloudflare Pages 的体验差异

写在最后

感谢你读到这里。技术文章不一定要高深复杂，把一个简单的问题讲清楚、讲透彻，本身就是一种能力。

如果你也在学习部署相关的内容，欢迎访问 guyib.vercel.app 看看这个项目的线上效果。也欢迎通过博客留言区交流。

保持学习，保持分享。 🌱

文章首发于「菜牙爱吃菜」博客，转载请注明出处。