diff --git a/src/config/app.config.js b/src/config/app.config.js
index 39c3670..2d770d3 100644
--- a/src/config/app.config.js
+++ b/src/config/app.config.js
@@ -1,12 +1,25 @@
 // ★ 集中配置 -- 外部服务 URL、默认参数等统一在此维护
 // 模块按需 import { appConfig } 使用，改 URL 只改这里即可（需重新 build）。
 // 每个服务项都带默认值，避免缺失字段导致渲染崩溃。
+//
+// 环境感知（测试环境指向测试环境，生产环境指向生产环境）：
+//   - 开发服务器（vite dev / MODE=development）：baseUrl 为空串（同源），
+//     经 vite.config.js 的 server.proxy 把 /api /pdf /health /static 等同源代理到
+//     本地 zTools2（127.0.0.1:6867），使 iframe 与 fetch 都命中本地服务。
+//   - 生产构建（vite build / MODE=production）：baseUrl 指向线上 f.zikai.wang（同源）。
+//   - 可用 VITE_API_BASE 覆盖（如自定义测试环境域名，需含协议）。
+
+// 生产构建用线上地址（同源）；开发用空串（同源，经 vite proxy 转发到本地 zTools2）；
+// 允许 VITE_API_BASE 显式覆盖（如指向独立测试环境域名）
+const BASE_URL =
+  import.meta.env.VITE_API_BASE ||
+  (import.meta.env.PROD ? 'https://f.zikai.wang' : '')
 
 export const appConfig = {
   // 共享记事本（白板）服务
   whiteboard: {
     // 服务根地址（含协议与域名）
-    baseUrl: 'https://f.zikai.wang',
+    baseUrl: BASE_URL,
     // 存活探针路径；周期探测，挂掉则隐藏页签并卸载组件
     healthPath: '/health',
     // 记事本页面路径生成器
@@ -19,7 +32,7 @@ export const appConfig = {
   // PDF 转换服务（zTools2 托管的 /pdf 页面，iframe 同源嵌入）
   pdf: {
     // 服务根地址（含协议与域名）
-    baseUrl: 'https://f.zikai.wang',
+    baseUrl: BASE_URL,
     // 存活探针路径；周期探测，挂掉则隐藏页签并卸载组件
     healthPath: '/health',
     // PDF 转换页面路径
@@ -39,3 +52,11 @@ export function healthUrl(service) {
   if (!cfg) return ''
   return `${cfg.baseUrl}${cfg.healthPath}`
 }
+
+/**
+ * 当前是否为开发/测试环境（便于组件按环境调整行为）。
+ * @returns {boolean}
+ */
+export function isDev() {
+  return !import.meta.env.PROD
+}
diff --git a/vite.config.js b/vite.config.js
index bdef092..505cbae 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -62,6 +62,41 @@ export default defineConfig({
         target: 'http://localhost:8080',
         changeOrigin: true,
       },
+      // zTools2 后端同源代理：开发环境把 /api /pdf /health /static 等转发到本地 zTools2，
+      // 使 iframe（/pdf）与 fetch（/api/pdf/*）同源命中本地服务（测试环境指向测试环境）。
+      // 生产构建时 app.config.js 的 baseUrl 指向线上 f.zikai.wang，不走此代理。
+      '/api': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/pdf': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/health': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/static': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/upload': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/files': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/wb': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+      },
+      '/ws': {
+        target: 'ws://127.0.0.1:6867',
+        ws: true,
+      },
     },
   },
 })