Vercel 部署前后端分离项目，常见坑你踩了吗？

说实话，第一次把前后端分离的玩意儿扔到 Vercel 上，心里那叫一个忐忑。

本地跑得飞起，到了云端就像坐了过山车——哎呀妈呀，报错一大堆。

别慌，咱们慢慢来。先把思路理清楚，再一步步排查。

先确认环境变量到底配好了没

本地用了 .env，代码里靠 dotenv 注入。

在 Vercel 那边，你得手动点进去把同名的 Environment Variables 塞进去。

记得名字要一模一样，否则 process.env.xxx 拿不到值。

还有一点，小心别把 secret 暴露在 git commit 里。

不对不对，我是说别把 .env 文件直接推到仓库，要删掉再重新生成。

前端请求后端的路径要对

Vercel 的 rewrites 配置是关键。

Ru果你写成了

{
  "rewrites": 
}

记得 destination 必须指向你的 Serverless 函数入口文件。

有时候我忘记加 /api 前缀，结果请求根路径直接 404，真是尴尬。

跨域别忘了搞一下

本地开发时 Vite 的 proxy 帮了大忙，可上线后 proxy 不管用。

这时候后端需要加上 cors 中间件：

app.use)

Ru果忘了这一步，前端控制台会报 CORS 错误——哈哈，这种错误Zui常见。

Serverless 函数的入口必须是默认导出

Vercel 要求每个函数文件导出一个 handler。

写成 module.exports = handler 那也行，但一定要匹配 Vercel 的规范。

我有次写成 export const handler = …，结果部署成功但调用不到——不对不对，是因为没有 default 导出导致的。

.vercelignore 与 .gitignore 的区别

.gitignore 控制本地提交，.vercelignore 控制部署时哪些文件会被忽略。

Ru果你误把 node_modules 写进 .vercelignore，那 Vercel 打包时根本找不到依赖，一堆 “module not found”。

检查一下这个文件，确保只排除不需要的构建产物，比如 dist、*.log 等等。

构建脚本是不是写对了？

Pnpm、Yarn、npm 的 buildCommand 写法有细微差别。

Pnpm 默认禁用 postinstall 脚本，需要在 Vercel 设置 “pnpm approve-builds”。

Caution: Ru果你的项目依赖 esbuild，在 Vercel 上可Neng会被拦截。解决办法是显式打开它：

"buildCommand": "pnpm run build && pnpm approve-builds"

日志是排查的好帮手

别老想着 console.log 在本地kan，就以为线上也一样。

Vercel 有自己的日志系统，你Ke以在 Dashboard → Functions → Logs kan到每一次函数调用的输出。

If you forget to log something, you’ll see a blank page and wonder ***—哈哈，这种情况太常见了！

为什么百度不收录？

问题： 项目部署到 Vercel 后用百度搜索根本搜不到页面。

#1： 没有给页面加上 SEO 必要的 meta 标签，比如 title、description、canonical。

#2： Vercel 默认使用 Serverless 渲染，百度爬虫可Neng抓不到动态生成的内容。

#3： robots.txt 配置错误，把所有路径dou disallow 了。

解决办法： 在 vite.config.js 或者对应的框架插件里加入 SSR 或 pre‑render；确保 robots.txt 只屏蔽 /admin 等敏感目录；再提交 sitemap 给百度站长平台。说实话，这一步往往被忽视，却是导致“不收录”的根源之一。

排查思路：从表象到根源一步步逼近 1️⃣ kan Deploy Log

A：打开 Vercel 项目页面点 “Deployments”。

B：选Zui近一次部署，kan有没有红色报错或者警告。

C：常见错误包括 “Failed to install dependencies”，这通常是因为 package.json 里的 engine 指定版本和 Vercel 环境不匹配。

2️⃣ kan Function Log

D：点击 “Functions” → 对应函数名 → “Logs”。

E：搜索关键字比如 “Error” 或者你的接口路径。

If you see “ReferenceError: process is not defined”，说明环境变量没注入成功——回到第一步检查 Environment Variables！

3️⃣ 本地模拟 Serverless 环境

Pnpm run dev 本地跑时用 vercel dev 命令启动模拟环境，这样Ke以kan到跟线上几乎一致的请求路径和响应。

Mistake 常见：忘记在 vercel.json 里配置 “functions” 字段，让函数被当成静态资源处理。

4️⃣ 检查跨域和协议问题

a) 前端 fetch 时使用相对路径，而不是硬编码 http://xxx.com/api/…；这样在不同环境下douNeng自动适配。

b) 确认后端返回的 Access-Control-Allow-Origin 与前端 origin 完全匹配，否则浏览器会拦截请求——害，这种 bug hen隐蔽。

踩坑小贴士——老友提醒你别忘记这些细节！

- 环境变量名字大小写敏感，一定保持统一； - .env.example 用来记录必填项，不然新人接手会摸不着头脑； - Ru果你用了 TypeScript，要确保 tsconfig.json 包含所有路径别名，否则编译时报错“Cannot find module '@/*'”； - 部署前先跑一遍 `npm run lint && npm run build` 确保没有隐藏错误； - 想让搜索引擎抓到内容，Ke以考虑在 `vercel.json` 加入 `"outputDirectory": "dist"` 并开启静态导出； - Zui后一定要经常刷新页面缓存，有时候旧缓存会让你误以为 bug 仍然存在——哈哈，我就是这样浪费半天时间的！

调试也是一种修行嘛~

Sooo…调试过程其实挺像玩侦探游戏，你追踪线索、排除嫌疑人，然后终于锁定凶手。

Crap，Ru果还有奇怪的问题卡住你，就去社区翻翻 issue，有时候别人Yi经踩过同样的坑，只等你来发现而Yi。

© 2026 前端小伙伴分享  |  保持好奇  |  别太严肃

---