Daotin

使用 Vercel 部署前端项目

前端

在 Vercel 部署 Vite + Vue 前端

本文档包含两种最简部署方式：通过 Git 在 Vercel 控制台导入（推荐）与使用 Vercel CLI 本地部署。项目为 Vite + Vue，默认构建产物目录为 dist，Vercel 能自动识别。

方式一：通过 Git 在 Vercel 控制台部署（推荐）

  1. 将项目推送到 GitHub/GitLab/Bitbucket（以 GitHub 为例）
bash
git init
git add -A
git commit -m "chore: init vite+vue"
git branch -M main
git remote add origin <https://你的git仓库.git>
git push -u origin main
  1. 在 Vercel 控制台创建项目
  • New Project → 选择刚推送的仓库进行 Import。
  1. 首次导入时的构建设置（通常会被自动识别）
  • Framework Preset: Vite
  • Install Command: npm ci（或保留默认）
  • Build Command: npm run build
  • Output Directory: dist
  1. 如需配置环境变量：Settings → Environment Variables 添加。
  2. 点击 Deploy，等待构建完成。之后只要向主分支推送代码，Vercel 会自动触发重新部署。

方式二：使用 Vercel CLI 本地部署

  1. 安装并登录 CLI
bash
npm i -g vercel
vercel login
  1. 在项目根目录执行部署
  • 交互式首发（自动创建并绑定 Vercel 项目）：
bash
vercel
  • 或非交互直接发布到生产（使用默认 Vite 设置）：
bash
vercel --prod --yes
  1. 之后更新上线只需：
bash
vercel --prod
使用vercel cli部署的话，有哪些常用的指令？
指令主要用途
vercel login登录 Vercel 账户。这是你首先需要运行的命令。它会通过浏览器打开一个认证页面，授权 CLI 访问你的账户。
vercel link连接本地目录到 Vercel 项目
vercel dev在本地模拟 Vercel 环境进行开发
vercel部署一个预览版本
vercel –prod部署到生产环境
vercel logs …查看实时日志
vercel env pull拉取云端环境变量到本地
vercel env add …添加环境变量
vercel 和 vercel –prod 有什么区别？
  • vercel（默认）：部署的是一个 Preview Deployment（预览环境）。 每次运行都会生成一个唯一的 URL（通常是 xxxx.vercel.app，带随机前缀）。主要用于测试、预览、联调，不会覆盖正式生产环境。常见于 CI/CD 中，每次提交 PR 时都会生成一个对应的 preview 链接。
  • vercel --prod：部署的是 Production Deployment（生产环境）。会将代码部署到主域名（例如 yourproject.vercel.app，以及你绑定的自定义域名）。部署结果会覆盖原来的生产版本，影响真实用户访问。一般在确认代码没问题后才使用。
vercel部署指令区别
命令构建地点上传内容是否部署使用场景
vercel --prod云端源码✅ 部署默认方式，最快捷，适合开发者本地直接上线
vercel build --prod本地.vercel/output❌ 不部署本地调试构建、验证产物
vercel deploy --prebuild --prod --archive=tgz本地.vercel/output 打包上传✅ 部署CI/CD、保证环境一致、文件多时加速

可以这么理解：

  • vercel --prod = 云端构建 + 部署
  • vercel build --prod = 本地构建，不部署
  • vercel deploy --prebuild --prod --archive=tgz = 本地构建 + 部署（产物打包上传）

可选：history 路由刷新 404 处理

若使用 Vue Router 的 history 模式，非根路径刷新可能出现 404。可在仓库根目录添加 vercel.json：

json
{
  "rewrites": [{ "source": "/(.*)", "destination": "/" }]
}

本地自检（建议首次部署前执行）

bash
npm ci
npm run build
npm run preview -- --host --port 4173

浏览器访问 http://localhost:4173 验证构建结果无误后再部署。

在 Vercel 部署 Node.js 后端

部署 Node.js 后端与部署前端静态应用在理念上有根本不同。前端是 静态文件托管 (CDN)，而后端则是 无服务器函数 (Serverless Functions)。

核心区别：前端 vs 后端

特性前端 (Vite/Vue)后端 (Node.js)
部署产物静态文件 (HTML, CSS, JS)Serverless Function(s)
Vercel 角色CDN 内容分发网络FaaS (Function as a Service) 平台
核心配置Output Directory: distapi 目录约定或 vercel.json
package.jsonbuild 脚本最重要dependencies 必须正确
vercel.json 重写用于处理客户端路由 (SPA 刷新)用于将 API 请求映射到后端函数
运行模式构建后不再执行代码按需唤醒，事件驱动

方式一：零配置部署（推荐）

Vercel 遵循“约定优于配置”的原则。如果你遵循其项目结构约定，则 无需 vercel.json 文件。

  1. 创建 api 目录：在项目根目录下创建一个名为 api 的文件夹。
  2. 创建函数文件：在 api 目录中创建 JavaScript (.js) 或 TypeScript (.ts) 文件。每个文件都是一个独立的 API 端点。
  • api/index.js -> 映射到 /api
  • api/users.js -> 映射到 /api/users
  • api/posts/all.js -> 映射到 /api/posts/all
  1. 导出处理函数：每个文件必须导出一个默认函数，该函数接收请求 (req) 和响应 (res) 对象，类似于 Express。

示例 api/user.js:

javascript
export default function handler(req, res) {
  const { name = 'Guest' } = req.query;
  res.status(200).send(`Hello,${name}!`);
}

部署后，访问 https://your-project.vercel.app/api/user?name=Alex 即可看到结果。

方式二：使用 vercel.json 自定义配置

当你无法或不想遵循 api 目录的约定时（例如，你的后端代码在 src 目录，或者你想将整个 Express 应用打包成一个函数），就需要使用 vercel.json 来明确告诉 Vercel 如何构建和路由你的项目。

什么时候不需要 vercel.json？

当你的项目完全符合 Vercel 的预设时，就不需要此文件：

  • 使用主流前端框架（如 Vite, Next.js）。
  • 后端逻辑完全遵循 api 目录约定。
  • 纯静态 HTML 网站。

vercel.json 常用配置项

1. builds (构建规则)

  • 作用：覆盖 Vercel 的默认构建行为，指定源文件和构建器。
  • 场景：当你的主入口文件不在 api 目录下时。
    json
    {
  "builds": [
    {
      "src": "src/index.js",
      "use": "@vercel/node"
    }
  ]
}

2. rewrites (重写)

  • 作用：服务器内部路径映射，浏览器地址栏 URL 不变。
  • 场景：API 路由代理。将所有 /api/* 的请求都交给 src/index.js 处理。
    json
    {
  "rewrites": [{ "source": "/api/(.*)", "destination": "/src/index.js" }]
}

3. redirects (重定向)

  • 作用：将请求重定向到新 URL，浏览器地址栏 URL 改变。
  • 场景：页面迁移。
    json
    {
  "redirects": [{ "source": "/old-path", "destination": "/new-path", "permanent": true }]
}

4. headers (自定义响应头)

  • 作用：为匹配的路径添加 HTTP 响应头。
  • 场景：配置 CORS 策略。
    json
    {
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [{ "key": "Access-Control-Allow-Origin", "value": "*" }]
    }
  ]
}

5. crons (定时任务)

  • 作用：按 Cron 表达式定时触发 Serverless Function。
  • 场景：每天凌晨执行数据同步。
    json
    {
  "crons": [
    {
      "path": "/api/cron/sync-data",
      "schedule": "0 0 * * *"
    }
  ]
}

6. functions (函数配置)

  • 作用：为特定函数覆盖默认配置，如内存和超时时间。
  • 场景：延长某个耗时任务的执行时间。
    json
    {
  "functions": {
    "api/heavy-task.js": {
      "maxDuration": 30,
      "memory": 1024
    }
  }
}

vercel如何使用单域名统一部署monorepo前后端？

方案：：使用 vercel.json 编排 Monorepo 部署

json
{
  "version": 2,
  "installCommand": "pnpm install",
  "buildCommand": "pnpm build",
  "builds": [
    { "src": "packages/server/api/**/*.ts", "use": "@vercel/node" },
    {
      "src": "packages/web/package.json",
      "use": "@vercel/static-build",
      "config": { "distDir": "dist" }
    }
  ],
  "rewrites": [
    { "source": "/api/(.*)", "destination": "/packages/server/api/$1.ts" },
    { "source": "/(.*)", "destination": "/packages/web/$1" }
  ]
}

Related posts