diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index ff508b6..32d8ff6 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -385,6 +385,7 @@ docker compose -f docker-compose.prod.yml exec backend bash
 
 | 现象 | 排查方向 |
 |------|---------|
+| **前端构建报 `JavaScript heap out of memory`** | V8 堆上限过低（VPS 内存小）。镜像已设 `NODE_OPTIONS=--max-old-space-size=2048`；若仍失败需加 swap，见下方「构建内存不足」 |
 | 浏览器白屏 / 404 | 前端容器是否运行：`curl -I http://127.0.0.1:8080`；Nginx `location /` 是否转发到 8080 |
 | 刷新 `/chat` 等子路由 404 | 前端容器 `nginx.conf` 是否有 `try_files $uri $uri/ /index.html`（已内置） |
 | 登录后无法收消息 / 一直转圈 | WebSocket 未通：检查 `wss://www.e4s.world/ws`；确认 Nginx `/ws` 块有 `proxy_http_version 1.1` + `Upgrade`/`Connection` 头 |
@@ -394,6 +395,32 @@ docker compose -f docker-compose.prod.yml exec backend bash
 | `compose` 报「请在 .env.prod 中设置…」 | 漏了 `--env-file .env.prod`，或 `.env.prod` 里对应变量为空 |
 | 改了 `.env.prod` 没生效 | 见 [第 12 节](#12-更新--重新部署) 关于「首次启动写入」的说明 |
 
+### 构建内存不足（前端 `JavaScript heap out of memory`）
+
+`npx vite build` 打包含 echarts 等大依赖的项目较吃内存。在内存小的 VPS 上，Node 会按可用内存把 V8 堆上限设得很低（如 ~476MB），导致打包到一半 OOM —— 这是 **V8 自身的堆限制**，不是系统内存不足，**加 swap 并不能单独解决**，必须提高堆上限。镜像内已通过 `ENV NODE_OPTIONS=--max-old-space-size=2048` 处理；若物理内存确实偏小，建议同时加 swap 防止内核 OOM：
+
+```bash
+# 查看当前内存（若可用 < 1GB，强烈建议加 swap）
+free -h
+
+# 创建 2GB swap 并启用（一行执行）
+sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
+
+# 持久化（重启后仍生效）
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# 验证（Swap 一行应显示约 2G）
+free -h
+```
+
+> 若 `fallocate` 不可用或报错，改用 `sudo dd if=/dev/zero of=/swapfile bs=1M count=2048` 创建。
+
+加完 swap 后，回到项目目录重新构建（只重建前端即可）：
+
+```bash
+docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build frontend
+```
+
 ---
 
 ## 15. 已知限制（架构层面）
diff --git a/frontend/Dockerfile.prod b/frontend/Dockerfile.prod
index 01c681f..e50c073 100644
--- a/frontend/Dockerfile.prod
+++ b/frontend/Dockerfile.prod
@@ -22,6 +22,11 @@ RUN npm install
 # 复制源码（frontend/.dockerignore 已排除 node_modules / dist / .env 等）
 COPY . .
 
+# Vite 打包（含 echarts / vue-echarts / naive-ui 等大依赖）较吃内存。
+# 显式调高 V8 堆上限，避免在内存受限的 VPS 上报 "JavaScript heap out of memory"。
+# 此值只是「允许上限」，V8 仅按需占用；若 VPS 物理内存很小，仍需加 swap（见 DEPLOYMENT.md）。
+ENV NODE_OPTIONS="--max-old-space-size=2048"
+
 # 直接调用 vite build，跳过 vue-tsc 类型检查
 # （避免仓库中既有的类型错误阻断生产部署；类型检查请在 CI / 发布前单独执行）
 # 如需严格的类型门禁，可改为 `npm run build`。