如何将Vite项目部署到Vercel？本地运行正常但部署失败求助

一、本地预检查（规避云端构建前置问题） #

• 先验证本地生产构建是否正常：执行npm run build（或对应包管理工具命令，如yarn build/pnpm build），确认项目根目录生成dist（或自定义输出）文件夹，打开其中的index.html确保页面能正常渲染。
• 配置Vite的base路径：
  若部署到根域名，保持base: '/'即可；若部署到子路径（如Vercel默认子域名、自定义子路径），修改vite.config.js：

  import { defineConfig } from 'vite'
  export default defineConfig({
    base: './', // 或具体子路径，如'/my-portfolio/'
  })
  

• 确保项目已推送到Git仓库（GitHub/GitLab/Bitbucket均可），.gitignore无需移除dist，Vercel会在云端自行构建。

二、Vercel平台部署操作 #

• 登录Vercel控制台，点击「New Project」，选择要部署的Git仓库并导入。
• 进入项目配置页，重点设置以下内容：
  • 构建命令：填写与本地一致的构建命令，如npm run build、pnpm build
  • 输出目录：填写Vite配置的输出目录，默认是dist；如果自定义了build.outDir，填对应的目录名
  • 环境变量：如果项目用到VITE_开头的环境变量，在此添加对应变量名和值（与本地.env.production保持一致）
• 点击「Deploy」启动部署流程。

三、常见失败原因及修复 #

• 依赖安装失败：
  • 项目根目录添加.nvmrc文件指定Node版本（如18.17.0），Vercel会自动匹配版本
  • 在package.json中添加packageManager字段指定包管理工具，如"packageManager": "pnpm@8.6.0"，避免Vercel自动选择错误工具
• 页面空白/资源404：
  • 检查vite.config.js的base配置是否与部署路径匹配，子路径场景下需设为相对路径./或具体子路径
  • 确认Vercel设置的「输出目录」与Vite的build.outDir一致
• 构建命令执行失败：
  • 确保本地执行相同构建命令能成功，排除代码本身的构建错误
  • 检查项目是否有未提交的依赖配置（如package-lock.json/pnpm-lock.yaml需同步推送到仓库）

内容的提问来源于stack exchange，提问作者Lambert Lee