diff --git a/.env.example b/.env.example
index e6aecd724..c18ce927b 100644
--- a/.env.example
+++ b/.env.example
@@ -27,6 +27,11 @@ E2E_TEST_PASSWORD="your-test-password"
 
 # ==================== DWEB 发布 ====================
 
+# KeyApp 官网配置（DWEB 自动更新使用）
+# 注意：SITE_ORIGIN 与 SITE_BASE_URL 必须成对配置
+SITE_ORIGIN="https://bioforestchain.github.io/"
+SITE_BASE_URL="/KeyApp/"
+
 # SFTP 服务器地址（默认: sftp://iweb.xin:22022）
 # DWEB_SFTP_URL="sftp://iweb.xin:22022"
 
diff --git a/scripts/build.ts b/scripts/build.ts
index 912877c53..35dbd6148 100644
--- a/scripts/build.ts
+++ b/scripts/build.ts
@@ -147,7 +147,7 @@ function resolveSiteOrigin(): string | null {
 function resolveSiteBaseUrl(): string | null {
   const origin = resolveSiteOrigin()
   if (!origin) return null
-  const basePath = process.env.VITEPRESS_BASE ?? '/'
+  const basePath = process.env.SITE_BASE_URL ?? process.env.VITEPRESS_BASE ?? '/'
   return new URL(basePath, origin).toString()
 }
 
diff --git a/scripts/env-registry.json b/scripts/env-registry.json
index e90b9b2be..adf8bcf90 100644
--- a/scripts/env-registry.json
+++ b/scripts/env-registry.json
@@ -8,7 +8,16 @@
       "required": true,
       "targets": { "local": true, "github": "variable" },
       "mask": "tail",
-      "description": "DWEB 自动更新使用的官网域名"
+      "description": "DWEB 自动更新使用的官网域名（需与 SITE_BASE_URL 成对配置）"
+    },
+    {
+      "key": "SITE_BASE_URL",
+      "label": "KeyApp 站点 Base Path",
+      "type": "string",
+      "required": true,
+      "targets": { "local": true, "github": "variable" },
+      "mask": "tail",
+      "description": "DWEB 自动更新使用的站点路径（需与 SITE_ORIGIN 成对配置，例如 /KeyApp/）"
     },
     {
       "key": "DWEB_SFTP_URL",
diff --git a/src/lib/dweb-update.ts b/src/lib/dweb-update.ts
index 153ea6f8d..f91d7ab5c 100644
--- a/src/lib/dweb-update.ts
+++ b/src/lib/dweb-update.ts
@@ -74,6 +74,7 @@ function normalizeBasePath(basePath: string): string {
 }
 
 function resolveSiteBase(): string {
+  // __KEYAPP_SITE_ORIGIN__ + __KEYAPP_BASE_URL__ 必须成对配置，避免丢失站点路径。
   const origin = normalizeOrigin(__KEYAPP_SITE_ORIGIN__)
   try {
     const originUrl = new URL(origin)
diff --git a/vite.config.ts b/vite.config.ts
index 8e1f72f37..ff09d6914 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -113,7 +113,10 @@ export default defineConfig(({ mode }) => {
   const etherscanApiKey = env.ETHERSCAN_API_KEY ?? process.env.ETHERSCAN_API_KEY ?? '';
   const moralisApiKey = env.MORALIS_API_KEY ?? process.env.MORALIS_API_KEY ?? '';
   const isDevBuild = (env.VITE_DEV_MODE ?? process.env.VITE_DEV_MODE) === 'true';
+  // DWEB 更新地址由 SITE_ORIGIN + SITE_BASE_URL 拼接，二者必须成对配置。
+  // 注意：这里不要误用 VITE_BASE_URL（它是构建资源的 base），否则会导致更新 URL 丢失站点路径。
   const siteOrigin = env.SITE_ORIGIN ?? process.env.SITE_ORIGIN ?? 'https://bioforestchain.github.io/KeyApp/';
+  const siteBaseUrl = env.SITE_BASE_URL ?? process.env.SITE_BASE_URL ?? BASE_URL;
 
   const buildTime = new Date();
   const pad = (value: number) => value.toString().padStart(2, '0');
@@ -209,8 +212,8 @@ export default defineConfig(({ mode }) => {
       __APP_VERSION__: JSON.stringify(appVersion),
       // KeyApp 官网 Origin（DWEB 升级检查使用）
       __KEYAPP_SITE_ORIGIN__: JSON.stringify(siteOrigin),
-      // KeyApp Base URL（DWEB 升级链接拼接使用）
-      __KEYAPP_BASE_URL__: JSON.stringify(BASE_URL),
+      // KeyApp Base URL（DWEB 升级链接拼接使用；需配合 SITE_ORIGIN 使用）
+      __KEYAPP_BASE_URL__: JSON.stringify(siteBaseUrl),
       // 默认生态源列表（用于订阅源管理展示）
       __ECOSYSTEM_SOURCES__: JSON.stringify(ecosystemSources),
       // API Keys 对象（用于动态读取环境变量）