@cloudbase/manager-node 5.8.7 → 5.8.8

package/lib/storage/index.js

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageService = exports.md5File = void 0;
+exports.collectBatchDeleteFailures = collectBatchDeleteFailures;
 const fs_1 = __importDefault(require("fs"));
 const util_1 = __importDefault(require("util"));
 const path_1 = __importDefault(require("path"));
@@ -22,6 +23,7 @@ const cos_nodejs_sdk_v5_1 = __importDefault(require("cos-nodejs-sdk-v5"));
 const utils_1 = require("../utils");
 const error_1 = require("../error");
 const parallel_1 = require("../utils/parallel");
+const storage_config_1 = require("../utils/storage-config");
 const runenv_1 = require("../utils/runenv");
 const constant_1 = require("../constant");
 const helper_1 = require("./helper");
@@ -33,6 +35,23 @@ const DEFAULT_MD5_PARALLEL = 20;
 const CONSISTENT_DEPLOY_BACKUP_PREFIX = '.cloudbase-backup/';
 var helper_2 = require("./helper");
 Object.defineProperty(exports, "md5File", { enumerable: true, get: function () { return helper_2.md5File; } });
+/**
+ * 整理 storage.batchDeleteFile 的逐文件删除结果，取出失败项并回填对应的 cloudPath
+ *
+ * 该接口逐文件返回 code，未失败的文件已经删除成功。把结果汇总成一条错误消息会丢掉逐项信息，
+ * 调用方无法区分「删掉了哪些」和「哪些本来就不存在」，因此保留结构化失败列表。
+ * 接口未保证 delete_list 与入参同序，这里按 fileID 反查。
+ */
+function collectBatchDeleteFailures(deleteList, fileIdList, cloudPathList) {
+    const cloudPathByFileId = new Map(fileIdList.map((fileId, index) => [fileId, cloudPathList[index]]));
+    return (deleteList || [])
+        .filter(item => item.code !== 'SUCCESS')
+        .map(item => ({
+        fileId: item.fileID,
+        cloudPath: cloudPathByFileId.get(item.fileID),
+        code: item.code
+    }));
+}
 class StorageService {
     constructor(environment) {
         this.environment = environment;
@@ -44,15 +63,17 @@ class StorageService {
      * 过滤目录占位对象。prefix 无前导斜杠，空串表示整桶（Hosting 桶请用 getRemoteManifestCustom）。
      */
     async getRemoteManifest(prefix) {
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         return this.getRemoteManifestCustom({
             prefix,
             bucket,
-            region
+            region,
+            basePath
         });
     }
     /**
      * 获取远端 manifest，支持自定义 Bucket 和 Region。prefix 规则同 getRemoteManifest。
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath
      */
     async getRemoteManifestCustom(options) {
         const fileList = await this.walkCloudDirCustom(options);
@@ -162,13 +183,14 @@ class StorageService {
      * 始终跳过 .cloudbase-backup/ 下的历史备份，避免根目录发布时递归备份。
      */
     async backupRemote(options) {
-        const { bucket, region, prefix, backupPrefix, parallel = 20 } = options;
+        const { bucket, region, prefix, backupPrefix, parallel = 20, basePath = '' } = options;
         // COS 对象 Key 不保留前导斜杠，统一规范化为 .cloudbase-backup/... 形式
         const normalizedBackupPrefix = backupPrefix.replace(/^\/+/, '').replace(/\/+$/, '');
         const remoteManifest = await this.getRemoteManifestCustom({
             bucket,
             region,
-            prefix
+            prefix,
+            basePath
         });
         // 过滤掉已备份的文件，避免根目录发布时递归备份旧备份，filesToBackup 存的是需要备份的文件
         const filesToBackup = remoteManifest.filter(item => !item.key.replace(/^\/+/, '').startsWith(CONSISTENT_DEPLOY_BACKUP_PREFIX));
@@ -183,11 +205,11 @@ class StorageService {
         filesToBackup.map(file => async () => {
             const destPath = `${normalizedBackupPrefix}/${file.key.replace(/^\/+/, '')}`;
             // 拼接复制源
-            const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent(file.key)}`;
+            const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent((0, storage_config_1.toPhysicalKey)(basePath, file.key))}`;
             const res = await putObjectCopy({
                 Bucket: bucket,
                 Region: region,
-                Key: destPath,
+                Key: (0, storage_config_1.toPhysicalKey)(basePath, destPath),
                 CopySource: copySource
             });
             if (res.statusCode !== 200) {
@@ -207,7 +229,7 @@ class StorageService {
      * 任一阶段失败都会抛错，由上层决定是否保留备份供人工恢复。
      */
     async restoreFromBackup(options) {
-        const { bucket, region, backupPrefix, overwrittenKeys, addedKeys, parallel = 20 } = options;
+        const { bucket, region, backupPrefix, overwrittenKeys, addedKeys, parallel = 20, basePath = '' } = options;
         // COS 对象 Key 不保留前导斜杠，与 backupRemote 的规范化规则保持一致
         const normalizedBackupPrefix = backupPrefix.replace(/^\/+/, '').replace(/\/+$/, '');
         if (overwrittenKeys.length > 0) {
@@ -216,11 +238,11 @@ class StorageService {
             const controller = new parallel_1.AsyncTaskParallelController(parallel, 50);
             controller.loadTasks(overwrittenKeys.map(key => async () => {
                 const sourcePath = `${normalizedBackupPrefix}/${key.replace(/^\/+/, '')}`;
-                const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent(sourcePath)}`;
+                const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent((0, storage_config_1.toPhysicalKey)(basePath, sourcePath))}`;
                 const res = await putObjectCopy({
                     Bucket: bucket,
                     Region: region,
-                    Key: key,
+                    Key: (0, storage_config_1.toPhysicalKey)(basePath, key),
                     CopySource: copySource
                 });
                 if (res.statusCode !== 200) {
@@ -236,7 +258,7 @@ class StorageService {
             }
         }
         if (addedKeys.length > 0) {
-            await this.deleteFileCustom(addedKeys, bucket, region);
+            await this.deleteFileCustom(addedKeys.map(key => (0, storage_config_1.toPhysicalKey)(basePath, key)), bucket, region);
         }
     }
     /**
@@ -244,14 +266,15 @@ class StorageService {
      * 备份目录以 . 开头，内部使用空 Marker 列举，不受默认排除规则影响。
      */
     async cleanupBackup(options) {
-        const { bucket, region, backupPrefix } = options;
+        const { bucket, region, backupPrefix, basePath } = options;
         // 备份目录以 . 开头，会被 walkCloudDirCustom 默认 marker='/' 排除，
         // 必须显式传 marker='' 才能列举到备份对象
         await this.deleteDirectoryCustom({
             cloudPath: backupPrefix,
             bucket,
             region,
-            marker: ''
+            marker: '',
+            basePath
         });
     }
     /**
@@ -260,7 +283,7 @@ class StorageService {
      * 单个删除失败记入 failedKeys，不影响其他文件。
      */
     async pruneRemote(options) {
-        const { bucket, region, prefix, removedKeys, parallel = 20 } = options;
+        const { bucket, region, prefix, removedKeys, parallel = 20, basePath = '' } = options;
         const normalizedPrefix = prefix.replace(/^\/+/, '').replace(/\/+$/, '');
         const prefixWithSlash = normalizedPrefix ? `${normalizedPrefix}/` : '';
         const backupPrefix = CONSISTENT_DEPLOY_BACKUP_PREFIX;
@@ -281,7 +304,7 @@ class StorageService {
                 await deleteObject({
                     Bucket: bucket,
                     Region: region,
-                    Key: key
+                    Key: (0, storage_config_1.toPhysicalKey)(basePath, key)
                 });
                 return { key };
             }
@@ -333,7 +356,7 @@ class StorageService {
      * cleanupBackup 显式清理备份。调用方（CLI）仍须在开启 prune 前要求用户二次确认。
      */
     async uploadDirectoryConsistent(options) {
-        const { localPath, cloudPath = '', bucket, region, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500, onProgress, onFileFinish, verify = false, safe = false, prune = false, entries } = options;
+        const { localPath, cloudPath = '', bucket, region, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500, onProgress, onFileFinish, verify = false, safe = false, prune = false, entries, basePath } = options;
         const resolvePath = path_1.default.resolve(localPath);
         const resolveLocalPath = path_1.default.join(resolvePath, path_1.default.sep);
         const filePaths = await this.walkLocalDir(resolveLocalPath, ignore);
@@ -350,7 +373,8 @@ class StorageService {
             const remoteSnapshot = await this.getRemoteManifestCustom({
                 bucket,
                 region,
-                prefix: cloudPath
+                prefix: cloudPath,
+                basePath
             });
             // 发布前快照同时用于 safe 回滚判定和 prune 待删文件判定。
             diff = this.diffManifest(localManifest, remoteSnapshot);
@@ -364,7 +388,8 @@ class StorageService {
                 region,
                 prefix: cloudPath,
                 backupPrefix,
-                parallel
+                parallel,
+                basePath
             });
         }
         try {
@@ -374,6 +399,7 @@ class StorageService {
                 entryFiles: entries,
                 bucket,
                 region,
+                basePath,
                 ignore,
                 fileId,
                 parallel,
@@ -387,7 +413,8 @@ class StorageService {
                 const remoteManifest = await this.getRemoteManifestCustom({
                     bucket,
                     region,
-                    prefix: cloudPath
+                    prefix: cloudPath,
+                    basePath
                 });
                 const verifyResult = this.verifyManifest(localManifest, remoteManifest);
                 if (!verifyResult.ok) {
@@ -404,6 +431,7 @@ class StorageService {
                 await this.restoreFromBackup({
                     bucket,
                     region,
+                    basePath,
                     backupPrefix,
                     overwrittenKeys: diff.overwritten,
                     addedKeys: diff.added,
@@ -421,6 +449,7 @@ class StorageService {
             ? await this.pruneRemote({
                 bucket,
                 region,
+                basePath,
                 prefix: cloudPath,
                 removedKeys: (diff === null || diff === void 0 ? void 0 : diff.removed) || [],
                 parallel
@@ -445,12 +474,13 @@ class StorageService {
      */
     async uploadFile(options) {
         const { localPath, cloudPath = '', onProgress } = options;
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         return this.uploadFileCustom({
             localPath,
             cloudPath,
             bucket,
             region,
+            basePath,
             onProgress
         });
     }
@@ -460,11 +490,12 @@ class StorageService {
      */
     async uploadFiles(options) {
         const { files, onProgress, parallel, onFileFinish, ignore, retryCount, retryInterval } = options;
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         return this.uploadFilesCustom({
             files,
             bucket,
             region,
+            basePath,
             ignore,
             parallel,
             onProgress,
@@ -475,13 +506,14 @@ class StorageService {
     }
     /**
      * 上传文件，支持自定义 Bucket 和 Region
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；fileId 始终按逻辑路径 cloudPath 获取
      * @param {string} localPath
      * @param {string} cloudPath
      * @param {string} bucket
      * @param {string} region
      */
     async uploadFileCustom(options) {
-        const { localPath, cloudPath, bucket, region, onProgress, fileId = true } = options;
+        const { localPath, cloudPath, bucket, region, onProgress, fileId = true, basePath = '' } = options;
         let localFilePath = '';
         let resolveLocalPath = path_1.default.resolve(localPath);
         (0, utils_1.checkFullAccess)(resolveLocalPath, true);
@@ -517,7 +549,7 @@ class StorageService {
                 onProgress,
                 Bucket: bucket,
                 Region: region,
-                Key: cloudPath,
+                Key: (0, storage_config_1.toPhysicalKey)(basePath, cloudPath),
                 StorageClass: 'STANDARD',
                 ContentLength: fileStats.size,
                 Body: fs_1.default.createReadStream(localFilePath),
@@ -529,7 +561,7 @@ class StorageService {
             res = await sliceUploadFile({
                 Bucket: bucket,
                 Region: region,
-                Key: cloudPath,
+                Key: (0, storage_config_1.toPhysicalKey)(basePath, cloudPath),
                 FilePath: localFilePath,
                 StorageClass: 'STANDARD',
                 AsyncLimit: 3,
@@ -557,7 +589,7 @@ class StorageService {
         const { localPath, cloudPath = '', ignore, onProgress, onFileFinish, parallel, retryCount, retryInterval } = options;
         // 此处不检查路径是否存在
         // 绝对路径 /var/blog/xxxx
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         return this.uploadDirectoryCustom({
             localPath,
             cloudPath,
@@ -566,6 +598,7 @@ class StorageService {
             retryInterval,
             bucket,
             region,
+            basePath,
             ignore,
             onProgress,
             onFileFinish
@@ -573,6 +606,7 @@ class StorageService {
     }
     /**
      * 上传文件夹，支持自定义 Region 和 Bucket
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath
      * @param {string} localPath
      * @param {string} cloudPath
      * @param {number} parallel
@@ -584,7 +618,7 @@ class StorageService {
      * @returns {Promise<void>}
      */
     async uploadDirectoryCustom(options) {
-        const { localPath, cloudPath, entryFiles, bucket, region, onProgress, onFileFinish, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500 } = options;
+        const { localPath, cloudPath, entryFiles, bucket, region, basePath, onProgress, onFileFinish, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500 } = options;
         // 此处不检查路径是否存在
         // 绝对路径 /var/blog/xxxx
         const resolvePath = path_1.default.resolve(localPath);
@@ -622,7 +656,8 @@ class StorageService {
             .map(info => () => this.createCloudDirectroyCustom({
             cloudPath: info.cloudFileKey,
             bucket,
-            region
+            region,
+            basePath
         }));
         creatingDirController.loadTasks(creatingDirTasks);
         await creatingDirController.run();
@@ -664,6 +699,7 @@ class StorageService {
             files: resourceFiles,
             bucket,
             region,
+            basePath,
             ignore: [],
             onProgress,
             onFileFinish,
@@ -677,6 +713,7 @@ class StorageService {
             files: entryUploadFiles,
             bucket,
             region,
+            basePath,
             ignore: [],
             onProgress,
             onFileFinish,
@@ -688,7 +725,7 @@ class StorageService {
     }
     async uploadFilesCustom(options) {
         var _a;
-        const { files, bucket, region, ignore, onProgress, onFileFinish, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500 } = options;
+        const { files, bucket, region, basePath = '', ignore, onProgress, onFileFinish, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500 } = options;
         if (!files || !files.length) {
             return;
         }
@@ -710,6 +747,7 @@ class StorageService {
                 fileList,
                 bucket,
                 region,
+                basePath,
                 fileId,
                 retryCount,
                 retryInterval,
@@ -734,6 +772,7 @@ class StorageService {
             fileList,
             bucket,
             region,
+            basePath,
             fileId,
             parallel,
             retryCount: 0, // 并行阶段不重试，失败后交给串行阶段
@@ -747,6 +786,7 @@ class StorageService {
                 fileList: parallelFailedFiles,
                 bucket,
                 region,
+                basePath,
                 fileId: false, // 串行重试不需要再获取 fileId
                 retryCount,
                 retryInterval,
@@ -774,7 +814,7 @@ class StorageService {
      */
     // eslint-disable-next-line @typescript-eslint/member-ordering
     async uploadFilesSerial(options) {
-        const { fileList, bucket, region, fileId, retryCount, retryInterval, onFileFinish } = options;
+        const { fileList, bucket, region, basePath, fileId, retryCount, retryInterval, onFileFinish } = options;
         let uploadedCount = 0;
         let failedFiles = [];
         for (let i = 0; i < fileList.length; i++) {
@@ -789,7 +829,7 @@ class StorageService {
                     await putObject({
                         Bucket: bucket,
                         Region: region,
-                        Key: file.cloudFileKey,
+                        Key: (0, storage_config_1.toPhysicalKey)(basePath, file.cloudFileKey),
                         Body: fs_1.default.createReadStream(file.filePath),
                         ContentLength: fs_1.default.statSync(file.filePath).size,
                     });
@@ -840,7 +880,7 @@ class StorageService {
      */
     // eslint-disable-next-line @typescript-eslint/member-ordering
     async uploadFilesParallel(options) {
-        const { fileList, bucket, region, fileId, parallel, retryCount, retryInterval, onProgress, onFileFinish } = options;
+        const { fileList, bucket, region, basePath, fileId, parallel, retryCount, retryInterval, onProgress, onFileFinish } = options;
         // 生成上传文件属性
         const tasks = fileList.map(stats => async () => {
             let cosFileId;
@@ -851,7 +891,7 @@ class StorageService {
             return {
                 Bucket: bucket,
                 Region: region,
-                Key: stats.cloudFileKey,
+                Key: (0, storage_config_1.toPhysicalKey)(basePath, stats.cloudFileKey),
                 FilePath: stats.filePath,
                 'x-cos-meta-fileid': cosFileId
             };
@@ -887,7 +927,8 @@ class StorageService {
                         console.warn('[parallel-upload] onFileFinish received null/undefined file');
                         return;
                     }
-                    const fileKey = file.Key || file.cloudFileKey;
+                    // file.Key 是 COS 物理 Key，回调与失败重试统一使用逻辑路径
+                    const fileKey = (0, storage_config_1.toLogicalPath)(basePath, file.Key || file.cloudFileKey);
                     if (error) {
                         batchFailedFiles.push({
                             filePath: file.FilePath || file.filePath,
@@ -900,7 +941,9 @@ class StorageService {
                     }
                     // 继续调用用户传入的回调（转换参数格式）
                     // 注意：cloudFileKey 和 filePath 是 CLI 期望的格式
-                    onFileFinish === null || onFileFinish === void 0 ? void 0 : onFileFinish(error, result, Object.assign(Object.assign({}, file), { cloudFileKey: fileKey, filePath: file.FilePath || file.filePath }));
+                    onFileFinish === null || onFileFinish === void 0 ? void 0 : onFileFinish(error, result, Object.assign(Object.assign({}, file), { 
+                        // Key 同样返回逻辑路径，避免调用方（如 tcb storage upload）展示带 BasePath 的物理 Key
+                        Key: fileKey, cloudFileKey: fileKey, filePath: file.FilePath || file.filePath }));
                 }
             };
             try {
@@ -921,7 +964,7 @@ class StorageService {
                     // onFileFinish 未被调用，整个批次失败
                     allFailedFiles.push(...batchFiles.map(f => ({
                         filePath: f.FilePath || f.filePath,
-                        cloudFileKey: f.Key || f.cloudFileKey,
+                        cloudFileKey: (0, storage_config_1.toLogicalPath)(basePath, f.Key || f.cloudFileKey),
                         error: error.message || String(error)
                     })));
                 }
@@ -945,24 +988,26 @@ class StorageService {
      * @param {string} cloudPath
      */
     async createCloudDirectroy(cloudPath) {
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         await this.createCloudDirectroyCustom({
             cloudPath,
             bucket,
-            region
+            region,
+            basePath
         });
     }
     /**
      * 创建一个空的文件夹，支持自定义 Region 和 Bucket
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath
      * @param {string} cloudPath
      * @param {string} bucket
      * @param {string} region
      */
     async createCloudDirectroyCustom(options) {
-        const { cloudPath, bucket, region } = options;
+        const { cloudPath, bucket, region, basePath = '' } = options;
         const cos = this.getCos();
         const putObject = util_1.default.promisify(cos.putObject).bind(cos);
-        const dirKey = this.getCloudKey(cloudPath);
+        const dirKey = (0, storage_config_1.toPhysicalKey)(basePath, this.getCloudKey(cloudPath));
         const res = await putObject({
             Bucket: bucket,
             Region: region,
@@ -1125,15 +1170,17 @@ class StorageService {
             },
             method: 'POST'
         });
-        const failedList = res.data.delete_list
-            .filter(item => item.code !== 'SUCCESS')
-            .map(item => `${item.fileID} : ${item.code}`);
-        if (failedList.length) {
-            throw new error_1.CloudBaseError(`部分删除文件失败：${JSON.stringify(failedList)}`);
+        const failed = collectBatchDeleteFailures(res.data.delete_list, fileIdList, cloudPathList);
+        if (failed.length) {
+            const failedList = failed.map(item => `${item.fileId} : ${item.code}`);
+            throw new error_1.CloudBaseError(`部分删除文件失败：${JSON.stringify(failedList)}`, {
+                meta: { failed, total: cloudPathList.length }
+            });
         }
     }
     /**
      * 删除文件，可以指定 Bucket 和 Region
+     * 不会自动拼接环境的共享桶 BasePath，cloudPathList 按 COS 原始 Key 处理
      * @param {string[]} cloudPathList
      * @param {string} bucket
      * @param {string} region
@@ -1164,11 +1211,11 @@ class StorageService {
     async getFileInfo(cloudPath) {
         const cos = this.getCos();
         const headObject = util_1.default.promisify(cos.headObject).bind(cos);
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         const { headers } = await headObject({
             Bucket: bucket,
             Region: region,
-            Key: cloudPath
+            Key: (0, storage_config_1.toPhysicalKey)(basePath, cloudPath)
         });
         if (!headers) {
             throw new error_1.CloudBaseError(`[${cloudPath}] 获取文件信息失败`);
@@ -1188,31 +1235,34 @@ class StorageService {
      * @returns {Promise<void>}
      */
     async deleteDirectory(cloudPath) {
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         return this.deleteDirectoryCustom({
             cloudPath,
             bucket,
-            region
+            region,
+            basePath
         });
     }
     /**
      * 删除文件，可以指定 bucket 和 region
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；返回的 Key 为逻辑路径
      * @param {string} cloudPath
      * @param {string} bucket
      * @param {string} region
      * @returns {Promise<void>}
      */
     async deleteDirectoryCustom(options) {
-        const { cloudPath, bucket, region, marker } = options;
+        const { cloudPath, bucket, region, marker, basePath = '' } = options;
         const key = this.getCloudKey(cloudPath);
         const cos = this.getCos();
         const deleteMultipleObject = util_1.default.promisify(cos.deleteMultipleObject).bind(cos);
-        // 遍历获取全部文件
+        // 遍历获取全部文件（返回的 Key 为逻辑路径）
         const files = await this.walkCloudDirCustom({
             bucket,
             region,
             prefix: key,
-            marker
+            marker,
+            basePath
         });
         // 文件为空时，不能调用删除接口
         if (!files.length) {
@@ -1231,16 +1281,17 @@ class StorageService {
         const tasks = sliceGroup.map(group => deleteMultipleObject({
             Bucket: bucket,
             Region: region,
-            Objects: group.map(file => ({ Key: file.Key }))
+            Objects: group.map(file => ({ Key: (0, storage_config_1.toPhysicalKey)(basePath, file.Key) }))
         }));
         // 删除多个文件
         const taskRes = await Promise.all(tasks);
-        // 合并响应结果
+        // 合并响应结果，Key 映射回逻辑路径
+        const toLogicalItems = (items) => basePath ? items.map(item => (Object.assign(Object.assign({}, item), { Key: (0, storage_config_1.toLogicalPath)(basePath, item.Key) }))) : items;
         const Deleted = taskRes.map(_ => _.Deleted).reduce((prev, next) => [...prev, ...next], []);
         const Error = taskRes.map(_ => _.Error).reduce((prev, next) => [...prev, ...next], []);
         return {
-            Deleted,
-            Error
+            Deleted: toLogicalItems(Deleted),
+            Error: toLogicalItems(Error)
         };
     }
     async getStorageAcl(options) {
@@ -1311,16 +1362,18 @@ class StorageService {
      * @returns {Promise<IListFileInfo[]>}
      */
     async walkCloudDir(prefix, marker) {
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         return this.walkCloudDirCustom({
             prefix,
             bucket,
             region,
-            marker
+            marker,
+            basePath
         });
     }
     /**
      * 遍历云端文件夹，支持自定义 Bucket 和 Region
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；传入后返回的 Key 为逻辑路径
      * @param {string} prefix
      * @param {string} [marker]
      * @param {string} bucket
@@ -1328,12 +1381,13 @@ class StorageService {
      * @returns {Promise<IListFileInfo[]>}
      */
     async walkCloudDirCustom(options) {
-        const { prefix, bucket, region, marker = '/' } = options;
+        const { prefix, bucket, region, marker = '/', basePath = '' } = options;
         let fileList = [];
         const cos = this.getCos();
         const getBucket = util_1.default.promisify(cos.getBucket).bind(cos);
-        const prefixKey = this.getCloudKey(prefix);
-        let currentMarker = marker;
+        const prefixKey = (0, storage_config_1.toPhysicalKey)(basePath, this.getCloudKey(prefix));
+        // Marker 按字典序生效：默认 '/' 用于排除 . 开头的 Key，共享桶下同样放到 basePath 之后（如 base//）
+        let currentMarker = marker ? (0, storage_config_1.toPhysicalKey)(basePath, '').concat(marker) : marker;
         let isTruncated = true;
         // 使用循环替代递归
         while (isTruncated) {
@@ -1350,7 +1404,10 @@ class StorageService {
                 currentMarker = res.NextMarker;
             }
         }
-        return fileList;
+        if (!basePath) {
+            return fileList;
+        }
+        return fileList.map(file => (Object.assign(Object.assign({}, file), { Key: (0, storage_config_1.toLogicalPath)(basePath, file.Key) })));
     }
     /**
      * 列出指定目录下的文件和子目录（不递归，只列当前层）
@@ -1359,7 +1416,7 @@ class StorageService {
      * @returns {Promise<{ files: IListFileInfo[], directories: string[] }>}
      */
     async listCurrentDirectory(dirPath = '') {
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         const cos = this.getCos();
         const getBucket = util_1.default.promisify(cos.getBucket).bind(cos);
         // 确保目录路径以 / 结尾（除了根目录）
@@ -1367,6 +1424,7 @@ class StorageService {
         if (prefix && !prefix.endsWith('/')) {
             prefix = prefix + '/';
         }
+        const physicalPrefix = (0, storage_config_1.toPhysicalKey)(basePath, prefix);
         const files = [];
         const directories = [];
         let marker = '';
@@ -1375,20 +1433,20 @@ class StorageService {
             const res = await getBucket({
                 Bucket: bucket,
                 Region: region,
-                Prefix: prefix,
+                Prefix: physicalPrefix,
                 Delimiter: '/', // 关键：使用分隔符，不递归子目录
                 MaxKeys: 1000,
                 Marker: marker
             });
-            // 文件列表（不包含子目录）
+            // 文件列表（不包含子目录），Key 映射回逻辑路径
             if (res.Contents) {
                 // 过滤掉目录本身（Key === prefix 的情况）
-                const fileItems = res.Contents.filter((item) => item.Key !== prefix);
+                const fileItems = res.Contents.filter((item) => item.Key !== physicalPrefix).map((item) => (Object.assign(Object.assign({}, item), { Key: (0, storage_config_1.toLogicalPath)(basePath, item.Key) })));
                 files.push(...fileItems);
             }
             // 子目录列表（CommonPrefixes）
             if (res.CommonPrefixes) {
-                const dirs = res.CommonPrefixes.map((item) => item.Prefix);
+                const dirs = res.CommonPrefixes.map((item) => (0, storage_config_1.toLogicalPath)(basePath, item.Prefix));
                 directories.push(...dirs);
             }
             isTruncated = res.IsTruncated === 'true' || res.IsTruncated === true;
@@ -1520,18 +1578,21 @@ class StorageService {
      */
     async getBucket(options) {
         // const { bucket } = this.getStorageConfig()
-        const { prefix, maxKeys, marker, bucket, region } = options;
+        const { prefix, maxKeys, marker, bucket, region, basePath = '' } = options;
         const cos = this.getCos();
         const getBucket = util_1.default.promisify(cos.getBucket).bind(cos);
-        const prefixKey = this.getCloudKey(prefix);
+        const prefixKey = (0, storage_config_1.toPhysicalKey)(basePath, this.getCloudKey(prefix));
         const res = await getBucket({
             Bucket: bucket,
             Region: region,
             Prefix: prefixKey,
             MaxKeys: maxKeys,
-            Marker: marker
+            Marker: basePath && marker ? (0, storage_config_1.toPhysicalKey)(basePath, marker) : marker
         });
-        return res;
+        if (!basePath) {
+            return res;
+        }
+        return Object.assign(Object.assign({}, res), { Prefix: res.Prefix ? (0, storage_config_1.toLogicalPath)(basePath, res.Prefix) : res.Prefix, Contents: (res.Contents || []).map(item => (Object.assign(Object.assign({}, item), { Key: (0, storage_config_1.toLogicalPath)(basePath, item.Key) }))), NextMarker: res.NextMarker ? (0, storage_config_1.toLogicalPath)(basePath, res.NextMarker) : res.NextMarker });
     }
     // ===== 复制/移动/搜索方法 =====
     /**
@@ -1544,7 +1605,7 @@ class StorageService {
      */
     async copyFile(options) {
         const { sourcePath, destPath, force = false, skipExisting = false } = options;
-        const { bucket, region } = this.getStorageConfig();
+        const { bucket, region, basePath } = this.getStorageConfig();
         // 1. 检查源文件是否存在
         let sourceFileInfo;
         try {
@@ -1593,11 +1654,11 @@ class StorageService {
         // CopySource 格式: {bucket}.cos.{region}.myqcloud.com/{key}
         // 注意: key 需要 URL 编码
         // cspell:ignore myqcloud
-        const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent(sourcePath)}`;
+        const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent((0, storage_config_1.toPhysicalKey)(basePath, sourcePath))}`;
         const res = await putObjectCopy({
             Bucket: bucket,
             Region: region,
-            Key: destPath,
+            Key: (0, storage_config_1.toPhysicalKey)(basePath, destPath),
             CopySource: copySource
         });
         if (res.statusCode !== 200) {
@@ -1725,11 +1786,11 @@ class StorageService {
         const result = await this.copyFile(options);
         if (result.status === 'copied') {
             // 复制成功后使用 COS SDK 直接删除源文件
-            const { bucket, region } = this.getStorageConfig();
+            const { bucket, region, basePath } = this.getStorageConfig();
             const cos = this.getCos();
             const deleteObject = util_1.default.promisify(cos.deleteObject).bind(cos);
             // 注意：文件路径不需要用 getCloudKey()，getCloudKey() 会在末尾加 /，用于目录
-            const sourceKey = options.sourcePath;
+            const sourceKey = (0, storage_config_1.toPhysicalKey)(basePath, options.sourcePath);
             try {
                 await deleteObject({
                     Bucket: bucket,
@@ -1758,7 +1819,7 @@ class StorageService {
             .map(r => r.sourcePath);
         if (copiedFiles.length > 0) {
             // 使用 COS SDK deleteMultipleObject 批量删除源文件
-            const { bucket, region } = this.getStorageConfig();
+            const { bucket, region, basePath } = this.getStorageConfig();
             const cos = this.getCos();
             const deleteMultipleObject = util_1.default.promisify(cos.deleteMultipleObject).bind(cos);
             // COS deleteMultipleObject 单次最多删除 1000 个对象，这里按 500 分片
@@ -1775,12 +1836,12 @@ class StorageService {
                     const res = await deleteMultipleObject({
                         Bucket: bucket,
                         Region: region,
-                        Objects: group.map(file => ({ Key: file }))
+                        Objects: group.map(file => ({ Key: (0, storage_config_1.toPhysicalKey)(basePath, file) }))
                     });
                     // 检查部分删除失败的情况
                     if (res.Error && res.Error.length > 0) {
                         for (const err of res.Error) {
-                            deleteFailedFiles.set(err.Key, err.Message || 'Unknown error');
+                            deleteFailedFiles.set((0, storage_config_1.toLogicalPath)(basePath, err.Key), err.Message || 'Unknown error');
                         }
                     }
                 }
@@ -1908,7 +1969,7 @@ class StorageService {
         // env / proxy
         const authConfig = this.environment.getAuthConfig();
         const { proxy } = authConfig;
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         // 路径编码：保留 "/" 层级，仅编码每段
         const encodedBucketId = encodeURIComponent(bucketId);
@@ -2019,7 +2080,7 @@ class StorageService {
         if (!accessToken || typeof accessToken !== 'string') {
             throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2083,7 +2144,7 @@ class StorageService {
                 throw new error_1.CloudBaseError('prefixes 中的每一项必须是非空字符串');
             }
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/${encodedBucketId}`;
@@ -2154,7 +2215,7 @@ class StorageService {
         if (!accessToken || typeof accessToken !== 'string') {
             throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/copy`;
         const headers = {
@@ -2233,7 +2294,7 @@ class StorageService {
         if (!accessToken || typeof accessToken !== 'string') {
             throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/move`;
         const body = {
@@ -2329,7 +2390,7 @@ class StorageService {
                 sortBy.order = normalizedOrder;
             }
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/list/${encodedBucketId}`;
@@ -2401,7 +2462,7 @@ class StorageService {
         if (!accessToken || typeof accessToken !== 'string') {
             throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2475,7 +2536,7 @@ class StorageService {
         if (!accessToken || typeof accessToken !== 'string') {
             throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/sign/${encodedBucketId}`;
@@ -2535,7 +2596,7 @@ class StorageService {
         if (!accessToken || typeof accessToken !== 'string') {
             throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2604,7 +2665,7 @@ class StorageService {
         if (localPath && body) {
             throw new error_1.CloudBaseError('localPath 与 body 只能二选一');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2694,7 +2755,7 @@ class StorageService {
         if (!allowedMethods.includes(normalizedMethod)) {
             throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2782,7 +2843,7 @@ class StorageService {
         if (!allowedMethods.includes(normalizedMethod)) {
             throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2868,7 +2929,7 @@ class StorageService {
         if (!allowedMethods.includes(normalizedMethod)) {
             throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -2934,7 +2995,7 @@ class StorageService {
         if (!allowedMethods.includes(normalizedMethod)) {
             throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -3000,7 +3061,7 @@ class StorageService {
         if (!allowedMethods.includes(normalizedMethod)) {
             throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -3075,7 +3136,7 @@ class StorageService {
         if (!objectName || typeof objectName !== 'string') {
             throw new error_1.CloudBaseError('objectName 必须是非空字符串');
         }
-        const { env } = this.getStorageConfig();
+        const env = this.environment.getEnvId();
         const envId = envIdOverride || env;
         const encodedBucketId = encodeURIComponent(bucketId);
         const encodedObjectName = objectName
@@ -3182,19 +3243,12 @@ class StorageService {
         return `cloud://${env}.${bucket}/${cloudPath}`;
     }
     /**
-     * 获取存储桶配置
+     * 获取存储桶配置，兼容共享桶（ExternalStorage）环境
+     * basePath 为共享桶内的目录前缀，普通环境为空串
      */
     getStorageConfig() {
-        var _a;
-        const envConfig = this.environment.lazyEnvironmentConfig;
-        const storageConfig = (_a = envConfig === null || envConfig === void 0 ? void 0 : envConfig.Storages) === null || _a === void 0 ? void 0 : _a[0];
-        const { Region, Bucket } = storageConfig;
-        const region = process.env.TCB_COS_REGION || Region;
-        return {
-            region,
-            bucket: Bucket,
-            env: envConfig.EnvId
-        };
+        const config = (0, storage_config_1.resolveStorageConfig)(this.environment.lazyEnvironmentConfig);
+        return Object.assign(Object.assign({}, config), { region: process.env.TCB_COS_REGION || config.region });
     }
     /**
      * 带重试功能的上传多文件函数
@@ -3399,6 +3453,7 @@ __decorate([
     (0, utils_1.preLazy)()
     /**
      * 上传文件（支持精准重试失败文件）
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；onFileFinish 回调中的 cloudFileKey 为逻辑路径
      *
      * 智能混合模式（默认）：
      * 1. 先并行快速上传（速度快）