Vercel 中文教程：一条命令把本地网页发布成可访问的线上网址

一、速览：它是什么，解决什么问题

入门

你写好了一个网页，想让别人通过一个网址打开它，通常要买服务器、装环境、配域名，过程很繁琐。Vercel 就是替你把这些事做完的平台：你把代码交给他，他给你一个可以直接访问的网址。

配套的命令行工具（CLI，即在终端里敲命令来操作的程序）叫 vercel，装好之后，在项目文件夹里敲一条命令，几秒钟网站就上线了。

Vercel 项目开源仓库封面

二、安装前的准备

入门

安装之前需要先有 Node.js（一个让 JavaScript 能在电脑上运行的环境，npm 这个包管理器是随它一起装的），因为 vercel 命令是通过 npm 安装的。

建议使用 Node.js 18 或更高版本，太旧的版本可能跑不起来新版 CLI。可以在终端输入下面的命令检查：

node -v
npm -v

两个都能打印出版本号，就说明准备好了。没有装的话，去 nodejs.org 下载 LTS 版本安装即可。

三、安装 CLI

入门

标准安装方式是一条命令，装完后全局都能使用 vercel 命令：

npm i -g vercel

-g 表示全局安装，装完后你在任何目录敲 vercel 都能用，而不是只能在某个项目里用。

装好后验证一下：

vercel --version

能打印出版本号就算成功。如果提示找不到命令，通常是 npm 的全局路径没加进环境变量，重启一次终端通常能解决。

另外还有一种原生二进制版本（不依赖 Node.js 运行、直接编译好的可执行文件），启动更快。想换用它需要显式安装，并用 --force 让 npm 覆盖掉原来的命令链接：

npm i -g @vercel/vc-native --force

普通用户直接用 npm i -g vercel 就够了，原生版属于可选升级，两者用法一致，不会互相冲突。

四、核心命令：从登录到上线

入门

假设你有一个网页项目文件夹，里面至少要有一个 index.html。下面走一遍完整流程。

第一步：登录。 首次使用需要把 CLI 和你的 Vercel 账号绑定：

vercel login

它会问你用邮箱还是其他方式登录，按提示操作即可。这一步相当于给你的命令行领了一张"通行证"。

第二步：部署。 进入项目文件夹，执行：

cd /path/to/your/project
vercel

它会问几个问题（是否链接到已有项目、是否修改设置等），新手全部选默认即可。结束后会输出类似这样的结果：

✔  Production: https://your-project-xxxx.vercel.app

这个网址就是你网站的线上地址，发给别人就能打开。

第三步：正式部署到生产环境。 上面那条命令给的是预览地址，想让链接成为正式地址，加 --prod：

vercel --prod

其他常用命令：

vercel --version      # 查看版本
vercel ls             # 列出当前项目的部署记录
vercel pull           # 把云端的项目设置拉取到本地
vercel logs           # 查看某次部署的日志

vercel deploy 是 vercel 的完整写法，vercel deploy --prod 和 vercel --prod 效果一样。日常用短的就行。

五、配置：让部署更顺手

进阶 · 推荐细读

每次部署都回答一堆问题会很烦，可以在项目根目录建一个 vercel.json 文件来固定配置。比如指定网站入口文件：

{
  "buildCommand": "",
  "outputDirectory": "."
}

这样 CLI 就知道直接把当前目录的文件原样发布，不再猜测。

几个实用的命令行参数：

vercel --cwd=/path/to/project   # 不用 cd，直接指定要部署的目录
vercel --prod                   # 部署到正式环境
vercel --yes                    # 跳过所有交互提问，全部用默认值

在脚本或 CI（持续集成，即代码一推送就自动跑构建的流水线）里一定要加 --yes，否则命令会停下来等你输入，导致流程卡死。

如果想在服务器或 CI 上无人值守地部署，需要准备一个 Token（一串代表你身份的密钥字符串）和 Team ID（你的团队编号），在 vercel.com 的账户设置里生成，然后写进环境变量：

export VERCEL_TOKEN=你的token
export VERCEL_TEAM_ID=你的team-id

之后 CLI 就会自动用这两个值完成认证，不再要求登录。

六、踩坑：三个常见问题

进阶 · 推荐细读

1. 提示 401 或拉取部署失败。 这通常是项目的"部署保护"（Deployment Protection，即给预览地址加访问验证的功能）开着。去 Vercel 后台该项目的 Settings → Deployment Protection 里关掉它，CLI 才能正常下载构建产物。这条在自己搭建构建环境时尤其容易碰到。

2. 全局安装时提示 EEXIST 或命令冲突。 说明旧版本的 vercel 命令还占着位置。安装原生版时加上 --force 即可让 npm 覆盖旧链接：

npm i -g @vercel/vc-native --force

3. 部署上去是 404 或空白页。 多半是输出目录没对上。静态站点（纯 HTML/CSS/JS）可以在 vercel.json 里把 outputDirectory 指向放网页的文件夹；如果是 Next.js 等框架项目，CLI 会自动识别，不需要手动指定。

Vercel 项目主界面示意

七、自动化：推送代码就自动上线

深入 · 老手可选

最省事的方式其实是把仓库（代码库，存代码的地方）托管到 GitHub 上，在 vercel.com/new 导入这个仓库。之后每次 git push，Vercel 会自动构建并生成一个预览网址，合并进主分支后自动发布到正式网址，全程不需要手动敲命令。

如果想自己写脚本，把部署塞进 CI 流程也很简单：

npm i -g vercel
vercel --prod --yes --cwd=./dist

配合上一节的 Token 环境变量，这条命令可以放在任何 CI 里无人值守运行。也可以写成 shell 脚本，用 cron（Linux 自带的定时任务工具）定期执行，实现定时发布。

建议把 vercel.json 和 .vercel 目录的处理规则写进 .gitignore 的团队约定里：链接信息属于个人，密钥绝不能提交进仓库。

八、小结

回顾一下最短路径：npm i -g vercel 安装，vercel login 登录，vercel --prod 上线。日常开发时用不带 --prod 的版本看预览效果，满意了再发正式地址。等这套流程跑熟，再去看框架检测、环境变量、自定义域名这些进阶配置，会顺很多。

项目信息

项目	值
仓库	vercel/vercel
语言	TypeScript
Star	16,443
Fork	3,872
主页	https://vercel.com

参考链接

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

S.A.O