Vercel部署报错404：无法识别仓库中HTML/CSS/JS文件求助

第一步：明确项目类型与基础配置 #

不同技术栈的项目在Vercel上的部署逻辑差异很大，先对应检查：

• 纯静态HTML/CSS/JS项目：确保项目根目录存在index.html入口文件。如果你的静态文件在子目录，要在Vercel的「Build & Development Settings」里把「Output Directory」设为对应文件夹，而不是直接指定src（除非src里就是编译好的静态产物）。
• 需要构建的框架项目（React/Vue/Next.js等）：先看package.json里是否有build脚本，比如React的"build": "react-scripts build"。Vercel会自动执行这个脚本生成产物，你需要确保本地运行npm run build（或yarn build）能正常生成build/dist这类产物文件夹，然后在Vercel设置里把「Output Directory」设为这个产物路径。

第二步：核对Vercel部署配置细节 #

进入你Vercel项目的「Settings」→「Build & Development Settings」，逐一确认：

• Framework Preset：手动选择和你项目匹配的框架（如果Vercel没自动识别）。
• Root Directory：填包含package.json的根文件夹，不要选src（除非你的package.json在src内，这不符合常规项目结构）。
• Build Command：需要构建的项目填npm run build（对应你的包管理工具）；纯静态项目留空或填echo "Skip build"。
• Output Directory：填构建后产物的路径，比如React的build、Vue的dist，纯静态项目直接留空。

第三步：处理单页应用（SPA）的路由404 #

如果是SPA，刷新页面时出现404是典型问题，需要配置路由重写：
在项目根目录创建vercel.json文件，写入以下内容：

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

这个配置会让所有路由请求都指向index.html，交由前端路由处理。

第四步：本地验证排除项目自身问题 #

• 先在本地启动项目，确认所有页面能正常访问，无404。
• 运行构建命令生成产物后，用本地服务器（比如npx serve build）打开产物文件夹，验证本地访问构建后的文件没有问题，再重新部署到Vercel。

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