WHAT — Dev Companion (general)…

# React+Vite 项目部署 Vercel 白屏排查指南

一、错误本质分析

Cannot read properties of undefined (reading 'map') 表示代码对一个 undefined 值调用了 .map()，本质是数据在渲染时未就绪，而非部署工具问题。本地正常、线上白屏常见原因：环境变量缺失、接口跨域/未配置、构建环境差异。

二、逐步排查

1. 先看浏览器控制台和 Network

• F12 打开控制台，确认报错堆栈定位到哪个组件的 .map()
• 查看 Network 面板：接口请求是否 404 / CORS 失败 / 返回空数据

2. 检查环境变量（最高频原因）

• 本地用 .env.local 里的变量（如 VITE_API_URL）不会提交到 Git，Vercel 上读取后是 undefined
• 修复：Vercel 项目 Settings → Environment Variables 中添加以 VITE_ 开头的变量，添加后必须 Redeploy 才生效
• 注意：Vite 只注入 VITE_ 前缀变量，用 import.meta.env.VITE_XXX 读取

3. 检查 API 请求路径

• 线上接口若返回空或失败，初始 state 为 undefined 就会崩
• 临时修复（防御式编码）：

```jsx

{(items ?? []).map(item => ...)}

// 或

{Array.isArray(items) && items.map(...)}

```

4. 检查 Vercel 构建配置

• Framework Preset 选 Vite，Build Command npm run build，Output Directory dist
• 本地先执行 npm run build && npm run preview 验证构建产物是否正常

5. 若是刷新子路由白屏

• 需在项目根目录添加 vercel.json 配置 SPA 回退：

```json

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

```

三、推荐处理顺序

1. 本地 npm run build && npm run preview 复现问题

2. 补齐 Vercel 环境变量并重新部署

3. 给所有 .map() 前的数组加默认值兜底

4. 检查接口跨域与返回数据结构

按此顺序排查，90% 以上此类白屏可解决。若仍报错，把控制台完整堆栈贴出可进一步定位。