从本地到云端：前端项目多平台部署全流程指南
前言
本文将完整记录一个 Vite 前端项目从本地开发，到 GitHub 代码托管，再到 Vercel、Netlify、Cloudflare Pages 三大平台部署的全过程。
一、本地准备与 GitHub 托管
这是部署的第一步，确保代码能稳定提交到云端。(注意这里项目名称是:project)
1. 本地项目初始化
# 创建 Vite 项目
npm create vite@latest project -- --template vue
cd project
npm install
2. 代码提交到 GitHub
# 初始化 Git 仓库
git init
git add .
git commit -m "Initial commit"
# 关联 GitHub 远程仓库
git remote add origin https://github.com/你的用户名/你的仓库名.git
git push -u origin main
二、Vercel 部署（常用方案）
Vercel 对前端框架的支持非常友好，但细节配置容易踩坑。
1. 基础部署步骤
-
访问 Vercel 官网，用 GitHub 账号登录。
-
点击
Add New→Project，选择你的 GitHub 仓库导入。 -
关键配置（解决子目录和依赖问题）：
- Root Directory：如果项目在子目录，需在此填写路径。
- Install Command：
npm install --registry=https://registry.npmmirror.com --legacy-peer-deps --force（这里加了镜像和强制） - Build Command：
npm run build - Output Directory：
dist
-
点击
Deploy完成部署。
2. 常见问题与解决方案
| 问题现象 | 错误原因 | 解决方法 |
ENOENT: Could not read package.json | Vercel 找不到项目配置文件 | 在 Root Directory 中填写子目录路径，如 amap-travel-assistant |
npm install 退出码 254/1 | 依赖安装超时或版本冲突 | 使用国内镜像源，添加 --legacy-peer-deps --force 强制安装 |
| 锁文件兼容性问题 | Windows 生成的 package-lock.json 在 Linux 环境报错 | 执行 npm install --package-lock-only 重新生成锁文件并提交 |
三、其他主流平台部署方案
除了 Vercel，这两个平台也非常适合前端项目部署。
1. Netlify 部署
-
登录 Netlify，导入 GitHub 仓库。
-
配置构建命令：
- Build command：
npm run build - Publish directory：
dist
- Build command：
-
点击
Deploy site完成部署。
2. Cloudflare Pages 部署
-
登录 Cloudflare Pages，连接 GitHub 仓库。
-
配置构建命令：
- Build command：
npm run build - Build output directory：
dist
- Build command：
-
点击
Save and Deploy完成部署。
四、部署踩坑总结与最佳实践
- 子目录项目必须配置根路径：如果代码不在仓库根目录，一定要在平台设置中指定
Root Directory。 - 锁文件必须提交：
package-lock.json是依赖安装的关键，缺失会导致部署失败。 - 依赖安装命令要优化：使用国内镜像源、添加强制安装参数，可大幅提升部署成功率。
- 避免使用缓存：重新部署时，务必取消勾选
Use existing Build Cache，确保环境干净。
同篇文章同步平台（内容一致，观感效果不同）
CSDN：
微信公众号：
bilibili：
