@lynker-desktop/electron-sdk 0.0.9-alpha.81 → 0.0.9-alpha.85

package/esm/main/downloader.js

@@ -39,6 +39,10 @@ const MAX_FILENAME_COUNTER = 10000;
  * 下载器类：提供文件下载功能
  */
 class Downloader {
+    /**
+     * 构造函数：初始化下载器并注册 IPC 处理器
+     * 注册 `core:downloader` IPC 处理器，用于从渲染进程接收下载请求
+     */
     constructor() {
         /** 正在下载的 URL 集合（避免重复下载） */
         this._downloadingUrls = new Map();
@@ -48,7 +52,7 @@ class Downloader {
             try {
                 const { id, url } = options;
                 const sender = event.sender;
-                // 创建进度回调，通过 IPC 发送进度更新
+                // 创建进度回调，通过 IPC 发送进度更新到渲染进程
                 const progressCallback = (progress) => {
                     try {
                         if (sender && typeof sender.send === 'function') {
@@ -59,75 +63,127 @@ class Downloader {
                         }
                     }
                     catch (error) {
-                        console.error('发送下载进度失败:', error);
+                        // 进度回调失败不影响下载，只记录日志
+                        console.error(`[Downloader] 发送下载进度失败 (ID: ${id}):`, error);
                     }
                 };
                 const result = await this.download(url, options, progressCallback);
                 return result;
             }
             catch (error) {
+                // IPC 调用异常处理：解析错误并返回明确的错误信息
+                const parsedError = this._parseError(error, options?.url);
                 return {
                     success: false,
-                    error: error instanceof Error ? error.message : '未知错误'
+                    error: parsedError.message,
+                    errorType: parsedError.type
                 };
             }
         });
     }
     /**
      * 下载文件
-     * @param url 要下载的 URL
-     * @param options 下载选项
+     *
+     * 主要流程：
+     * 1. 检查是否正在下载（避免重复下载）
+     * 2. 确定输出路径（支持弹窗选择或自动解析）
+     * 3. 验证并准备输出目录
+     * 4. 处理 base64 data URL 或普通 HTTP 下载
+     * 5. 使用临时文件下载，完成后重命名为最终文件
+     *
+     * @param url 要下载的 URL（支持 HTTP/HTTPS 和 base64 data URL）
+     * @param options 下载选项（输出路径、重试配置、回调函数等）
      * @param onProgress 进度回调函数（可选，优先级高于 options.onProgress）
-     * @returns Promise<DownloadResult> 下载结果
+     * @returns Promise<DownloadResult> 下载结果，包含成功/失败状态、文件路径、错误信息等
      */
     async download(url, options = {}, onProgress) {
-        // 生成唯一标识：URL + ID（如果存在）
+        // 参数验证：检查 URL 是否有效
+        if (!url || typeof url !== 'string' || url.trim().length === 0) {
+            return this._createErrorResult('下载 URL 不能为空', 'VALIDATION');
+        }
+        // 生成唯一标识：URL + ID（如果存在），用于避免重复下载
         const downloadKey = this._getDownloadKey(url, options.id);
-        // 检查是否正在下载，避免重复下载
+        // 检查是否正在下载，避免重复下载同一资源
         if (this._downloadingUrls.has(downloadKey)) {
-            return this._createErrorResult(`资源正在下载中: ${url}${options.id ? ` (ID: ${options.id})` : ''}`);
+            return this._createErrorResult(`资源正在下载中，请勿重复下载: ${url}${options.id ? ` (ID: ${options.id})` : ''}`, 'VALIDATION');
         }
         // 合并进度回调：优先使用传入的 onProgress，其次使用 options.onProgress
         const progressCallback = onProgress || options.onProgress;
-        // 先检查是否是 base64 data URL（用于确定默认扩展名）
+        // 先检查是否是 base64 data URL（用于确定默认扩展名和特殊处理）
         const base64Info = this._isBase64DataUrl(url);
         const defaultExt = base64Info.isBase64 && base64Info.ext ? base64Info.ext : undefined;
-        // 确定输出路径
+        // 确定输出路径：支持弹窗选择或自动解析
         let outputPath;
         try {
             if (options.showSaveDialog) {
+                // 显示保存对话框，让用户选择保存位置
                 const savePath = await this._showSaveDialog(url, options, defaultExt);
                 if (!savePath) {
-                    return this._createErrorResult('用户取消了保存操作');
+                    return this._createErrorResult('用户取消了保存操作', 'USER_CANCEL');
                 }
                 outputPath = savePath;
             }
             else {
+                // 自动解析输出路径
                 outputPath = this._resolveOutputPath(url, options, defaultExt);
             }
+            // 验证 outputPath 是否有效
+            if (!outputPath || typeof outputPath !== 'string' || outputPath.trim().length === 0) {
+                return this._createErrorResult('无法确定输出路径：路径解析结果无效', 'VALIDATION');
+            }
         }
         catch (error) {
-            return this._createErrorResult(error instanceof Error ? error.message : '确定输出路径失败');
+            // 路径解析失败：可能是文件系统错误或权限问题
+            const parsedError = this._parseError(error, url);
+            return this._createErrorResult(`确定输出路径失败: ${parsedError.message}`, parsedError.type);
+        }
+        // 准备输出路径：确保目录存在、检查文件是否已存在
+        try {
+            const pathCheckResult = await this._prepareOutputPath(outputPath, options);
+            if (pathCheckResult) {
+                // 文件已存在且不允许覆盖，直接返回已存在的文件信息
+                return pathCheckResult;
+            }
         }
-        // 准备输出路径（确保目录存在、检查文件是否已存在）
-        const pathCheckResult = await this._prepareOutputPath(outputPath, options);
-        if (pathCheckResult) {
-            return pathCheckResult;
+        catch (error) {
+            // 路径准备失败：可能是权限问题或文件系统错误
+            const parsedError = this._parseError(error, url);
+            return this._createErrorResult(`准备输出路径失败: ${parsedError.message}`, parsedError.type);
         }
-        const downloadDir = path.dirname(outputPath);
+        // 提取下载目录和文件名
+        let downloadDir = path.dirname(outputPath);
         let downloadFileName = path.basename(outputPath);
-        // 再次清理文件名，确保不包含 query 参数和特殊字符
+        // 再次清理文件名，确保不包含 query 参数和特殊字符（防止文件系统错误）
         downloadFileName = this._cleanFileName(downloadFileName);
-        // 更新 outputPath 使用清理后的文件名
+        // 验证下载目录是否可访问，如果不可用则使用系统下载目录作为备用
+        if (!this._isDirectoryAccessible(downloadDir)) {
+            try {
+                downloadDir = app.getPath('downloads');
+                // 确保备用目录存在（如果不存在则创建）
+                if (!fs.existsSync(downloadDir)) {
+                    fs.mkdirSync(downloadDir, { recursive: true });
+                }
+                // 验证备用目录是否可访问
+                if (!this._isDirectoryAccessible(downloadDir)) {
+                    return this._createErrorResult(`无法访问下载目录: ${downloadDir}，请检查目录权限`, 'PERMISSION');
+                }
+            }
+            catch (error) {
+                const parsedError = this._parseError(error, url);
+                return this._createErrorResult(`无法创建或访问备用下载目录: ${parsedError.message}`, parsedError.type);
+            }
+        }
+        // 更新 outputPath 使用清理后的文件名和验证后的目录
         outputPath = path.join(downloadDir, downloadFileName);
-        // 如果是 base64 data URL，使用已确定的输出路径进行处理
+        // 如果是 base64 data URL，使用已确定的输出路径进行特殊处理（无需网络请求）
         if (base64Info.isBase64 && base64Info.ext && base64Info.mimeType && base64Info.data) {
             return await this._handleBase64Download(url, { ext: base64Info.ext, mimeType: base64Info.mimeType, data: base64Info.data }, outputPath, options, progressCallback);
         }
-        // 使用临时文件下载，避免下载中断时文件不完整
+        // 使用临时文件下载（.cache 后缀），避免下载中断时文件不完整
+        // 下载完成后会将临时文件重命名为最终文件
         const tempFilePath = path.join(downloadDir, downloadFileName + '.cache');
         return new Promise((resolve, reject) => {
-            // 创建下载器实例
+            // 创建下载器实例（使用 node-downloader-helper）
             const dl = new DownloaderHelper(url, downloadDir, {
                 fileName: downloadFileName + '.cache',
                 retry: {
@@ -135,16 +191,16 @@ class Downloader {
                     delay: options.retry?.delay ?? DEFAULT_RETRY.delay
                 },
                 timeout: options.timeout ?? DEFAULT_TIMEOUT,
-                override: true, // 临时文件总是覆盖
+                override: true, // 临时文件总是覆盖，避免残留文件
                 httpRequestOptions: {
                     followRedirect: options.httpRequestOptions?.followRedirect ?? true,
                     maxRedirects: options.httpRequestOptions?.maxRedirects ?? MAX_REDIRECTS,
                     headers: options.httpRequestOptions?.headers
                 }
             });
-            // 记录正在下载的 URL（使用 URL + ID 作为 key）
+            // 记录正在下载的 URL（使用 URL + ID 作为 key），用于避免重复下载
             this._downloadingUrls.set(downloadKey, dl);
-            // 监听下载进度
+            // 监听下载进度事件
             if (progressCallback) {
                 dl.on('progress', (stats) => {
                     try {
@@ -157,63 +213,101 @@ class Downloader {
                         });
                     }
                     catch (error) {
-                        // 忽略回调中的错误，避免影响下载
-                        console.error('进度回调执行失败:', error);
+                        // 进度回调失败不影响下载，只记录日志
+                        console.error(`[Downloader] 进度回调执行失败 (${url}):`, error);
                     }
                 });
             }
-            // 监听下载完成
+            // 监听下载完成事件
             dl.on('end', () => {
+                // 从下载列表中移除
                 this._downloadingUrls.delete(downloadKey);
-                // 将临时文件重命名为最终文件
+                // 将临时文件重命名为最终文件（原子操作，确保文件完整性）
                 fs.rename(tempFilePath, outputPath, (renameErr) => {
                     if (renameErr) {
-                        const error = new Error(`文件重命名失败 from ${tempFilePath} to ${outputPath}: ${renameErr.message}`);
+                        // 文件重命名失败：可能是权限问题或文件被占用
+                        const parsedError = this._parseError(renameErr, url);
+                        const error = new Error(`文件重命名失败: 无法将临时文件 "${tempFilePath}" 重命名为 "${outputPath}"。${parsedError.message}`);
+                        // 调用错误回调
                         if (options.onError) {
                             options.onError(error);
                         }
+                        // reject 应该传入 Error 对象，而不是 DownloadResult
+                        // 将错误类型附加到错误对象上
+                        error.errorType = parsedError.type;
                         reject(error);
                     }
                     else {
-                        // 获取文件大小并返回结果
-                        const stats = fs.statSync(outputPath);
-                        const result = this._createSuccessResult(outputPath, stats.size);
-                        if (options.onComplete) {
-                            options.onComplete(outputPath);
+                        try {
+                            // 获取文件大小并返回成功结果
+                            const stats = fs.statSync(outputPath);
+                            const result = this._createSuccessResult(outputPath, stats.size);
+                            // 调用完成回调
+                            if (options.onComplete) {
+                                options.onComplete(outputPath);
+                            }
+                            resolve(result);
+                        }
+                        catch (error) {
+                            // 获取文件信息失败
+                            const parsedError = this._parseError(error, url);
+                            const errorObj = new Error(`下载完成但无法获取文件信息: ${parsedError.message}`);
+                            // 将错误类型附加到错误对象上
+                            errorObj.errorType = parsedError.type;
+                            reject(errorObj);
                         }
-                        resolve(result);
                     }
                 });
             });
             // 统一的错误处理函数
-            const handleError = (error) => {
+            const handleError = (error, isUserCancel = false) => {
+                // 从下载列表中移除
                 this._downloadingUrls.delete(downloadKey);
-                // 清理临时文件
+                // 清理临时文件（忽略删除失败，避免影响错误处理）
                 fs.promises.unlink(tempFilePath).catch(() => {
-                    // 忽略删除失败
+                    // 临时文件删除失败不影响错误处理流程
                 });
+                // 解析错误信息
+                const parsedError = this._parseError(error, url);
+                const errorType = isUserCancel ? 'USER_CANCEL' : parsedError.type;
+                const errorMessage = isUserCancel
+                    ? `下载已取消: ${url}`
+                    : parsedError.message;
+                // 创建错误对象（包含错误类型信息）
+                const errorObj = new Error(errorMessage);
+                // 将错误类型附加到错误对象上，供 catch 处理时使用
+                errorObj.errorType = errorType;
+                // 调用错误回调
                 if (options.onError) {
-                    options.onError(error);
+                    options.onError(errorObj);
                 }
-                reject(error);
+                // reject 应该传入 Error 对象，而不是 DownloadResult
+                reject(errorObj);
             };
-            // 监听下载错误
+            // 监听下载错误事件（网络错误、服务器错误等）
             dl.on('error', (err) => {
                 const error = err instanceof Error ? err : new Error(`下载失败: ${url}`);
-                handleError(error);
+                handleError(error, false);
             });
-            // 监听下载停止（取消）
+            // 监听下载停止事件（用户取消或手动停止）
             dl.on('stop', () => {
                 const error = new Error(`下载已停止: ${url}`);
-                handleError(error);
+                handleError(error, true);
             });
             // 开始下载
             dl.start().catch((err) => {
+                // 启动下载失败：可能是 URL 无效、网络不可达等
                 const error = err instanceof Error ? err : new Error(`启动下载失败: ${url}`);
-                handleError(error);
+                handleError(error, false);
             });
         }).catch((error) => {
-            return this._createErrorResult(error instanceof Error ? error.message : '未知错误');
+            // Promise 异常捕获：返回格式化的错误结果
+            // 如果错误对象已经包含 errorType，直接使用；否则解析错误
+            if (error instanceof Error && error.errorType) {
+                return this._createErrorResult(error.message, error.errorType);
+            }
+            const parsedError = this._parseError(error, url);
+            return this._createErrorResult(parsedError.message, parsedError.type);
         });
     }
     /**
@@ -294,10 +388,54 @@ class Downloader {
         // 从 URL 中提取文件名（_extractFileNameFromUrl 已经包含清理逻辑）
         return this._extractFileNameFromUrl(url);
     }
+    /**
+     * 检查目录是否存在且有访问权限
+     *
+     * 检查项：
+     * 1. 路径是否有效（非空字符串）
+     * 2. 目录是否存在
+     * 3. 路径是否为目录（而非文件）
+     * 4. 是否有读写权限
+     *
+     * @param dirPath 目录路径
+     * @returns 如果目录存在且有读写权限则返回 true，否则返回 false
+     */
+    _isDirectoryAccessible(dirPath) {
+        // 参数验证：检查路径是否有效
+        if (!dirPath || typeof dirPath !== 'string') {
+            return false;
+        }
+        try {
+            // 检查目录是否存在
+            if (!fs.existsSync(dirPath)) {
+                return false;
+            }
+            // 检查是否是目录（而非文件）
+            const stats = fs.statSync(dirPath);
+            if (!stats.isDirectory()) {
+                return false;
+            }
+            // 检查是否有读写权限（R_OK: 读权限, W_OK: 写权限）
+            fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+            return true;
+        }
+        catch {
+            // 如果任何检查失败（不存在、不是目录、无权限等），返回 false
+            return false;
+        }
+    }
     /**
      * 显示保存对话框
-     * @param url 下载 URL
-     * @param options 下载选项
+     *
+     * 功能说明：
+     * 1. 确定默认保存目录（优先级：defaultPath > outputDir > _lastSelectedDir > 系统下载目录）
+     * 2. 验证并更新 _lastSelectedDir（如果不可访问则重置）
+     * 3. 生成唯一文件名（如果文件已存在，添加数字后缀）
+     * 4. 显示 Electron 保存对话框
+     * 5. 记录用户选择的目录（用于下次默认使用）
+     *
+     * @param url 下载 URL（用于提取默认文件名）
+     * @param options 下载选项（包含 defaultPath、outputDir 等）
      * @param defaultExt 默认扩展名（可选，用于 base64 URL）
      * @returns Promise<string | null> 用户选择的保存路径，如果取消则返回 null
      */
@@ -314,6 +452,12 @@ class Downloader {
         }
         else {
             // 如果没有指定目录，使用上一次选择的文件夹，如果没有则使用下载目录
+            // 检查 _lastSelectedDir 是否可用，如果不可用则重置为下载目录
+            if (this._lastSelectedDir && !this._isDirectoryAccessible(this._lastSelectedDir)) {
+                const downloadsPath = app.getPath('downloads');
+                // 验证下载目录是否可用，如果可用则使用，否则设为 null
+                this._lastSelectedDir = this._isDirectoryAccessible(downloadsPath) ? downloadsPath : null;
+            }
             defaultDir = this._lastSelectedDir || app.getPath('downloads');
         }
         // 如果指定了目录，检查文件是否存在并生成唯一文件名
@@ -349,7 +493,15 @@ class Downloader {
         // 记录用户选择的文件夹路径，用于下次默认使用
         const selectedDir = path.dirname(result.filePath);
         if (selectedDir) {
-            this._lastSelectedDir = selectedDir;
+            // 验证选择的目录是否可访问，只有可访问时才保存
+            if (this._isDirectoryAccessible(selectedDir)) {
+                this._lastSelectedDir = selectedDir;
+            }
+            else {
+                // 如果选择的目录不可访问，尝试使用下载目录
+                const downloadsPath = app.getPath('downloads');
+                this._lastSelectedDir = this._isDirectoryAccessible(downloadsPath) ? downloadsPath : null;
+            }
         }
         return result.filePath;
     }
@@ -396,45 +548,90 @@ class Downloader {
     }
     /**
      * 保存 base64 数据到文件
-     * @param base64Data base64 编码的数据
-     * @param filePath 目标文件路径
+     *
+     * 处理流程：
+     * 1. 将 base64 字符串解码为 Buffer
+     * 2. 将 Buffer 写入目标文件路径
+     *
+     * @param base64Data base64 编码的数据字符串
+     * @param filePath 目标文件路径（完整路径，包含文件名）
+     * @throws 如果解码失败或文件写入失败，抛出错误
      */
     async _saveBase64ToFile(base64Data, filePath) {
         try {
-            // 解码 base64 数据
+            // 解码 base64 数据为 Buffer
             const buffer = Buffer.from(base64Data, 'base64');
-            // 使用 Promise 版本的 writeFile
+            // 使用 Promise 版本的 writeFile 写入文件
             // Buffer 继承自 Uint8Array，可以直接使用
             await fs.promises.writeFile(filePath, buffer);
         }
         catch (error) {
-            throw new Error(`保存 base64 文件失败: ${error instanceof Error ? error.message : '未知错误'}`);
+            // 文件保存失败：可能是权限问题、磁盘空间不足、路径无效等
+            const errorMessage = error instanceof Error ? error.message : '未知错误';
+            throw new Error(`保存 base64 文件失败 (${filePath}): ${errorMessage}`);
         }
     }
     /**
-     * 准备输出路径（确保目录存在、检查文件是否已存在）
-     * @param outputPath 输出路径
-     * @param options 下载选项
-     * @returns 如果文件已存在且不允许覆盖，返回结果；否则返回 null
+     * 准备输出路径
+     *
+     * 主要功能：
+     * 1. 确保输出目录存在（不存在则创建）
+     * 2. 检查文件是否已存在
+     * 3. 如果文件已存在且不允许覆盖，返回已存在的文件信息
+     *
+     * @param outputPath 输出文件路径
+     * @param options 下载选项（包含 override 选项）
+     * @returns 如果文件已存在且不允许覆盖，返回已存在的文件信息；否则返回 null
+     * @throws 如果目录创建失败或权限不足，抛出错误
      */
     async _prepareOutputPath(outputPath, options) {
-        const downloadDir = path.dirname(outputPath);
-        // 确保目录存在
+        // 参数验证：确保 outputPath 是有效的非空字符串
+        if (!outputPath || typeof outputPath !== 'string' || outputPath.trim().length === 0) {
+            throw new Error(`输出路径无效: ${outputPath}`);
+        }
+        // 规范化路径（解析相对路径、处理 .. 等）
+        const normalizedPath = path.resolve(outputPath);
+        // 验证规范化后的路径是否有效
+        if (!normalizedPath || normalizedPath.trim().length === 0) {
+            throw new Error(`无法解析输出路径: ${outputPath}`);
+        }
+        const downloadDir = path.dirname(normalizedPath);
+        // 使用规范化后的路径
+        outputPath = normalizedPath;
+        // 确保目录存在：如果不存在则创建（递归创建父目录）
         if (!fs.existsSync(downloadDir)) {
-            fs.mkdirSync(downloadDir, { recursive: true });
+            try {
+                fs.mkdirSync(downloadDir, { recursive: true });
+            }
+            catch (error) {
+                // 目录创建失败：可能是权限问题或路径无效
+                const parsedError = this._parseError(error);
+                throw new Error(`无法创建输出目录 "${downloadDir}": ${parsedError.message}`);
+            }
         }
-        // 如果文件已存在且不允许覆盖，直接返回
+        // 验证目录是否可访问
+        if (!this._isDirectoryAccessible(downloadDir)) {
+            throw new Error(`无法访问输出目录 "${downloadDir}"，请检查目录权限`);
+        }
+        // 如果文件已存在且不允许覆盖，直接返回已存在的文件信息
         if (fs.existsSync(outputPath) && !(options.override ?? true)) {
-            const stats = fs.statSync(outputPath);
-            return this._createSuccessResult(outputPath, stats.size);
+            try {
+                const stats = fs.statSync(outputPath);
+                return this._createSuccessResult(outputPath, stats.size);
+            }
+            catch (error) {
+                // 获取文件信息失败：可能是权限问题
+                const parsedError = this._parseError(error);
+                throw new Error(`无法访问已存在的文件 "${outputPath}": ${parsedError.message}`);
+            }
         }
         return null;
     }
     /**
      * 创建成功结果
      * @param filePath 文件路径
-     * @param size 文件大小
-     * @returns DownloadResult
+     * @param size 文件大小（字节）
+     * @returns DownloadResult 成功结果对象
      */
     _createSuccessResult(filePath, size) {
         return {
@@ -446,31 +643,120 @@ class Downloader {
     /**
      * 创建错误结果
      * @param error 错误信息
-     * @returns DownloadResult
+     * @param errorType 错误类型（可选，用于区分不同类型的错误）
+     * @returns DownloadResult 错误结果对象
      */
-    _createErrorResult(error) {
+    _createErrorResult(error, errorType) {
         return {
             success: false,
-            error
+            error,
+            errorType: errorType || 'UNKNOWN'
+        };
+    }
+    /**
+     * 从错误对象中提取错误类型和详细信息
+     * @param error 错误对象
+     * @param url 下载的 URL（用于上下文信息）
+     * @returns 包含错误类型和详细错误信息的对象
+     */
+    _parseError(error, url) {
+        if (error instanceof Error) {
+            const errorMessage = error.message.toLowerCase();
+            const errorCode = error.code?.toLowerCase() || '';
+            // 网络相关错误
+            if (errorMessage.includes('network') ||
+                errorMessage.includes('timeout') ||
+                errorMessage.includes('econnrefused') ||
+                errorMessage.includes('enotfound') ||
+                errorMessage.includes('etimedout') ||
+                errorCode.includes('timeout') ||
+                errorCode.includes('econnrefused') ||
+                errorCode.includes('enotfound') ||
+                errorCode.includes('etimedout')) {
+                return {
+                    type: 'NETWORK',
+                    message: `网络错误: ${error.message}${url ? ` (URL: ${url})` : ''}`
+                };
+            }
+            // 文件系统相关错误
+            if (errorMessage.includes('enoent') ||
+                errorMessage.includes('eacces') ||
+                errorMessage.includes('eperm') ||
+                errorMessage.includes('file') ||
+                errorMessage.includes('directory') ||
+                errorMessage.includes('path') ||
+                errorCode.includes('enoent') ||
+                errorCode.includes('eacces') ||
+                errorCode.includes('eperm')) {
+                if (errorMessage.includes('permission') || errorMessage.includes('eacces') || errorMessage.includes('eperm')) {
+                    return {
+                        type: 'PERMISSION',
+                        message: `权限错误: ${error.message}${url ? ` (URL: ${url})` : ''}`
+                    };
+                }
+                return {
+                    type: 'FILE_SYSTEM',
+                    message: `文件系统错误: ${error.message}${url ? ` (URL: ${url})` : ''}`
+                };
+            }
+            // 验证相关错误
+            if (errorMessage.includes('invalid') ||
+                errorMessage.includes('validation') ||
+                errorMessage.includes('格式') ||
+                errorMessage.includes('无效')) {
+                return {
+                    type: 'VALIDATION',
+                    message: `验证错误: ${error.message}${url ? ` (URL: ${url})` : ''}`
+                };
+            }
+            // 用户取消
+            if (errorMessage.includes('cancel') || errorMessage.includes('取消')) {
+                return {
+                    type: 'USER_CANCEL',
+                    message: error.message
+                };
+            }
+            // 其他错误
+            return {
+                type: 'UNKNOWN',
+                message: `未知错误: ${error.message}${url ? ` (URL: ${url})` : ''}`
+            };
+        }
+        // 非 Error 对象
+        return {
+            type: 'UNKNOWN',
+            message: `未知错误: ${String(error)}${url ? ` (URL: ${url})` : ''}`
         };
     }
     /**
      * 处理 base64 data URL 的下载
+     *
+     * base64 data URL 格式：data:[<mediatype>][;base64],<data>
+     * 例如：data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
+     *
+     * 处理流程：
+     * 1. 验证 base64 数据有效性
+     * 2. 触发进度回调（模拟 100% 完成）
+     * 3. 解码并保存 base64 数据到文件
+     * 4. 返回成功结果
+     *
      * @param url base64 data URL
-     * @param base64Info base64 信息
+     * @param base64Info base64 信息（扩展名、MIME 类型、数据）
      * @param outputPath 已确定的输出路径
      * @param options 下载选项
-     * @param progressCallback 进度回调
+     * @param progressCallback 进度回调（可选）
      * @returns Promise<DownloadResult> 下载结果
      */
     async _handleBase64Download(url, base64Info, outputPath, options, progressCallback) {
+        // 验证 base64 数据有效性
         if (!base64Info.data || !base64Info.ext) {
-            return this._createErrorResult(`无效的 base64 data URL: ${url}`);
+            return this._createErrorResult(`无效的 base64 data URL: 缺少数据或扩展名 (URL: ${url.substring(0, 50)}...)`, 'VALIDATION');
         }
         try {
+            // 计算数据长度（用于进度回调）
+            const dataLength = Buffer.from(base64Info.data, 'base64').length;
             // 模拟进度回调（base64 数据通常很小，立即完成）
             if (progressCallback) {
-                const dataLength = Buffer.from(base64Info.data, 'base64').length;
                 progressCallback({
                     url,
                     downloaded: dataLength,
@@ -481,27 +767,42 @@ class Downloader {
             }
             // 保存 base64 数据到文件
             await this._saveBase64ToFile(base64Info.data, outputPath);
-            // 获取文件大小
+            // 获取文件大小并返回成功结果
             const stats = fs.statSync(outputPath);
             const result = this._createSuccessResult(outputPath, stats.size);
+            // 调用完成回调
             if (options.onComplete) {
                 options.onComplete(outputPath);
             }
             return result;
         }
         catch (error) {
-            const err = error instanceof Error ? error : new Error('保存 base64 文件失败');
+            // base64 文件保存失败：可能是文件系统错误或权限问题
+            const parsedError = this._parseError(error, url);
+            const err = error instanceof Error ? error : new Error(`保存 base64 文件失败: ${parsedError.message}`);
+            // 调用错误回调
             if (options.onError) {
                 options.onError(err);
             }
-            return this._createErrorResult(err.message);
+            return this._createErrorResult(`保存 base64 文件失败: ${parsedError.message}`, parsedError.type);
         }
     }
     /**
      * 生成唯一的文件名（如果文件已存在，添加数字后缀）
+     *
+     * 命名规则：
+     * - 如果文件不存在，返回原始文件名
+     * - 如果文件已存在，添加数字后缀：filename(1).ext, filename(2).ext, ...
+     * - 最多尝试 MAX_FILENAME_COUNTER 次，防止无限循环
+     *
+     * 示例：
+     * - "test.pdf" -> "test.pdf" (如果不存在)
+     * - "test.pdf" -> "test(1).pdf" (如果 test.pdf 已存在)
+     * - "test(1).pdf" -> "test(2).pdf" (如果 test(1).pdf 也已存在)
+     *
      * @param dir 目录路径
-     * @param fileName 原始文件名
-     * @returns 唯一的文件名
+     * @param fileName 原始文件名（包含扩展名）
+     * @returns 唯一的文件名（如果原文件不存在则返回原文件名，否则返回带数字后缀的文件名）
      */
     _generateUniqueFileName(dir, fileName) {
         // 分离文件名和扩展名
@@ -638,21 +939,71 @@ class Downloader {
      * @param options 下载选项
      * @param defaultExt 默认扩展名（可选，用于 base64 URL）
      * @returns 输出文件路径
+     * @throws 如果无法解析有效路径，抛出错误
      */
     _resolveOutputPath(url, options, defaultExt) {
         // 如果提供了完整路径，直接使用（但需要清理文件名部分）
         if (options.outputPath) {
-            const dir = path.dirname(options.outputPath);
-            const fileName = this._cleanFileName(path.basename(options.outputPath));
-            return path.resolve(path.join(dir, fileName));
+            // 验证 outputPath 是否有效
+            if (typeof options.outputPath !== 'string' || options.outputPath.trim().length === 0) {
+                throw new Error(`无效的输出路径: ${options.outputPath}`);
+            }
+            try {
+                const dir = path.dirname(options.outputPath);
+                const fileName = this._cleanFileName(path.basename(options.outputPath));
+                // 验证文件名是否有效
+                if (!fileName || fileName.trim().length === 0) {
+                    throw new Error(`无法从路径中提取有效文件名: ${options.outputPath}`);
+                }
+                const resolvedPath = path.resolve(path.join(dir, fileName));
+                // 验证解析后的路径是否有效
+                if (!resolvedPath || resolvedPath.trim().length === 0) {
+                    throw new Error(`路径解析失败: ${options.outputPath}`);
+                }
+                return resolvedPath;
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw error;
+                }
+                throw new Error(`解析输出路径失败: ${String(error)}`);
+            }
         }
         // 确定输出目录：优先使用指定的目录，否则使用 Electron 的下载目录
-        const outputDir = options.outputDir
-            ? path.resolve(options.outputDir)
-            : app.getPath('downloads');
+        let outputDir;
+        try {
+            if (options.outputDir) {
+                if (typeof options.outputDir !== 'string' || options.outputDir.trim().length === 0) {
+                    throw new Error(`无效的输出目录: ${options.outputDir}`);
+                }
+                outputDir = path.resolve(options.outputDir);
+            }
+            else {
+                outputDir = app.getPath('downloads');
+            }
+            // 验证输出目录是否有效
+            if (!outputDir || outputDir.trim().length === 0) {
+                throw new Error('无法获取有效的输出目录');
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new Error(`确定输出目录失败: ${String(error)}`);
+        }
         // 使用统一的文件名获取方法
         const fileName = this._getFileName(url, options, defaultExt);
-        return path.join(outputDir, fileName);
+        // 验证文件名是否有效
+        if (!fileName || fileName.trim().length === 0) {
+            throw new Error('无法获取有效的文件名');
+        }
+        const finalPath = path.join(outputDir, fileName);
+        // 验证最终路径是否有效
+        if (!finalPath || finalPath.trim().length === 0) {
+            throw new Error('无法构建有效的输出路径');
+        }
+        return finalPath;
     }
 }
 /**