Vercel 部署完全指南 / A Complete Guide to Vercel Deployment

这篇文档解释了前端部署的核心概念，理解从本地开发到线上生产的完整流程。

1. 开发命令 vs 构建命令

为什么平时用 `npm run dev`？

你在本地开发时，代码是"生"的。为了让你改一行代码就能立刻看到效果，Vercel（或 Vite）会启动一个开发服务器：

实时编译：代码变动立即更新
调试工具：包含丰富的开发调试功能

缺点：运行效率低，文件体积巨大，不能直接丢给浏览器运行。

为什么部署要用 `npm run build`？

部署到线上时，我们需要把代码做成"罐头"——也就是构建（Build）。打包工具（如 Vite）会做以下几件事：

步骤	说明
压缩 (Minify)	把长变量名变成 a, b, c，删掉所有空格和注释
转换 (Transpile)	把 TypeScript 或 ES6+ 语法转成普通 JS
打包 (Bundle)	把几百个小文件合并成几个大文件

2. Vercel 部署的三个核心参数

当你把项目导入 Vercel 时，需要确认这三个配置：

① Build Command（构建命令）

默认值：npm run build（Nuxt 3 是 npx nuxi build）
作用：告诉 Vercel 把源代码变成可以上线的成品

② Output Directory（输出目录）

默认值：dist、.output 或 build（Nuxt 3 通常是 .output/public）
作用：构建完成后，生成一个文件夹，里面装满了压缩后的 HTML、JS 和 CSS
关键：Vercel 会把这个文件夹里的内容推送到全球 CDN

③ Install Command（安装命令）

默认值：npm install
作用：在构建之前，下载 package.json 里记录的所有依赖包

3. 什么是 dist 文件夹？

dist 是 Distribution（发布/分发） 的缩写。

它是 npm run build 执行后的产物
通常会被列入 .gitignore，不应该提交到 GitHub

自动化部署流程

1. 你提交 src 源代码到 GitHub
2. Vercel 监测到更新，拉取源代码
3. Vercel 在它的服务器上跑 npm run build
4. Vercel 自动生成 dist（或 .output），然后发布到 CDN

4. 针对 Nuxt 3 项目

Nuxt 3 是全栈框架，生成的产物通常在 .output 文件夹里：

模式	输出目录
纯静态 (SSG)	`.output/public`
SSR (服务端渲染)	Vercel 自动识别并转化为 Serverless Functions

5. 源代码 vs 产物（核心概念）

你的直觉非常精准：部署的永远是"产物"，而不是源代码！

	源代码 (Source)	产物 (Artifacts)
内容	TypeScript、Vue 组件、注释、空格	纯粹的 index.html、main.js、style.css
用途	给人看	给机器看
浏览器	看不懂 .vue 文件	直接运行

Vercel 扮演的角色

Vercel 就像一个"全自动工厂"：

把仓库代码拉过去
在虚拟机里跑 npm run build
把生成的文件夹里的内容分发到全球 CDN

为什么 Vercel 看起来像"自动"的？

因为 Vercel 内置了主流框架的预设（Framework Preset）：

扫描到 nuxt.config.ts → 自动识别为 Nuxt 3 项目
自动填好 Build Command 和 Output Directory

6. 分支部署逻辑

Main 分支 → Production（生产环境）

当你 push 到 main 分支（或通过 PR 合并）
Vercel 立刻启动"工厂"重新打包
正式域名会立刻更新

Dev 分支 → Preview（预览环境）

当你 push 到 dev 分支
Vercel 也会打包，但不更新正式域名
生成临时链接：project-git-dev-user.vercel.app
意义：可以在真机上测试新功能，不影响正式用户

Vercel 后台改参数 → Redeploy

比如修改环境变量 API_URL
Vercel 会提示"需要重新部署"
点击 Redeploy，用现有代码重新打包

7. 一个容易踩的坑：环境变量

如果你在前端代码里写 process.env.API_URL：

这个变量必须在 构建（Build） 那一刻就存在
构建完后，JS 已变成静态文件
部署完后再改环境变量：必须重新部署一次

总结

命令/概念	说明
`npm run dev`	开发环境，边写边看
`npm run build`	生产环境，压缩打包
`dist` / `.output`	打包后的成品，真正给用户看的东西
Main 分支 push	触发 Production 部署
Dev 分支 push	触发 Preview 部署
改环境变量	触发 Redeploy

Vercel 部署完全指南 / A Complete Guide to Vercel Deployment ​

1. 开发命令 vs 构建命令 ​

为什么平时用 npm run dev？ ​

为什么部署要用 npm run build？ ​

2. Vercel 部署的三个核心参数 ​

① Build Command（构建命令） ​

② Output Directory（输出目录） ​

③ Install Command（安装命令） ​

3. 什么是 dist 文件夹？ ​

自动化部署流程 ​

4. 针对 Nuxt 3 项目 ​

5. 源代码 vs 产物（核心概念） ​

Vercel 扮演的角色 ​

为什么 Vercel 看起来像"自动"的？ ​

6. 分支部署逻辑 ​

Main 分支 → Production（生产环境） ​

Dev 分支 → Preview（预览环境） ​

Vercel 后台改参数 → Redeploy ​

7. 一个容易踩的坑：环境变量 ​

总结 ​