如何将React应用部署到Vercel/Render等托管平台？部署遇错求助

Vercel部署问题排查 #

• 构建命令/输出目录配置错误
  Vercel默认会识别Create React App或Vite项目，但如果自定义了构建流程，需手动配置：

  • Create React App：构建命令设为npm run build，输出目录填build
  • Vite：构建命令设为npm run build，输出目录填dist
    进入Vercel项目的「Build & Development Settings」页面核对配置，确保和本地构建逻辑一致。

• 依赖安装失败

  • 检查package.json里的依赖版本，优先用稳定版，避免依赖冲突
  • 若使用私有包，需在Vercel配置对应访问权限；无私有包的话，可删除package-lock.json/yarn.lock后重新提交，再尝试部署
  • 推荐用npm ci代替npm install加快依赖安装（需确保锁文件存在）

• 环境变量缺失
  React项目中以REACT_APP_开头的环境变量，必须在Vercel项目的「Environment Variables」页面添加，且要勾选「Production」环境，否则生产部署时会出现变量未定义错误。

• SPA路由刷新404
  用React Router的单页应用刷新页面会返回404，需在项目根目录创建vercel.json，添加以下配置：

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

Render部署问题排查 #

• 构建配置错误
  在Render的静态网站部署设置中，正确填写：

  • Create React App：构建命令npm run build，发布目录build
  • Vite：构建命令npm run build，发布目录dist
    若自定义构建脚本，确保脚本能将静态文件生成到指定目录。

• 构建超时
  Render免费版构建时长有限，可通过以下方式优化：

  • 清理项目中不必要的依赖，减少构建体积
  • 用npm ci代替npm install，加快依赖安装速度

• SPA路由404
  在Render的静态网站设置中找到「Redirects/Rewrites」，添加规则：

  • 源路径：/*
  • 目标路径：/index.html
  • 类型：选「Rewrite」

• Node.js版本不兼容
  在package.json中添加engines字段指定Node.js版本，比如：

  "engines": {
    "node": ">=16.0.0 <19.0.0"
  }
  

  确保平台使用的Node.js版本和本地开发环境一致，避免版本差异导致的错误。

通用排查步骤 #

1. 本地预构建测试
   先在本地运行npm run build生成静态文件，再用npx serve build（或npx serve dist）启动服务，确认本地能正常访问，排除项目本身的构建问题。
2. 查看构建日志
   部署失败后，一定要查看平台提供的构建日志，日志会明确标注错误原因（比如语法错误、依赖缺失、环境变量未配置等），根据日志定位问题是最直接的方法。

内容的提问来源于stack exchange，提问作者Rohit kumar