diff --git a/.env.example b/.env.example
index 78a3b72c..3fdc9bb0 100644
--- a/.env.example
+++ b/.env.example
@@ -13,4 +13,12 @@ ZEP_API_KEY=your_zep_api_key_here
 # 注意如果不使用加速配置，env文件中就不要出现下面的配置项
 LLM_BOOST_API_KEY=your_api_key_here
 LLM_BOOST_BASE_URL=your_base_url_here
-LLM_BOOST_MODEL_NAME=your_model_name_here
\ No newline at end of file
+LLM_BOOST_MODEL_NAME=your_model_name_here
+
+# ===== 前端部署配置 =====
+# 仅在使用源码部署并从非本机访问时需要设置
+# 对于远程服务器/VPS部署，必须设置为后端实际可访问的地址
+# 示例：VITE_API_BASE_URL=http://你的服务器IP:5001
+# 本地开发时默认使用 http://localhost:5001，无需设置
+# 注意：Vite开发服务器的代理配置(/api)仅在本地开发时有效，production构建后需设置此变量
+VITE_API_BASE_URL=http://localhost:5001
\ No newline at end of file
diff --git a/README-ZH.md b/README-ZH.md
index 0b20424d..76d98d8a 100644
--- a/README-ZH.md
+++ b/README-ZH.md
@@ -155,6 +155,15 @@ npm run dev
 - 前端：`http://localhost:3000`
 - 后端 API：`http://localhost:5001`
 
+> **远程部署说明：** 如果您从不同于运行MiroFish的机器（例如在VPS上）访问MiroFish，您必须在构建前端之前设置 `VITE_API_BASE_URL` 环境变量为您的服务器IP或域名。否则，前端会尝试连接浏览器本机的 `localhost:5001` 而不是服务器。
+>
+> ```bash
+> # 远程部署示例
+> VITE_API_BASE_URL=http://你的服务器IP:5001 npm run build
+> ```
+>
+> Vite开发服务器的代理配置（`/api` → `http://localhost:5001`）仅在本地开发模式下有效，在生产环境构建后需要设置此变量。
+
 **单独启动：**
 
 ```bash
diff --git a/README.md b/README.md
index 4b8369f4..8793267b 100644
--- a/README.md
+++ b/README.md
@@ -155,6 +155,15 @@ npm run dev
 - Frontend: `http://localhost:3000`
 - Backend API: `http://localhost:5001`
 
+> **Remote/VPS Deployment Note:** If you are accessing MiroFish from a different machine than where it's running (e.g., on a VPS), you must set the `VITE_API_BASE_URL` environment variable to your server's IP or domain before building the frontend. Without this, the frontend will try to connect to `localhost:5001` on the *browser's* machine instead of the server.
+>
+> ```bash
+> # Example for remote deployment
+> VITE_API_BASE_URL=http://YOUR_SERVER_IP:5001 npm run build
+> ```
+>
+> The Vite dev server proxy (`/api` → `http://localhost:5001`) only works in local development mode, not in production builds.
+
 **Start Individually:**
 
 ```bash