**这是本文档旧的修订版!**
Vercel 使用教程
Vercel 是一个前端 / 静态站点托管平台:把本地的一堆文件(或一个前端项目)传上去,它替你跑构建、发到全球 CDN,最后给你一个可访问的 https 网址。
Next.js笔记 里提到过它,这篇专门讲怎么用,重点放在不接 Git 仓库的做法——直接把自己电脑上的代码传上去建站。
一、三种部署方式怎么选
| 方式 | 操作 | 需要的条件 |
|---|---|---|
| Git 集成 | 绑定 GitHub / GitLab / Bitbucket,push 后自动部署 | 需要仓库,需要 Git |
| 网页上传 | 在控制台里拖入文件夹或 zip | 什么都不用装 |
| CLI 命令 | 本地执行 vercel / vercel –prod | 装 Node.js,最可控,推荐 |
关键认识:不用 Git 完全不影响功能。三种方式产出的结果一模一样,都是 https:项目名.vercel.app,区别只是“代码怎么送到 Vercel”以及“以后怎么更新”。
===== 二、准备工作 =====
1. 注册账号:vercel.com/signup。用邮箱注册即可,不必绑 Git;当然也可以用 GitHub / Google 账号登录(那只是身份认证,不代表要用它托管代码)。
2. 整理本地目录,让网站根目录清晰——纯静态站点长这样:
<code>
my-site/
├── index.html ← 入口,必须在最外层
├── style.css
├── app.js
└── images/
└── logo.png
</code>
需要构建的项目(Vite / React / Next 等)则保证 package.json 在项目根目录。
===== 三、方案一:CLI 上传(推荐)=====
==== 1. 安装 Node.js 与 CLI ====
<code bash>
node -v # 确认 Node 18+(新版本 CLI 要求更高,建议 20+)
npm i -g vercel
vercel –version
</code>
Windows 下若提示权限不足,用管理员身份打开 PowerShell 重试。
==== 2. 登录 ====
<code bash>
vercel login
</code>
会让你选择登录方式(邮箱 / GitHub / Google)。选邮箱时,命令行给出一个确认地址,浏览器打开点确认即可(设备授权流程),全程不涉及 Git。
==== 3. 在项目目录里部署 ====
<code bash>
cd my-site
vercel # 部署到 Preview(预览环境),先验证效果
vercel –prod # 部署到 Production(正式网址)
</code>
首次运行会问几个问题,答完写入 .vercel/ 目录,以后就不再问:
<code>
? Set up and deploy “~/my-site”? Y
? Which scope do you want to deploy to? 选自己的账号
? Link to existing project? N
? What's your project's name? my-site
? In which directory is your code located? ./
? Want to modify these build settings? N
</code>
想跳过全部交互、一律用默认值:vercel –yes。
需要构建的项目:Vercel 会自动识别 Vite / Next / Nuxt 等框架,用默认构建命令(npm run build)和默认输出目录在云端构建,所以你不需要先在本地构建。识别错了就在上面那步选 Y 手动填 Build Command 与 Output Directory,或事后到控制台 Settings → Build & Development Settings 修改。
纯静态项目(没有 package.json,只有 index.html):Vercel 直接当静态站点托管,不跑任何构建。
==== 4. 更新网站 ====
改完代码再跑一次 vercel –prod 就行。每次部署都是不可变快照,旧版本不会丢。
==== 5. 不想把源码传到云端 ====
上面默认会上传源码、由 Vercel 云端构建。如果只想传成品:
<code bash>
vercel pull –yes –environment=production # 拉取项目配置与环境变量
vercel build –prod # 本地构建,产物在 .vercel/output
vercel deploy –prebuilt –prod # 只上传构建产物
</code>
这样 Vercel 拿到的是 dist 之类的结果,拿不到源码。
===== 四、方案二:网页上传(零安装)=====
不想装 Node.js 的话,控制台本身就带上传部署入口:
1. 打开 vercel.com/new,或在已有项目的 Deployments 页面找右上角的部署按钮(不同时期文案可能是 Create Deployment 或 Deploy,认准带虚线上传框的弹窗;UI 会变,以实际界面为准)。
2. 把 index.html 所在的整个文件夹拖进去,或选择一个提前打好的 zip 包;还没有项目时会引导你先建一个。
3. 等它跑完,页面给出 项目名.vercel.app 网址。
三点提醒:
* 拖的是“网站根目录本身”,不要把外层文件夹一起打包,否则会多出一层路径。
* 项目需要构建时,先在本地构建好、拖产物目录最稳妥;想省心就直接用 CLI 让云端构建。
* 上传有体积上限,大项目会被拒绝,这时必须改用 CLI。
===== 五、绑定自己的域名 =====
1. 控制台进入项目 → Settings → Domains → Add,填域名(建议 example.com 和 www.example.com 都加上)。
2. 按面板提示到域名服务商添加解析,以面板显示的值优先,常见组合是:
* 裸域 example.com:A 记录 → 76.76.21.21
* www:CNAME → cname.vercel-dns.com
3. 也可以把域名的 NS 直接托管给 Vercel,由它统一管解析。
4. HTTPS 证书自动签发、自动续期,不用自己配。
解析生效一般几分钟到几小时。如果域名套了 Cloudflare,先关掉橙色云朵(代理)能避免校验失败。
===== 六、更新与回滚 =====
* 更新:重跑 CLI,或重新拖拽上传,产生一个新部署。
* 回滚:控制台 → Deployments → 找到旧部署 → 右侧 ⋯ → Promote to Production,秒级切回,无需重新构建。
常用命令:
<code bash>
vercel ls # 列出本项目的历史部署
vercel inspect <url> # 查看某次部署详情(产物、函数、耗时)
vercel logs <url> # 查看运行时日志
vercel rm <url> # 删除某次部署
vercel env add MY_KEY # 添加环境变量(生产 / 预览 / 开发 分环境)
vercel dev # 本地起一个接近线上的开发环境
vercel domains ls # 查看已绑定域名
</code>
===== 七、vercel.json:静态站点最常用的配置 =====
纯静态站点通常不需要它,需要下面几件事时再加:
cleanUrlsjson
{
"cleanUrls": true,
"trailingSlash": false,
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
],
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "X-Frame-Options", "value": "SAMEORIGIN" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
]
}
* :访问 /about 也能命中 about.html。
* rewrites:单页应用(SPA)刷新不 404 的经典做法——找不到的路径统一回退到 index.html。静态文件优先于 rewrites 生效,所以 CSS / JS 不会被误改写。
* headers:统一注入安全头,省得每页单独写,可参考 安全头。
注意:Git 集成部署时 vercel.json 必须提交进仓库才生效;CLI 上传时它待在本地目录里就够了。
===== 八、.vercelignore =====
语法跟 .gitignore 一样,用来排除不上传的文件,能明显加快上传:
<code>
node_modules
.env
*.log
/draft
</code>
依赖目录一般会被自动忽略,显式写一份更保险。环境变量务必用 vercel env add 管理,不要写进源码。
===== 九、常见坑 =====
1. 根目录没有 Logo.PNGindex.html → 访问根路径直接 404。上传的必须是“网站根目录”,不是它的上一级。
2. 文件名大小写:Windows / macOS 默认不区分大小写,Vercel 的 Linux 构建环境区分。 引用成 logo.png,本地正常、线上 404。
3. 绝对路径:部署在域名根下,写 /style.css 没问题;若要挂到子路径,改用相对路径或设置 base。
4. SPA 刷新 404:见上一节的 rewrites。
5. 免费(Hobby)计划限个人非商业用途,商业项目按条款需升级 Pro;且 Hobby 的函数区域固定、无法自选,国内访问延迟偏高。
6. 国内网络体验:Vercel 默认域名在国内不稳定,纯展示站可以接受;面向国内用户的服务建议同时准备国内节点或 CDN 方案。
7. 拖拽上传有体积上限,大项目走 CLI。
8. 预览环境(vercel)和正式环境(vercel –prod)是两套地址,别把预览地址当正式站发出去。
===== 十、最小可用流程回顾 =====
1. 邮箱注册 Vercel 账号(不需要 Git)
2. 本地准备好文件夹,根目录放 index.html
3. npm i -g vercel → vercel login
4. 在项目目录里执行 vercel –prod
5. 拿到 xxx.vercel.app,浏览器验证页面
6. 需要独立域名:Settings → Domains 绑定
7. 以后要更新:再跑一次 vercel –prod''
参考资料:Vercel 官网、官方文档、CLI 文档