diff --git a/src/api.ts b/src/api.ts
index 64eb292..b76d899 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -95,6 +95,31 @@ function createRequestError(
   return requestError;
 }
 
+const PROXY_ERROR_PATTERNS = [
+  'socket disconnected before secure TLS connection',
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'CERT_HAS_EXPIRED',
+  'self signed certificate',
+  'proxy',
+  'ETIMEDOUT',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+];
+
+function isProxyRelatedError(error: unknown): boolean {
+  const msg =
+    error instanceof Error
+      ? error.message
+      : typeof error === 'string'
+        ? error
+        : '';
+  const lower = msg.toLowerCase();
+  return PROXY_ERROR_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+}
+
 async function query(url: string, options: RuntimeRequestInit) {
   const baseUrl = await getBaseUrl;
   const fullUrl = `${baseUrl}${url}`;
@@ -102,7 +127,13 @@ async function query(url: string, options: RuntimeRequestInit) {
   try {
     resp = await runtimeFetch(fullUrl, options);
   } catch (error) {
-    throw createRequestError(error, fullUrl);
+    const baseError = createRequestError(error, fullUrl);
+    if (isProxyRelatedError(error)) {
+      throw new Error(
+        `${baseError.message}\n\n${t('proxyNetworkError')}\n${t('proxyNetworkErrorTips')}`,
+      );
+    }
+    throw baseError;
   }
   const text = await resp.text();
   let json: any;
@@ -230,6 +261,13 @@ export async function uploadFile(fn: string, key?: string) {
       body: form,
     });
   } catch (error) {
+    if (isProxyRelatedError(error)) {
+      const rawMessage =
+        error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `${rawMessage}\n\n${t('proxyNetworkError')}\n${t('proxyNetworkErrorTips')}`,
+      );
+    }
     throw createRequestError(error, realUrl);
   }
 
diff --git a/src/locales/en.ts b/src/locales/en.ts
index 9d7c5e4..95a398e 100644
--- a/src/locales/en.ts
+++ b/src/locales/en.ts
@@ -182,4 +182,7 @@ This can reduce the risk of inconsistent dependencies and supply chain attacks.
   nodeHdiffpatchRequired:
     'This function needs "node-hdiffpatch". Please run "{{scriptName}} install node-hdiffpatch" to install',
   apkExtracted: 'APK extracted to {{output}}',
+  proxyNetworkError:
+    'Network error — likely caused by a proxy/VPN. Please try disabling your proxy and retry.',
+  proxyNetworkErrorTips: 'Common fixes:\n1. Disable system proxy or VPN\n2. Check HTTP_PROXY / HTTPS_PROXY environment variables\n3. Check proxy settings in .npmrc',
 };
diff --git a/src/locales/zh.ts b/src/locales/zh.ts
index 2843ec2..a68ce5e 100644
--- a/src/locales/zh.ts
+++ b/src/locales/zh.ts
@@ -168,4 +168,7 @@ export default {
   nodeHdiffpatchRequired:
     '此功能需要 "node-hdiffpatch"。请运行 "{{scriptName}} install node-hdiffpatch" 来安装',
   apkExtracted: 'APK 已提取到 {{output}}',
+  proxyNetworkError:
+    '网络连接异常，可能是代理/VPN 导致。请尝试关闭代理后重试。',
+  proxyNetworkErrorTips: '常见解决方法：\n1. 关闭系统代理或 VPN\n2. 检查 HTTP_PROXY / HTTPS_PROXY 环境变量\n3. 检查 .npmrc 中的 proxy 配置',
 };