部署预览：Vercel 与环境变量

这一课你将能做到

1. 把 React 项目部署到 Vercel，获得公开访问的 URL
2. 配置环境变量，区分开发和生产环境的敏感配置
3. 理解 CI/CD 基础流程，实现 push 代码自动部署

为什么要学

代码在自己电脑上跑得再好，别人看不到等于没做。部署是把项目发布到服务器，让任何人通过 URL 访问。对初学者来说，部署是「作品上线」的最后一公里——面试官、朋友、用户，都需要一个能点开的链接。

传统部署要买服务器、配 Nginx、传文件，门槛高。现代平台（Vercel、Netlify）把这变成了「连接 GitHub，点一下按钮」——push 代码就自动构建部署，还有免费额度、HTTPS、全球 CDN。

先建立图像

本地开发                    部署后
localhost:5173        →     https://my-app.vercel.app
    ↓                          ↑
git push ──→ GitHub ──→ Vercel 自动构建 ──→ 全球 CDN
                              ↑
                        环境变量注入

Vercel 的工作流：监听 GitHub 仓库 → 检测到 push → 拉代码 → npm install → npm run build → 把 dist 目录发布到 CDN。

跟着做

步骤 1：准备项目

确保上一课的待办项目已推送到 GitHub：

git add .
git commit -m "完成待办清单应用"
git push origin main

确认 package.json 有 build 脚本：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

本地验证构建：

npm run build
npm run preview

npm run build 会生成 dist/ 目录，里面是优化后的静态文件。npm run preview 在本地预览构建结果。

步骤 2：部署到 Vercel

1. 访问 vercel.com，用 GitHub 账号登录
2. 点击 Add New → Project
3. 在仓库列表中找到 todo-app，点击 Import
4. Vercel 自动检测到 Vite 项目，配置已预填：
   • Framework Preset: Vite
   • Build Command: npm run build
   • Output Directory: dist
5. 点击 Deploy

等待 1-2 分钟，部署完成后获得 URL：https://todo-app-xxxx.vercel.app。

步骤 3：自动部署（CI/CD）

部署后，Vercel 自动配置了 CI/CD：

# 本地修改代码
echo "// 添加新功能" >> src/App.jsx

# 提交并推送
git add .
git commit -m "更新界面"
git push origin main

push 后打开 Vercel 控制台，会看到新的部署自动触发，1-2 分钟后线上更新。这就是 CI/CD：持续集成（自动构建测试）+ 持续部署（自动发布）。

预览部署：创建 PR 时，Vercel 会为每个 PR 生成独立的预览 URL，合并前可以先看效果。

步骤 4：环境变量

项目中调用 API 时，密钥不能直接写死在代码里（会推送到 GitHub 泄露）。用环境变量管理：

本地开发，创建 .env.local（已默认在 .gitignore 中）：

VITE_API_URL=https://api.example.com
VITE_API_KEY=dev-key-12345

代码中读取（Vite 要求 VITE_ 前缀）：

const apiUrl = import.meta.env.VITE_API_URL;
const apiKey = import.meta.env.VITE_API_KEY;

fetch(`${apiUrl}/data?key=${apiKey}`);

Vercel 生产环境配置：

1. Vercel 项目 → Settings → Environment Variables
2. 添加 VITE_API_URL = https://api.example.com
3. 添加 VITE_API_KEY = prod-key-67890（生产密钥）
4. 重新部署生效（Deployments → 最新一条 → ⋯ → Redeploy）

环境分类：

• Production：main 分支部署用
• Preview：PR 预览部署用
• Development：vercel dev 本地用

步骤 5：自定义域名

1. Vercel 项目 → Settings → Domains
2. 输入你的域名（如 todo.yourdomain.com）
3. 按提示到域名服务商（阿里云/Cloudflare）添加 DNS 记录：
   • 类型：CNAME
   • 名称：todo
   • 值：cname.vercel-dns.com
4. 等待 DNS 生效（几分钟到几小时），Vercel 自动配置 HTTPS

步骤 6：Netlify 备选方案

Netlify 是 Vercel 的主要竞争对手，流程几乎一样：

1. netlify.com → Add new site → Import from Git
2. 选择 GitHub 仓库
3. Build command: npm run build，Publish directory: dist
4. Deploy

差异对比：

特性	Vercel	Netlify
最适合	Next.js（同公司）	通用静态站
免费带宽	100GB/月	100GB/月
Serverless 函数	支持	支持
表单处理	无	内置

讲清楚要点

1. 静态部署 vs 服务器部署：React 构建产物是纯静态文件（HTML/CSS/JS），不需要 Node 服务器，放 CDN 即可。这也是 Vercel/Netlify 免费的原因。
2. 环境变量不进 Git：.env.local 必须在 .gitignore 中。密钥泄露到 GitHub 会被机器人扫描盗用（尤其是云服务密钥）。
3. 构建时注入 vs 运行时注入：Vite 的环境变量是构建时写进代码的，改环境变量要重新构建部署。真正的运行时配置需要后端接口下发。
4. CI/CD 的核心价值：消除「在我电脑上能跑」的问题，统一构建环境；自动部署消除手动传文件的错误和繁琐。
5. 预览部署改变协作方式：每个 PR 有独立 URL，设计师、产品、测试可以直接看效果，不用猜代码长什么样。

你可能会懵的地方

• 为什么 build 后就能直接访问，不需要服务器？ React SPA 是静态文件 + 浏览器端路由。CDN 返回 index.html，JS 接管后续渲染。唯一的「服务器」是存文件的 CDN。

• Vercel 免费额度够用吗？ 个人项目完全够：100GB 带宽/月、无限静态部署。商用项目流量大了才需要付费。

• 为什么我的 API 密钥在构建产物里能看到？ 前端环境变量最终都会打包进 JS，任何人按 F12 都能看到。前端环境变量不能存真密钥，只能存公开配置（API 地址、公开 key）。真密钥必须放后端。

• 路由刷新 404 怎么办？ SPA 用浏览器路由（如 /about），直接访问时服务器找不到对应文件。Vercel 需配置重写规则：项目根目录建 vercel.json：

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

• Vercel 国内访问慢？ Vercel 的 CDN 在国内没有节点，访问不稳定。面向国内用户的项目用国内平台（如腾讯云 EdgeOne、阿里云 OSS+CDN）或自建服务器。

错法对照

错法	问题	正解
把 .env.local 提交到 Git	密钥泄露	确认 .gitignore 包含 .env*
前端环境变量存数据库密码	任何人 F12 可见	前端只存公开配置，密钥放后端
改了环境变量不重新部署	构建时注入，不生效	重新触发部署
本地能跑线上白屏	路径大小写、环境变量缺失	看浏览器 Console 和 Vercel 构建日志
直接访问 /about 报 404	SPA 路由未配置重写	配置 vercel.json rewrites
手动 FTP 传文件部署	易出错、无版本管理	Git 触发的自动部署
API 请求写死 localhost	线上请求失败	用环境变量区分环境

卡点急救

1. 构建失败：Vercel 控制台看 Build Logs，常见原因：本地没跑过 npm run build、依赖在 devDependencies 但构建需要、Node 版本不一致（Settings → General → Node.js Version）。
2. 页面白屏：浏览器 Console 看报错，多半是资源路径 404（检查 vite.config.js 的 base 配置）或环境变量 undefined。
3. 环境变量没生效：检查变量名是否有 VITE_ 前缀；检查是否重新部署；确认代码用 import.meta.env.XXX 而不是 process.env.XXX。
4. 域名不生效：DNS 生效需要时间，用 nslookup todo.yourdomain.com 检查解析是否指向 Vercel。

面试常问

• CI/CD 是什么？ 持续集成（CI）：代码提交后自动构建、跑测试，尽早发现问题。持续部署（CD）：构建通过后自动发布到服务器。Vercel 把这两步合并成「push 即部署」。

• 前端环境变量安全吗？ 不安全。所有前端环境变量最终都打包进 JS 文件，用户可见。敏感密钥必须放后端，前端通过后端接口间接使用。

• SPA 部署需要注意什么？

  1. 路由重写规则（所有路径返回 index.html）；2) 静态资源缓存策略（带 hash 的文件长缓存，index.html 短缓存）；3) HTTPS；4) CDN 加速。

• Vercel 和传统服务器部署的区别？ 传统：买服务器 → 装环境 → 传文件 → 配 Nginx → 手动更新。Vercel：连 Git 仓库 → push 自动构建部署 → 全球 CDN + HTTPS 开箱即用。前者灵活可控，后者省事高效。

自测三问

1. 为什么 React 项目构建后可以直接部署到 CDN，而不需要 Node 服务器？
2. 本地开发连测试 API、线上连正式 API，应该怎么配置？写出关键代码。
3. 同事说「我改了环境变量但线上没生效」，你会怎么排查？

小结一句话

部署不再是运维的专利：Git push 触发自动构建、环境变量管理配置、CDN 全球分发——现代平台让初学者也能拥有企业级的发布流程。

延伸

• Vercel 官方文档
• 下一课：路线图对照——梳理前端知识体系，规划进阶方向。