在 macOS 上安装 Vercel CLI 需先安装 Node.js（含 npm），再执行 npm install -g vercel，接着 vercel login 授权账户，最后进入项目目录运行 vercel 完成部署。

如果您在 macOS 系统上需要安装 Vercel CLI 工具以实现项目部署、预览与管理，则可能是由于本地缺少 Node.js 运行时或未正确配置全局命令环境。以下是完成安装与基础使用的具体步骤：

一、确认并安装 Node.js 与 npm

Node.js 是运行 Vercel CLI 的底层依赖，macOS 默认不预装该环境，必须显式安装；npm 随 Node.js 自动集成，用于包管理与 CLI 安装。

1、访问 https://nodejs.org 下载 LTS 版本的 macOS 安装包（.pkg 格式）。

2、双击安装包，按向导完成安装，期间允许系统权限请求。

3、打开终端，执行 node -v && npm -v，确认输出类似 v20.13.1 和 10.5.2 的版本号。

二、全局安装 Vercel CLI

Vercel CLI 提供命令行接口，支持从任意项目目录触发部署、登录账户、查看日志等操作；必须通过 npm 全局安装才能在系统任意路径调用 vercel 命令。

1、在终端中执行 npm install -g vercel，等待安装完成。

2、执行 vercel -v，验证是否输出有效版本号（如 39.2.0）。

3、若提示权限错误（EPERM 或 EACCES），请勿使用 sudo，改用 npm config set prefix ~/.local 后重新安装。

三、登录 Vercel 账户并绑定身份

CLI 需与 Vercel 平台账户关联，方可访问项目配置、部署权限及团队空间；登录过程通过浏览器 OAuth 授权完成，凭证保存于本地 ~/.vercel 目录。

1、终端执行 vercel login，自动打开默认浏览器跳转至 Vercel 登录页。

2、选择 GitHub、GitLab、Bitbucket 或邮箱方式登录，完成授权后页面显示 “Success”。

3、返回终端，确认提示 “Logged in as your-email@example.com”。此时 ~/.vercel/config.json 已生成有效令牌。

四、初始化并部署本地项目

首次部署时，Vercel CLI 会自动检测框架类型（Next.js、Nuxt、Static 等），生成部署配置并上传构建产物；无需手动编写 vercel.json 即可完成基础部署。

1、进入项目根目录，确保包含 package.json 或框架特有文件（如 next.config.js、nuxt.config.ts）。

2、执行 vercel，按提示选择团队（Personal 或所属 Team）、项目名称、部署环境（Preview 或 Production）。

3、等待构建日志滚动结束，最终输出 Deployed to https://xxx.vercel.app 即表示成功。

五、配置项目级 vercel.json（可选进阶）

当默认自动检测无法满足定制需求（如自定义构建命令、环境变量注入、重写路由规则）时，需手动创建 vercel.json 文件，覆盖 CLI 推断行为。

1、在项目根目录新建文件 vercel.json，使用 UTF-8 编码保存。

2、填入最小合法结构：{"version": 2, "builds": [{"src": "package.json", "use": "@vercel/next"}]}（Next.js 项目示例）。

3、若为纯静态站点，将 use 替换为 @vercel/static-build，并确保 public/ 或 dist/ 目录存在可部署资源。