diff --git a/.gitignore b/.gitignore
index 337e6503..6803d691 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,8 @@ frontend-web/.vscode/
 
 # Frontend local/runtime artifacts
 frontend-web/.env
+frontend-web/.env.local
+frontend-web/.env.*.local
 frontend-web/node_modules/
 frontend-web/.pnpm-store/
 frontend-web/tsconfig.tsbuildinfo
diff --git a/frontend-web/.env.development b/frontend-web/.env.development
new file mode 100644
index 00000000..0d15230d
--- /dev/null
+++ b/frontend-web/.env.development
@@ -0,0 +1,12 @@
+# 本地开发（pnpm dev）— 与原先 .env 保持一致
+# 个人覆盖请新建 .env.development.local（已 gitignore，优先级更高）
+
+# Gateway / DeerFlow API
+VITE_BACKEND_BASE_URL=http://127.0.0.1:8001
+VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
+
+# 轻应用「新建笔记」系列接口
+VITE_NOTE_API_BASE_URL=http://47.88.25.99:8000
+
+# 可选：Canvas 独立 LangGraph 地址（不设则回退到 VITE_LANGGRAPH_BASE_URL）
+# VITE_CANVAS_LANGGRAPH_BASE_URL=
diff --git a/frontend-web/.env.development.local.example b/frontend-web/.env.development.local.example
new file mode 100644
index 00000000..3f551f71
--- /dev/null
+++ b/frontend-web/.env.development.local.example
@@ -0,0 +1,7 @@
+# 复制为 .env.development.local，仅本机生效，不提交 Git
+# 直连本机 Gateway（需后端 CORS_ORIGINS 包含 http://127.0.0.1:5173 等）
+
+VITE_BACKEND_BASE_URL=http://127.0.0.1:8001
+VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
+
+# VITE_NOTE_API_BASE_URL=http://127.0.0.1:8000
diff --git a/frontend-web/.env.example b/frontend-web/.env.example
index 26095be7..30e82ad6 100644
--- a/frontend-web/.env.example
+++ b/frontend-web/.env.example
@@ -1,9 +1,30 @@
-# 复制为 .env 后按需修改（Vite 仅暴露以 VITE_ 开头的变量）
-# 直连本机 Gateway 时使用；若浏览器报 CORS，请在网关环境设置 CORS_ORIGINS，包含前端源站，例如：
-#   CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
+# 环境变量说明（Vite 仅暴露以 VITE_ 开头的变量）
+#
+# ┌─────────────────┬──────────────────────────────────────────────────┐
+# │ 命令            │ 生效文件                                          │
+# ├─────────────────┼──────────────────────────────────────────────────┤
+# │ pnpm dev        │ .env.development + .env.development.local        │
+# │ pnpm build      │ .env.production + .env.production.local          │
+# │ scripts/start-* │ 脚本注入的环境变量会覆盖上述文件（见下方说明）      │
+# └─────────────────┴──────────────────────────────────────────────────┘
+#
+# 推荐：
+# - 日常本地开发：改 .env.development（已提交，团队默认 UAT 地址）
+# - 本机连 127.0.0.1:8001：复制 .env.development.local.example → .env.development.local
+# - 内网打包部署：改 .env.production 后再执行 pnpm build
+#
+# 若浏览器直连后端报 CORS，请在 Gateway 配置 CORS_ORIGINS，包含前端源站，例如：
+#   CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173,http://127.0.0.1:5174
 
-VITE_BACKEND_BASE_URL=https://ch1.b.uat.4.cn/deerflow
-VITE_LANGGRAPH_BASE_URL=https://ch1.b.uat.4.cn/deerflow/api
+# --- 开发环境（见 .env.development）---
+# VITE_BACKEND_BASE_URL=https://ch1.b.uat.4.cn/deerflow
+# VITE_LANGGRAPH_BASE_URL=https://ch1.b.uat.4.cn/deerflow/api
+# VITE_NOTE_API_BASE_URL=http://47.88.25.99:8000
 
-# 轻应用「新建笔记」系列接口（与 DeerFlow Gateway 分离）
-VITE_NOTE_API_BASE_URL=http://47.88.25.99:8000
+# --- 生产打包（见 .env.production）---
+# 部署前修改 .env.production 中的地址，再执行 pnpm build
+
+# 可选
+# VITE_CANVAS_LANGGRAPH_BASE_URL=
+# VITE_STATIC_WEBSITE_ONLY=
+# VITE_GITHUB_OAUTH_TOKEN=
diff --git a/frontend-web/.env.production b/frontend-web/.env.production
new file mode 100644
index 00000000..1d13e37e
--- /dev/null
+++ b/frontend-web/.env.production
@@ -0,0 +1,12 @@
+# 生产打包（pnpm build）— 部署前请改成实际内网/生产地址
+# 打包后变量会写入 dist，运行时不可再改
+
+# Gateway / DeerFlow API
+VITE_BACKEND_BASE_URL=https://ch1.b.uat.4.cn/deerflow
+VITE_LANGGRAPH_BASE_URL=https://ch1.b.uat.4.cn/deerflow/api
+
+# 轻应用「新建笔记」系列接口
+VITE_NOTE_API_BASE_URL=https://your-intranet-host/note-api
+
+# 可选：Canvas 独立 LangGraph 地址
+# VITE_CANVAS_LANGGRAPH_BASE_URL=
diff --git a/frontend-web/.env.production.local.example b/frontend-web/.env.production.local.example
new file mode 100644
index 00000000..659844ac
--- /dev/null
+++ b/frontend-web/.env.production.local.example
@@ -0,0 +1,5 @@
+# 复制为 .env.production.local，打包前临时覆盖生产地址（不提交 Git）
+
+# VITE_BACKEND_BASE_URL=https://your-intranet-host/deerflow
+# VITE_LANGGRAPH_BASE_URL=https://your-intranet-host/deerflow/api
+# VITE_NOTE_API_BASE_URL=https://your-intranet-host/note-api