@cloudbase/manager-node 5.7.0-beta.0 → 5.7.0-beta.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## @cloudbase/manager-node v5.6.8 版本发布 🚀(2026-08-11)
+
+- 新增 封装 DescribeReleaseOrder 接口
+
+---
+
 ## @cloudbase/manager-node v5.6.7 版本发布 🚀(2026-08-05)
 
 - 新增 describeServerManageTask 及版本详情/回滚/删除接口

package/lib/cloudrun/index.js

@@ -101,6 +101,21 @@ class CloudRunService {
         const envConfig = this.environment.lazyEnvironmentConfig;
         return this.tcbrService.request('DescribeServerManageTask', Object.assign({ EnvId: envConfig.EnvId, ServerName: params.serverName, TaskId: (_a = params.taskId) !== null && _a !== void 0 ? _a : 0 }, (params.operatorRemark ? { OperatorRemark: params.operatorRemark } : {})));
     }
+    /**
+     * 查询发布单信息（DescribeReleaseOrder）
+     * @param {IDescribeReleaseOrderParams} params 查询参数
+     * @returns {Promise<IDescribeReleaseOrderResponse>} 发布单详情
+     */
+    async describeReleaseOrder(params) {
+        var _a, _b;
+        const envConfig = this.environment.lazyEnvironmentConfig;
+        const serverName = (_a = params === null || params === void 0 ? void 0 : params.ServerName) === null || _a === void 0 ? void 0 : _a.trim();
+        const status = (_b = params === null || params === void 0 ? void 0 : params.Status) === null || _b === void 0 ? void 0 : _b.trim();
+        if (!serverName) {
+            throw new Error('Missing required parameters: ServerName');
+        }
+        return this.tcbrService.request('DescribeReleaseOrder', Object.assign({ EnvId: envConfig.EnvId, ServerName: serverName }, (status ? { Status: status } : {})));
+    }
     /**
      * 获取云托管服务列表
      * @param {Object} [params] 查询参数
@@ -521,6 +536,9 @@ __decorate([
 __decorate([
     (0, utils_1.preLazy)()
 ], CloudRunService.prototype, "describeServerManageTask", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], CloudRunService.prototype, "describeReleaseOrder", null);
 __decorate([
     (0, utils_1.preLazy)()
 ], CloudRunService.prototype, "list", null);

package/lib/deploy/GatewayDeployer.js

@@ -72,13 +72,39 @@ class GatewayDeployer {
                 });
             }
             if (toCreate.length > 0) {
-                await envService.createHttpServiceRoute({
-                    EnvId: envId,
-                    Domain: {
-                        Domain: domain,
-                        Routes: toCreate
+                try {
+                    await envService.createHttpServiceRoute({
+                        EnvId: envId,
+                        Domain: {
+                            Domain: domain,
+                            Routes: toCreate
+                        }
+                    });
+                }
+                catch (e) {
+                    // 路由已存在（getExistingRoutes 因域名格式差异漏查，导致误判 create）：
+                    // 幂等降级为「逐个创建，已存在的跳过」，避免整批失败
+                    if (!this.isAlreadyExistsError(e)) {
+                        throw e;
                     }
-                });
+                    for (const route of toCreate) {
+                        try {
+                            await envService.createHttpServiceRoute({
+                                EnvId: envId,
+                                Domain: {
+                                    Domain: domain,
+                                    Routes: [route]
+                                }
+                            });
+                        }
+                        catch (e2) {
+                            // 该条已存在 → 跳过（已收敛）；否则（环境/资源不存在等真实失败）必须抛出，避免静默吞掉
+                            if (!this.isAlreadyExistsError(e2)) {
+                                throw e2;
+                            }
+                        }
+                    }
+                }
             }
             deployedDomains.push(domain);
             for (let i = 0; i < parsedRoutes.length; i++) {
@@ -197,24 +223,80 @@ class GatewayDeployer {
     }
     /**
      * 查询指定域名下已存在的路由（幂等收敛用），返回 Map<path, 云端路由详情>
+     *
+     * 匹配策略（优先级从高到低）：
+     * 1. 用 Filters 精确查询目标域名：DescribeHTTPServiceRoute 不带 Filters 时返回的 Domains
+     *    列表可能不完整（如 lowcode 环境 TotalCount=67 但 Domains 只返回部分，HTTPSERVICE 的
+     *    .app.tcloudbase.com 域名缺失），导致云端已有路由查不到被误判为 create
+     * 2. 降级：不带 Filters 全量查询，按域名归一化匹配（去协议/尾斜杠/转小写）
+     *    若目标域名找不到则返回空（保留 domain 维度，避免把其他域名同 path 误判为已存在）
      */
     async getExistingRoutes(envId, domain) {
+        var _a;
+        const normalizedTarget = this.normalizeDomain(domain);
+        // 1. Filters 精确查询目标域名（deleteCustomDomain 同款用法）
         try {
             const res = await this.environment.getEnvService().describeHttpServiceRoute({
-                EnvId: envId
+                EnvId: envId,
+                Filters: [{ Name: 'Domain', Values: [domain] }]
             });
-            const targetDomain = (res.Domains || []).find(d => d.Domain === domain);
+            const targetDomain = (res.Domains || []).find((d) => this.normalizeDomain(d.Domain) === normalizedTarget);
             const map = new Map();
             for (const route of (targetDomain === null || targetDomain === void 0 ? void 0 : targetDomain.Routes) || []) {
                 map.set(route.Path, route);
             }
+            if (map.size > 0) {
+                return map;
+            }
+        }
+        catch (_b) {
+            // Filters 查询失败（环境不支持）→ 走降级
+        }
+        // 2. 降级：全量查询 + 归一化匹配（严格保留域名维度）
+        try {
+            const res = await this.environment.getEnvService().describeHttpServiceRoute({
+                EnvId: envId
+            });
+            const targetDomain = (res.Domains || []).find((d) => this.normalizeDomain(d.Domain) === normalizedTarget);
+            const map = new Map();
+            if ((_a = targetDomain === null || targetDomain === void 0 ? void 0 : targetDomain.Routes) === null || _a === void 0 ? void 0 : _a.length) {
+                for (const route of targetDomain.Routes) {
+                    map.set(route.Path, route);
+                }
+            }
+            // 不再按 path 跨域兜底归并：
+            // 路由唯一键是 (domain, path)，不同域名同 path 合法；
+            // 若目标域名缺失，返回空并交由 create + AlreadyExists 幂等降级收敛，避免误判 skip/update。
             return map;
         }
-        catch (_a) {
+        catch (_c) {
             // 查询失败（首次部署/环境未初始化）视为无已存在路由
             return new Map();
         }
     }
+    /**
+     * 域名归一化：去协议、去尾斜杠、转小写（用于幂等收敛的域名匹配）
+     */
+    normalizeDomain(domain) {
+        if (!domain)
+            return '';
+        return domain.replace(/^https?:\/\//, '').replace(/\/+$/, '').toLowerCase();
+    }
+    /**
+     * 判断错误是否属于「路由已存在/已占用」类（幂等降级专用）
+     *
+     * 只匹配明确的重复/占用语义（code 含 AlreadyExists/Duplicate/ResourceInUse/Conflict，
+     * 或 message 含 already exists），并显式排除否定语义（not exists/not found 等），
+     * 避免把「环境/资源不存在」等真实失败误判为「已存在」而被静默跳过
+     */
+    isAlreadyExistsError(e) {
+        const msg = String((e === null || e === void 0 ? void 0 : e.message) || '') + String((e === null || e === void 0 ? void 0 : e.code) || '');
+        // 否定语义优先：资源/环境不存在 → 不是「已存在」，必须抛出让调用方感知真实失败
+        if (/not\s*exists?|doesn't?\s*exist|does\s+not\s+exist|not\s*found/i.test(msg)) {
+            return false;
+        }
+        return /already\s*exists?|already[_\s-]*exists|AlreadyExists|ALREADY_EXISTS|RESOURCE_ALREADY_EXISTS|Duplicate|ResourceInUse|ResourceOccupied|Conflict|已存在/i.test(msg);
+    }
     /**
      * 判断期望路由与云端已存在路由是否一致
      *
@@ -395,8 +477,16 @@ class GatewayDeployer {
                     `或为该路由显式配置 pathRewrite.prefix/staticStorePrefix 以引用已部署的托管实例`);
             }
             // 未显式配置时自动生成 Prefix = hosting 部署路径
+            // 透传会覆盖路径重写：用户显式开启 enablePathTransmission=true 时与自动重写冲突，
+            // 不再静默强制关闭（避免反向改写云端用户显式配置），明确报错让用户二选一
             if (hosting.deployPath) {
-                return Object.assign(Object.assign({}, parsed), { PathRewrite: { Prefix: hosting.deployPath } });
+                if (route.enablePathTransmission === true) {
+                    throw new error_1.CloudBaseError(`网关路由 ${route.path} 目标为 hosting:${hostingName} 且未显式配置 pathRewrite：` +
+                        `部署将自动生成 PathRewrite.Prefix=${hosting.deployPath}，` +
+                        `但 enablePathTransmission=true 会覆盖路径重写导致请求打不到托管部署路径。` +
+                        `请删除 enablePathTransmission，或显式配置 pathRewrite.prefix`);
+                }
+                return Object.assign(Object.assign({}, parsed), { EnablePathTransmission: false, PathRewrite: { Prefix: hosting.deployPath } });
             }
             return parsed;
         }

package/lib/deploy/StaticDeployer.js

@@ -57,6 +57,7 @@ class StaticDeployer {
      * 访问地址 = https://{CdnDomain}{deployPath}（与 tcb hosting deploy 一致）
      */
     async deployHosting(options) {
+        var _a, _b;
         const { config, cwd = process.cwd() } = options;
         const name = config.name || 'default';
         const root = path_1.default.resolve(cwd, config.root || '.');
@@ -81,13 +82,49 @@ class StaticDeployer {
         await this.environment.getHostingService().uploadFiles(hostingOptions);
         // SPA 回退：
         // - true：404 时返回 index.html（OriginalHttpStatus=Disabled 保留 200，Charity404=Disabled 防公益页面覆盖）
+        //   ErrorDocument 不带 deployPath 前缀：TCB 托管会把 ErrorDocument 相对 deployPath 解析
+        //   （index.html → web-pay-0804-test-ignore8/index.html），加前缀反而双重嵌套找不到
         // - false：显式取消，重置 ErrorDocument 为空（静态托管首页 IndexDocument 保留）
         // - undefined：不关心，保持云端现状
         // 注意：putBucketWebsite 是整体覆盖，设置前先读取现有配置并保留 RoutingRules + AutoAddressing，
         // 否则会清空用户之前在控制台配置的路由规则（如路径前缀重写/错误码重定向）和忽略 .html 扩展名能力
+        // 仅移除当前 deployPath 对应的 SPA 回退规则：
+        // cloudPath='/' => index.html；cloudPath='/web' => web/index.html
+        // 不能泛化删除所有 */index.html，否则会误删用户自定义的 404 重定向规则
+        const indexKey = cloudPath === '/' ? 'index.html' : `${cloudPath.replace(/^\//, '')}/index.html`;
+        const isCurrentSpaFallbackRedirect = (r) => {
+            if (r.httpErrorCodeReturnedEquals !== '404')
+                return false;
+            return r.replaceKeyWith === indexKey;
+        };
+        // 开启 SPA 回退时，清理历史上指向 index.html 的 404 重定向（含 ReplaceKeyPrefixWith）
+        // 避免 302 到 cos-website 与 ErrorDocument= index.html 冲突
+        const isLegacySpaIndexFallbackRedirect = (r) => {
+            var _a, _b;
+            if (r.httpErrorCodeReturnedEquals !== '404')
+                return false;
+            if (r.replaceKeyWith === 'index.html')
+                return true;
+            if ((_a = r.replaceKeyWith) === null || _a === void 0 ? void 0 : _a.endsWith('/index.html'))
+                return true;
+            if (r.replaceKeyPrefixWith === 'index.html')
+                return true;
+            if ((_b = r.replaceKeyPrefixWith) === null || _b === void 0 ? void 0 : _b.endsWith('/index.html'))
+                return true;
+            return false;
+        };
         if (config.spaFallback === true) {
             try {
-                await this.environment.getHostingService().setWebsiteDocument(Object.assign({ indexDocument: 'index.html', errorDocument: 'index.html', originalHttpStatus: 'Disabled', charity404: 'Disabled' }, (await this.preserveWebsiteConfig())));
+                const preserved = await this.preserveWebsiteConfig();
+                await this.environment.getHostingService().setWebsiteDocument({
+                    indexDocument: 'index.html',
+                    errorDocument: 'index.html',
+                    originalHttpStatus: 'Disabled',
+                    charity404: 'Disabled',
+                    routingRules: (preserved.routingRules || []).filter((r) => !isLegacySpaIndexFallbackRedirect(r)),
+                    // 优先保留云端 AutoAddressing（避免覆盖控制台配置），缺失时再兜底 Disabled
+                    autoAddressing: (_a = preserved.autoAddressing) !== null && _a !== void 0 ? _a : 'Disabled'
+                });
             }
             catch (e) {
                 throw new error_1.CloudBaseError(`[${name}] 设置 SPA 回退失败（spaFallback: true）：${(e === null || e === void 0 ? void 0 : e.message) || String(e)}`);
@@ -95,7 +132,16 @@ class StaticDeployer {
         }
         else if (config.spaFallback === false) {
             try {
-                await this.environment.getHostingService().setWebsiteDocument(Object.assign({ indexDocument: 'index.html', errorDocument: '' }, (await this.preserveWebsiteConfig())));
+                const preserved = await this.preserveWebsiteConfig();
+                await this.environment.getHostingService().setWebsiteDocument({
+                    indexDocument: 'index.html',
+                    errorDocument: '',
+                    // 仅移除当前 deployPath 对应的 SPA 回退规则（404 + replaceKeyWith=indexKey）
+                    // 保留用户自定义 404 规则和其他路由规则
+                    routingRules: (preserved.routingRules || []).filter((r) => !isCurrentSpaFallbackRedirect(r)),
+                    // 优先保留云端 AutoAddressing（避免覆盖控制台配置），缺失时再兜底 Enabled
+                    autoAddressing: (_b = preserved.autoAddressing) !== null && _b !== void 0 ? _b : 'Enabled'
+                });
             }
             catch (e) {
                 throw new error_1.CloudBaseError(`[${name}] 取消 SPA 回退失败（spaFallback: false）：${(e === null || e === void 0 ? void 0 : e.message) || String(e)}`);

package/lib/projectValidator/index.js

@@ -42,7 +42,7 @@ class ProjectValidator {
             const resourceIssues = this.validateResources(cwd, loaded.config);
             errors.push(...resourceIssues.errors);
             warnings.push(...resourceIssues.warnings);
-            this.validateConsistency(loaded.config, errors);
+            this.validateConsistency(loaded.config, errors, warnings);
         }
         const summary = this.getSummary(loaded.config);
         return {
@@ -277,11 +277,115 @@ class ProjectValidator {
         }
         return { errors, warnings };
     }
-    validateConsistency(config, errors) {
+    validateConsistency(config, errors, warnings = []) {
         this.validateUniqueNames('functions', config.functions || [], errors);
         this.validateUniqueNames('hosting', config.hosting || [], errors);
         this.validateUniqueField('hosting', config.hosting || [], { field: 'deployPath', errors });
         this.validateGatewayTargets(config, errors);
+        this.validateGatewayPathRewriteConflicts(config, warnings);
+        this.validateHostingSubPathBaseRisks(config, warnings);
+        this.validateSpaFallbackPrefixIsolation(config, warnings);
+    }
+    /**
+     * 检测 hosting 路由中 enablePathTransmission=true 与自动生成 pathRewrite 的冲突
+     *
+     * hosting 目标未显式配置 pathRewrite 时，部署会自动生成 PathRewrite.Prefix = hosting.deployPath。
+     * 若同时显式开启 enablePathTransmission=true，路径透传会覆盖路径重写，导致请求打到错误的托管路径（404）。
+     */
+    validateGatewayPathRewriteConflicts(config, warnings) {
+        var _a;
+        const hostingMap = new Map((config.hosting || []).map((h) => [h.name, h]));
+        (((_a = config.gateway) === null || _a === void 0 ? void 0 : _a.routes) || []).forEach((route, index) => {
+            var _a, _b, _c;
+            if (!((_a = route.target) === null || _a === void 0 ? void 0 : _a.startsWith('hosting:')))
+                return;
+            // 用户显式配置了 pathRewrite → 无自动重写，无冲突
+            if (((_b = route.pathRewrite) === null || _b === void 0 ? void 0 : _b.prefix) || ((_c = route.pathRewrite) === null || _c === void 0 ? void 0 : _c.staticStorePrefix))
+                return;
+            // 未显式开启透传 → 无冲突
+            if (route.enablePathTransmission !== true)
+                return;
+            const hostingName = route.target.slice('hosting:'.length);
+            const hosting = hostingMap.get(hostingName);
+            // hosting 无 deployPath → 不会自动生成 PathRewrite，不冲突
+            if (!(hosting === null || hosting === void 0 ? void 0 : hosting.deployPath))
+                return;
+            warnings.push({
+                level: 'warning',
+                resource: `gateway.routes[${index}]`,
+                field: 'enablePathTransmission',
+                message: `hosting 路由 ${route.target} 未显式配置 pathRewrite，部署将自动生成 ` +
+                    `PathRewrite.Prefix=${hosting.deployPath}，但 enablePathTransmission=true 会覆盖路径重写，` +
+                    `导致请求打不到托管实际部署路径`,
+                fix: '删除 enablePathTransmission，让自动生成的 pathRewrite 生效；' +
+                    '或显式配置 pathRewrite.prefix 指向托管部署路径',
+            });
+        });
+    }
+    /**
+     * 子路径部署（deployPath !== '/'）下，前端构建产物若仍使用根路径 base（如 Vite 默认 '/'），
+     * 会导致资源请求落到 /assets/* 而非 /{deployPath}/assets/*，出现 404/白屏。
+     *
+     * 这里在“可能存在构建步骤”的 hosting 配置上给出防坑告警。
+     */
+    validateHostingSubPathBaseRisks(config, warnings) {
+        ;
+        (config.hosting || []).forEach((hosting, index) => {
+            const deployPath = typeof hosting.deployPath === 'string' ? hosting.deployPath.trim() : '';
+            if (!deployPath || deployPath === '/')
+                return;
+            const framework = typeof hosting.framework === 'string' ? hosting.framework.trim().toLowerCase() : '';
+            const hasBuildStep = (typeof hosting.buildCommand === 'string' && hosting.buildCommand.trim().length > 0) ||
+                (!!framework && framework !== 'static' && framework !== 'custom');
+            if (!hasBuildStep)
+                return;
+            warnings.push({
+                level: 'warning',
+                resource: `hosting[${index}]`,
+                field: 'deployPath',
+                message: `静态托管部署在子路径 ${deployPath}，请确认前端构建 base 与子路径匹配，` +
+                    `否则资源可能请求到根路径（如 /assets/*）导致 404/白屏`,
+                fix: "建议将前端 base 配置为 './' 或与 deployPath 对齐（例如 '/serviceName/'）",
+            });
+        });
+    }
+    /**
+     * spaFallback 为站点级回退能力，不是按网关前缀独立生效。
+     * 同一 hosting 在 spaFallback=true 下被多个网关前缀复用时，容易出现不同前缀回退串扰。
+     */
+    validateSpaFallbackPrefixIsolation(config, warnings) {
+        var _a;
+        const routePathsByHosting = new Map();
+        (((_a = config.gateway) === null || _a === void 0 ? void 0 : _a.routes) || []).forEach((route) => {
+            var _a;
+            if (!((_a = route.target) === null || _a === void 0 ? void 0 : _a.startsWith('hosting:')))
+                return;
+            const hostingName = route.target.slice('hosting:'.length);
+            const pathValue = typeof route.path === 'string' ? route.path.trim() : '';
+            if (!pathValue)
+                return;
+            if (!routePathsByHosting.has(hostingName)) {
+                routePathsByHosting.set(hostingName, new Set());
+            }
+            routePathsByHosting.get(hostingName).add(pathValue);
+        });
+        (config.hosting || []).forEach((hosting, index) => {
+            if (hosting.spaFallback !== true)
+                return;
+            if (!hosting.name)
+                return;
+            const routePaths = [...(routePathsByHosting.get(hosting.name) || new Set())];
+            if (routePaths.length <= 1)
+                return;
+            warnings.push({
+                level: 'warning',
+                resource: `hosting[${index}]`,
+                field: 'spaFallback',
+                message: `hosting:${hosting.name} 在 spaFallback=true 下被多个网关前缀复用（${routePaths.join(', ')}），` +
+                    '可能出现前缀间 404 回退串扰',
+                fix: '建议将不同前缀拆分为独立 hosting 服务，或为每个前缀显式配置独立回退策略',
+            });
+        });
     }
     validateUniqueNames(resource, items, errors) {
         const names = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudbase/manager-node",
-    "version": "5.7.0-beta.0",
+    "version": "5.7.0-beta.2",
     "description": "The node manage service api for cloudbase.",
     "main": "lib/index.js",
     "scripts": {

package/types/cloudrun/index.d.ts

@@ -1,6 +1,6 @@
 import { Environment } from '../environment';
 import { IResponseInfo } from '../interfaces';
-import { CloudrunServerType, ICloudrunDetailResponse, ICloudrunListResponse, ICloudrunServerBaseConfig, ICreateVpcInfo, IBuildLogResponse, IProcessLogResponse, IDiffConfigItem, ITemplate, ReleaseTypeEnum, IServerManageTaskInfo, IDescribeCloudRunDeployRecordResponse, IDescribeVersionDetailParams, IDescribeVersionDetailResponse, ISubmitServerRollbackParams, ISubmitServerRollbackResponse, IDeleteCloudRunVersionsParams, IDeleteCloudRunVersionsResponse } from './type';
+import { CloudrunServerType, ICloudrunDetailResponse, ICloudrunListResponse, ICloudrunServerBaseConfig, ICreateVpcInfo, IBuildLogResponse, IProcessLogResponse, IDiffConfigItem, ITemplate, ReleaseTypeEnum, IServerManageTaskInfo, IDescribeReleaseOrderParams, IDescribeReleaseOrderResponse, IDescribeCloudRunDeployRecordResponse, IDescribeVersionDetailParams, IDescribeVersionDetailResponse, ISubmitServerRollbackParams, ISubmitServerRollbackResponse, IDeleteCloudRunVersionsParams, IDeleteCloudRunVersionsResponse } from './type';
 /**
  * 云托管服务管理类
  * 提供云托管服务的初始化、下载、列表查询和删除等功能
@@ -58,6 +58,12 @@ export declare class CloudRunService {
         Task?: IServerManageTaskInfo;
         RequestId?: string;
     }>;
+    /**
+     * 查询发布单信息（DescribeReleaseOrder）
+     * @param {IDescribeReleaseOrderParams} params 查询参数
+     * @returns {Promise<IDescribeReleaseOrderResponse>} 发布单详情
+     */
+    describeReleaseOrder(params: IDescribeReleaseOrderParams): Promise<IDescribeReleaseOrderResponse>;
     /**
      * 获取云托管服务列表
      * @param {Object} [params] 查询参数

package/types/cloudrun/type.d.ts

@@ -426,6 +426,28 @@ export interface IReleaseOrderInfo {
     CreateTime?: string;
     IsReleasing?: boolean;
 }
+/**
+ * DescribeReleaseOrder 请求参数
+ */
+export interface IDescribeReleaseOrderParams {
+    /** 服务名 */
+    ServerName: string;
+    /** 发布单状态（可选） */
+    Status?: string;
+}
+/**
+ * DescribeReleaseOrder 响应
+ */
+export interface IDescribeReleaseOrderResponse {
+    /** 是否存在发布单 */
+    IsExist?: boolean;
+    /** 发布单详情 */
+    ReleaseOrderInfo?: IReleaseOrderInfo;
+    /** 上一次成功发布时间 */
+    LastReleasedSuccessTime?: string;
+    /** 请求 ID */
+    RequestId: string;
+}
 /**
  * DescribeVersionDetail 请求参数
  */

package/types/deploy/GatewayDeployer.d.ts

@@ -104,8 +104,27 @@ export declare class GatewayDeployer {
     }>>;
     /**
      * 查询指定域名下已存在的路由（幂等收敛用），返回 Map<path, 云端路由详情>
+     *
+     * 匹配策略（优先级从高到低）：
+     * 1. 用 Filters 精确查询目标域名：DescribeHTTPServiceRoute 不带 Filters 时返回的 Domains
+     *    列表可能不完整（如 lowcode 环境 TotalCount=67 但 Domains 只返回部分，HTTPSERVICE 的
+     *    .app.tcloudbase.com 域名缺失），导致云端已有路由查不到被误判为 create
+     * 2. 降级：不带 Filters 全量查询，按域名归一化匹配（去协议/尾斜杠/转小写）
+     *    若目标域名找不到则返回空（保留 domain 维度，避免把其他域名同 path 误判为已存在）
      */
     private getExistingRoutes;
+    /**
+     * 域名归一化：去协议、去尾斜杠、转小写（用于幂等收敛的域名匹配）
+     */
+    private normalizeDomain;
+    /**
+     * 判断错误是否属于「路由已存在/已占用」类（幂等降级专用）
+     *
+     * 只匹配明确的重复/占用语义（code 含 AlreadyExists/Duplicate/ResourceInUse/Conflict，
+     * 或 message 含 already exists），并显式排除否定语义（not exists/not found 等），
+     * 避免把「环境/资源不存在」等真实失败误判为「已存在」而被静默跳过
+     */
+    private isAlreadyExistsError;
     /**
      * 判断期望路由与云端已存在路由是否一致
      *

package/types/projectValidator/index.d.ts

@@ -13,6 +13,25 @@ export declare class ProjectValidator {
     private isPersonalCloudFunction;
     private validateResources;
     private validateConsistency;
+    /**
+     * 检测 hosting 路由中 enablePathTransmission=true 与自动生成 pathRewrite 的冲突
+     *
+     * hosting 目标未显式配置 pathRewrite 时，部署会自动生成 PathRewrite.Prefix = hosting.deployPath。
+     * 若同时显式开启 enablePathTransmission=true，路径透传会覆盖路径重写，导致请求打到错误的托管路径（404）。
+     */
+    private validateGatewayPathRewriteConflicts;
+    /**
+     * 子路径部署（deployPath !== '/'）下，前端构建产物若仍使用根路径 base（如 Vite 默认 '/'），
+     * 会导致资源请求落到 /assets/* 而非 /{deployPath}/assets/*，出现 404/白屏。
+     *
+     * 这里在“可能存在构建步骤”的 hosting 配置上给出防坑告警。
+     */
+    private validateHostingSubPathBaseRisks;
+    /**
+     * spaFallback 为站点级回退能力，不是按网关前缀独立生效。
+     * 同一 hosting 在 spaFallback=true 下被多个网关前缀复用时，容易出现不同前缀回退串扰。
+     */
+    private validateSpaFallbackPrefixIsolation;
     private validateUniqueNames;
     private validateUniqueField;
     private validateGatewayTargets;