@cloudbase/manager-node 5.9.3 → 5.10.0

package/lib/deploy/StaticDeployer.js

@@ -4,36 +4,341 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StaticDeployer = void 0;
+exports.hasFilesInDir = hasFilesInDir;
+exports.normalizeIgnore = normalizeIgnore;
+exports.tryNormalizeDeployPath = tryNormalizeDeployPath;
+exports.resolveInsideBase = resolveInsideBase;
+exports.assertRealPathInsideBase = assertRealPathInsideBase;
+exports.resolveDeployRoot = resolveDeployRoot;
+exports.resolveArtifactDir = resolveArtifactDir;
 const path_1 = __importDefault(require("path"));
-const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
 const error_1 = require("../error");
+const error_types_1 = require("../error-types");
+// 默认排除清单的唯一来源：文件级上传（storage.uploadFilesCustom）也读它，
+// 在这里复制一份就会出现「目录上传排 .env、单文件上传不排」的口径分叉
+const ignore_1 = require("../utils/ignore");
 const framework_1 = require("./framework");
-/** 环境变量值统一转字符串（execSync env 要求 string） */
-function stringifyEnvValues(envVariables) {
-    const result = {};
-    if (envVariables) {
-        for (const [key, value] of Object.entries(envVariables)) {
-            result[key] = String(value);
+/**
+ * 写部署记录时固定下发的 `Framework`：必须逐字符等于 `static`。
+ *
+ * CreateCloudApp 只有一个 `StaticConfig.Framework` 字段，「是否跳过构建」的判断
+ * 和控制台展示共用它，没法一个字段塞两个值：
+ *
+ * - BuildServer 的跳过构建分支条件写死为 `SkipBuild && framework=="static"`
+ *   （cloud-tcb/cloudbasebuildserver/service/build_service.go:150）。传 `other` /
+ *   `vite` / `react` 都会**真的触发 CNB 流水线** —— 产物已在本地直传，再跑一遍
+ *   既排队又重复上传，`skipBuild: true` 形同虚设。
+ * - 旧实现按 iWiki 4052401611 的枚举白名单把 `static` 收敛成 `other`，
+ *   正是上面这条失效的直接原因（枚举白名单只描述控制台展示口径，不参与该判断）。
+ *
+ * 结论：纯静态直传一律传 `static`。真实框架只用于本地推断产物目录
+ * （`resolveArtifactDir`），不再写进这个字段。
+ */
+const SKIP_BUILD_FRAMEWORK = 'static';
+/**
+ * 判断目录下是否存在至少一个**真实文件**（递归）。
+ *
+ * 忽略 `.DS_Store`：只有该文件的目录在 macOS 上很常见，
+ * 若按「非空」通过，会静默发布一个空站点。
+ *
+ * 必须递归：只看顶层条目名时，「仅有空子目录」（如 `dist/assets/` 为空目录）
+ * 会被误判为有产物，于是把空站点当有效产物发布出去。
+ * 不跟随软链（`dirent.isDirectory()` 对符号链接为 false），避免环状链接无限递归。
+ */
+function hasFilesInDir(dir) {
+    try {
+        if (!fs_1.default.statSync(dir).isDirectory())
+            return false;
+        const stack = [dir];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
+                if (entry.name === '.DS_Store')
+                    continue;
+                if (entry.isFile())
+                    return true;
+                if (entry.isDirectory())
+                    stack.push(path_1.default.join(current, entry.name));
+            }
         }
+        return false;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * 把用户配置的 `ignore` 归一成字符串数组（app / hosting / uploadCode 三处共用）。
+ *
+ * 必须与 `uploadFiles` 一样接受 `string | string[]`：cloudbaserc 的 app / hosting
+ * 配置是原文透传给部署链路的（中间没有 schema 校验），用户按 `uploadFiles` 的写法
+ * 写 `"ignore": "*.map"` 是合法的。而拼接只认数组 —— 直接 `...'*.map'` 会按字符
+ * 展开成 `['*', '.', 'm', 'a', 'p']`：用户规则失效，且这些单字符 glob 会误伤大量
+ * 产物文件（文件名含 a / m / p 就被排除），站点缺文件、线上 404，全程无报错。
+ *
+ * 与 `src/deploy/function/config-guard.ts` 的 `Array.isArray` 归一化同一口径。
+ *
+ * - `undefined` / `null` → `[]`（未配置，只用默认清单）
+ * - 字符串 → 单元素数组
+ * - 数组 → 原样（逐项校验）
+ * - 空串项丢弃：不是合法 glob，留着只会让匹配行为不可预期
+ * - 非字符串项 → `INVALID_PARAM`，报错里带字段名
+ */
+function normalizeIgnore(ignore, field, name) {
+    if (ignore === undefined || ignore === null)
+        return [];
+    const list = Array.isArray(ignore) ? ignore : [ignore];
+    const prefix = name ? `[${name}] ` : '';
+    return list
+        .filter(item => item !== undefined && item !== null && item !== '')
+        .map(item => {
+        if (typeof item === 'string')
+            return item;
+        return (0, error_1.throwInvalidParam)(`${prefix}${field} 必须是字符串或字符串数组，当前含 ${Array.isArray(item) ? 'array' : typeof item}: ${String(item)}`);
+    });
+}
+/**
+ * 会被云端构建容器按 shell 解析的字符。
+ *
+ * 与 CLI 侧同名校验保持同一套口径：空白、引号、分号、
+ * `$`、反引号、重定向/管道、通配符、`#`、`~`、反斜杠。
+ */
+const SHELL_UNSAFE_PATTERN = /[\s'"`$;&|<>(){}[\]*?!#~\\]/;
+/**
+ * 校验并规范化部署路径（`app.deployPath` / `hosting[].deployPath`），
+ * 同时作为 `AppPath` / 静态托管 `cloudPath` 下发。
+ *
+ * 当前不再拼任何命令（`staticCmd` 已不下发），但校验刻意保留：
+ * - 部署路径是访问 URL、`AppPath` 与网关 `PathRewrite.Prefix` 的唯一真相源，
+ *   不能含 `..`、不能以 `-` 开头（服务端会原样存进版本记录并回显给排查者）
+ * - shell 元字符一并拒绝是纵深防御：一旦平台侧恢复「按命令部署」的链路，
+ *   这个值会被拼进 `tcb hosting deploy`，那时的防线只能在这里
+ *
+ * ⚠️ 缺前导 `/`（如 `"deployPath": "web"`）**自动补全**为 `/web`，不报错：
+ * 1. 契约要求绝对路径（cloudbaserc schema 的 `PathPattern` 就是 `^/.*`），但 schema
+ *    只在 `tcb validate` / MCP 注入侧生效，手改配置直连本方法时会被绕过
+ * 2. 补全对已部署内容是**幂等**的：`toPhysicalKey` 会 `replace(/^\/+/, '')`，
+ *    `web` 与 `/web` 落到同一个 COS key，不会产生两份文件
+ * 3. 存量配置（相对写法）因此不炸，而网关 Prefix 与访问 URL 都变正确 ——
+ *    以前相对写法在网关场景会静默 404
+ *
+ * 补全**不止**加前导 `/`，还会先做分段规范化（丢掉空段与 `.` 段）：
+ * 只补斜杠会把 `./web` 拼成 `/./web`，COS key 落成 `./web/...`，而浏览器访问
+ * `/./web` 会被规范化成 `/web` —— 两者不相等，整站 404 且部署「成功」无报错。
+ * `.` / `web/.` / `web//x` 一律归到 `/` / `/web` / `/web/x` 后才补前导 `/`。
+ *
+ * `../`、shell 元字符、`-` 开头仍一律拒绝（这些补斜杠救不了，且属注入面），
+ * 与 `.` 段「安全归一即可放行」的处理保持同一粒度判断：能归一的归一，不能的报错。
+ *
+ * @returns 规范化（trim + 折叠 `.`/空段 + 必要时补前导 `/`）后的值，调用方必须用返回值而非原值
+ */
+function normalizeDeployPath(value, field, mustBeAbsolute = false) {
+    const normalized = String(value !== null && value !== void 0 ? value : '').trim();
+    if (!normalized) {
+        (0, error_1.throwInvalidParam)(`${field} 不能为空`);
+    }
+    if (SHELL_UNSAFE_PATTERN.test(normalized)) {
+        (0, error_1.throwInvalidParam)(`${field} 含空白或 shell 特殊字符（会被当成命令参数解析）: ${value}`);
+    }
+    // ⚠️ `-` 前缀检查必须在补 `/` 之前：补完后再判，`-web` 已变成 `/-web` 而躲过检查
+    if (normalized.startsWith('-')) {
+        (0, error_1.throwInvalidParam)(`${field} 不能以 - 开头（会被当成命令选项）: ${value}`);
+    }
+    if (normalized.split('/').includes('..')) {
+        (0, error_1.throwInvalidParam)(`${field} 不能包含 ../: ${value}`);
+    }
+    // 折叠空段与 `.` 段（保留是否绝对路径的信息，前导 `/` 单独判断）：
+    // `./web` / `web/.` / `web//x` → `web` / `web` / `web/x`；`.` / `./` → 空段
+    const isAbsolute = normalized.startsWith('/');
+    const collapsed = normalized
+        .split('/')
+        .filter(seg => seg !== '' && seg !== '.')
+        .join('/');
+    if (mustBeAbsolute) {
+        // `.` 之类全被折叠掉时即根路径，不能返回空串或 `/.`
+        return `/${collapsed}`;
+    }
+    if (isAbsolute) {
+        (0, error_1.throwInvalidParam)(`${field} 必须是相对路径: ${value}`);
+    }
+    if (!collapsed) {
+        (0, error_1.throwInvalidParam)(`${field} 不能为空`);
+    }
+    return collapsed;
+}
+/**
+ * `normalizeDeployPath` 的只读版本：非法值返回 `undefined` 而不抛错。
+ *
+ * 导出给 `DeployOrchestrator.buildAppPlan` 复用：plan 必须与 apply 走**同一个**
+ * 校验函数，否则「用户显式配了非法 deployPath」这种场景会在 plan 里渲染成一条
+ * 完全正常的计划项，而 apply 必然抛 `INVALID_PARAM` —— 预演与真实发布口径分叉。
+ *
+ * plan 是只读预演，报错留给 apply 的参数校验，这里只降级为「无规范化值」。
+ */
+function tryNormalizeDeployPath(value, field, mustBeAbsolute = false) {
+    try {
+        return normalizeDeployPath(value, field, mustBeAbsolute);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * 解析路径并要求落在 `baseDir` 内，返回解析后的绝对路径。
+ *
+ * 防的是 `outputDir: '../..'` 或绝对路径把项目外文件递归上传并发布成站点。
+ * 这里只做字面路径判断；软链逃逸（`ln -s ~/.ssh dist`）需要调用方按需补充
+ * （CLI 侧 `safeResolveProjectPath` 有完整实现）。
+ *
+ * ⚠️ `path.isAbsolute(relative)` 不能省：`path.relative` 在找不到相对路径时
+ * 会返回 target 的绝对路径（Windows 跨盘符即如此），只判 `startsWith('..')` 会放行。
+ *
+ * 类型校验下沉到这里，而不是放在每个调用点：
+ * `app.root` / `app.outputDir` / `hosting.root` / `hosting.outputDir` 四个入口都来自
+ * 用户手改的 cloudbaserc 原文（无 schema 兜底），`"root": 123` 这类 JSON 合法值会在
+ * `path.resolve` 处抛 Node 原生 `ERR_INVALID_ARG_TYPE`，错误里不含任何字段名，用户无从定位。
+ * 逐个调用点补校验必然漏（本函数的四个调用点此前就只有一个做了），所以在唯一的收口处拦。
+ * 含 NUL 的字符串同理：能过 `path.resolve`，却在 `fs` 调用处抛 `ERR_INVALID_ARG_VALUE`。
+ *
+ * 导出给 `DeployOrchestrator.resolveBuildHint` 复用：plan 必须与 apply 用**同一个**
+ * 校验函数，否则 plan 会在越界路径上报 `artifactReady: true`，而 apply 必然拒绝。
+ */
+function resolveInsideBase(baseDir, target, field) {
+    if (typeof target !== 'string') {
+        (0, error_1.throwInvalidParam)(`${field} 必须是字符串，当前类型：${Array.isArray(target) ? 'array' : target === null ? 'null' : typeof target}`);
+    }
+    if (target.includes('\0')) {
+        (0, error_1.throwInvalidParam)(`${field} 含非法字符（NUL 字节）`);
+    }
+    const base = path_1.default.resolve(baseDir);
+    const resolved = path_1.default.resolve(base, target);
+    const relative = path_1.default.relative(base, resolved);
+    if (relative === '' || (!relative.startsWith('..') && !path_1.default.isAbsolute(relative))) {
+        return resolved;
+    }
+    (0, error_1.throwInvalidParam)(`${field} 解析后超出项目目录: ${target}`);
+}
+/**
+ * 在字面路径校验之上，再按 realpath 校验一次，挡住软链逃逸。
+ *
+ * 场景：`ln -s ~/.ssh dist` —— `resolveInsideBase` 只看字面路径，会认为 `dist`
+ * 就在项目内；实际读取时落在项目外，产物（或私钥）会被发布到公开可访问的托管桶。
+ *
+ * 目标不存在时 `realpathSync` 抛错，此时不做判断：交给调用方后续的存在性/非空校验
+ * 给出更准确的错误（例如 `BUILD_OUTPUT_NOT_FOUND`）。
+ *
+ * 只做「是否越界」的判定，返回值仍用字面解析结果 —— 避免把 `/var` → `/private/var`
+ * 这类系统级软链展开后泄漏到对外可见的路径与日志里。
+ *
+ * 与 `resolveInsideBase` 一同导出给 `DeployOrchestrator.resolveBuildHint` 复用。
+ */
+function assertRealPathInsideBase(options) {
+    const { baseDir, resolved, field, rawTarget } = options;
+    let realBase;
+    let realTarget;
+    try {
+        realBase = fs_1.default.realpathSync(path_1.default.resolve(baseDir));
+        realTarget = fs_1.default.realpathSync(resolved);
+    }
+    catch (_a) {
+        return;
+    }
+    const relative = path_1.default.relative(realBase, realTarget);
+    if (relative === '' || (!relative.startsWith('..') && !path_1.default.isAbsolute(relative))) {
+        return;
     }
-    return result;
+    (0, error_1.throwInvalidParam)(`${field} 实际路径（软链解析后）超出项目目录: ${rawTarget}`);
 }
 /**
- * app/hosting 声明式部署器
+ * 解析 `app.root` / `hosting.root`：落在 `cwd` 内，且软链解析后仍在 `cwd` 内。
  *
- * app：framework=static → 直传产物 + SkipBuild 写记录（对齐 tcb app deploy 纯静态分支）；
- *      其余 framework → 云端构建（上传源码 → 云端构建 → 写版本记录），与现有 tcb app deploy 一致
- * hosting：固定静态流程（buildCommand 非空则本地构建后直传），不写版本记录（现有 tcb hosting deploy 行为）
+ * 必须用 `||` 而非 `??`：`root: 0 / false / ''` 一律回落 `'.'`。
+ * 导出给 `DeployOrchestrator` 复用，plan 与 apply 用同一个函数，不会再出现口径分叉。
+ */
+function resolveDeployRoot(cwd, rawRoot, field) {
+    const rootField = (rawRoot || '.');
+    const root = resolveInsideBase(cwd, rootField, field);
+    assertRealPathInsideBase({ baseDir: cwd, resolved: root, field, rawTarget: rootField });
+    return root;
+}
+/**
+ * 解析产物目录（绝对路径），**app 与 hosting 同一套规则**：
+ *
+ * | `outputDir` | 结果 |
+ * |---|---|
+ * | 配了（trim 后非空字符串，含 `'.'`） | 按用户配置（用 trim 后的值），不参与推断 |
+ * | 没配（`undefined` / `null` / `''` / 纯空白串） | `resolveHostingOutputDir` 推断：显式 buildCommand → `dist`；framework / package.json → 框架默认产物目录；纯静态 → root |
+ * | 非字符串 | `INVALID_PARAM`（否则会在 `path.resolve` 处以裸 TypeError 失败） |
+ *
+ * 推断规则与 `tcb app build` 的产物落点一致：构建到哪里，就从哪里上传。
+ * 只解析和做越界 / 软链校验，**不判非空** —— apply 据此抛 `BUILD_OUTPUT_NOT_FOUND`，
+ * plan（`DeployOrchestrator`）据此报 `artifactReady`，两边共用本函数。
+ */
+function resolveArtifactDir(options) {
+    const { config, root, kind, name } = options;
+    const field = `${kind}.outputDir`;
+    const raw = config.outputDir;
+    if (raw !== undefined && raw !== null && typeof raw !== 'string') {
+        (0, error_1.throwInvalidParam)(`${name ? `[${name}] ` : ''}${field} 必须是字符串，当前类型：${Array.isArray(raw) ? 'array' : typeof raw}`);
+    }
+    // 先 trim：纯空白串（模板清空内容后残留空格最常见）是 truthy，不归一会被当成真实配置，
+    // 走到 path.resolve(root, '   ') 变成 '<root>/   ' 这种畸形目录名 —— 字面仍在 root 内，
+    // 越界与软链校验全部放行，最终在 assertArtifactReady 抛 BUILD_OUTPUT_NOT_FOUND，
+    // 用户看到的路径根本不知道是自己多打了空格。与 normalizeDeployPath 的 trim 口径一致。
+    // 配了就校验 trim 后的值（报错文案里也是用户写的值）；没配才推断，再折回相对 root 的值做越界校验
+    const trimmed = typeof raw === 'string' ? raw.trim() : raw;
+    const target = typeof trimmed === 'string' && trimmed !== ''
+        ? trimmed
+        : path_1.default.relative(root, (0, framework_1.resolveHostingOutputDir)({ framework: config.framework, buildCommand: config.buildCommand }, root));
+    const outputDir = resolveInsideBase(root, target, field);
+    assertRealPathInsideBase({ baseDir: root, resolved: outputDir, field, rawTarget: target });
+    return outputDir;
+}
+/**
+ * 产物必须已就绪（存在且含至少一个真实文件）。
+ *
+ * - 目录不存在：没构建，要明确告知先构建，而不是让 uploadFiles 抛一个指向内部路径的错
+ * - 目录为空：会被静默发布成空站点（线上 404，但部署「成功」）
+ */
+function assertArtifactReady(dir, name) {
+    if (hasFilesInDir(dir))
+        return;
+    throw new error_1.CloudBaseError(`[${name}] 未找到有效构建产物：${dir}（目录不存在或为空）。` +
+        `声明式部署只部署不构建，请先完成构建（本地执行构建命令或 tcb app build）后重试`, { type: error_types_1.ERROR_TYPES.buildOutputNotFound });
+}
+/**
+ * app/hosting 声明式部署器 —— **只部署，不构建**
+ *
+ * 声明式部署（CLI `tcb deploy` / MCP `deployApply`）的定位是「只部署」。构建由用户
+ * 自己完成，或走 `tcb app build`（本地）/ `tcb app deploy`（云端，不经过本类）。
+ * 本类不再执行任何构建命令，产物缺失即抛 `BUILD_OUTPUT_NOT_FOUND`。
+ *
+ * - app：产物直传 + `createApp(SkipBuild)` 写部署记录
+ * - hosting：产物直传，不写版本记录（保持 `tcb hosting deploy` 的既有行为）
+ *
+ * 两者的产物目录解析、就绪校验、上传排除清单完全一致（`resolveArtifactDir` /
+ * `assertArtifactReady` / `uploadArtifact`）。`buildCommand` / `framework` 仍被读取，
+ * 但只用于**推断产物目录**，不再执行；写部署记录时 `framework` 固定下发 `'static'`
+ * （跳过构建的唯一认可值，见 `SKIP_BUILD_FRAMEWORK`）。
  */
 class StaticDeployer {
     constructor(environment) {
         this.environment = environment;
     }
     /**
-     * app 部署（与现有 tcb app deploy 一致）
+     * app 部署：**只部署，不构建**。
      *
-     * framework=static：直传产物（hosting uploadFiles）+ createApp(SkipBuild) 后台写部署记录，跳过云端构建。
-     * 其余 framework：上传源码 ZIP → createApp 云端构建 → 写版本记录。
+     * 无条件走「产物直传 + `createApp({ skipBuild: true })`」写部署记录，
+     * 不再根据 `framework` 分叉到云端构建。理由：声明式部署（`tcb deploy`）
+     * 的定位是只部署，构建由用户用 `tcb app build`（本地）或
+     * CLI 的 `tcb app deploy`（云端，不经过本方法）完成。
+     *
+     * 产物目录与 hosting 同一套规则（见 `resolveArtifactDir`）：配了按配置，没配按
+     * buildCommand / framework / package.json 推断，纯静态回退 `app.root`。
+     *
+     * @throws CloudBaseError `INVALID_PARAM` 缺 serviceName / 路径越界 / outputDir 类型非法
+     * @throws CloudBaseError `BUILD_OUTPUT_NOT_FOUND` 产物目录不存在或为空
      */
     async deployApp(options) {
         const { config, cwd = process.cwd() } = options;
@@ -41,134 +346,165 @@ class StaticDeployer {
         if (!serviceName) {
             (0, error_1.throwInvalidParam)('app 部署需要配置 serviceName');
         }
-        const projectPath = path_1.default.resolve(cwd, config.root || '.');
-        const resolvedDeployPath = config.deployPath || `/${serviceName}`;
-        // 纯静态：直传产物 + SkipBuild 写记录（对齐 tcb app deploy 的 deployStaticApp 分支）
-        if (config.framework === 'static') {
-            return this.deployAppStatic({ config, serviceName, projectPath, resolvedDeployPath });
-        }
-        return this.deployAppCloud(config, serviceName, projectPath);
+        // app.root 也不允许越界：否则下面的 outputDir 校验会以项目外目录为基准而失去意义
+        const projectPath = resolveDeployRoot(cwd, config.root, 'app.root');
+        // 部署路径同时是直传的 cloudPath 与版本记录里的 appPath：必须逐字符一致，
+        // 否则产物挂到别的路径、页面 404。在入口处一次性规范化，两处共用同一个值
+        const resolvedDeployPath = normalizeDeployPath(config.deployPath || `/${serviceName}`, 'app.deployPath', true);
+        const uploadDir = resolveArtifactDir({ config, root: projectPath, kind: 'app', name: serviceName });
+        assertArtifactReady(uploadDir, serviceName);
+        // 入口归一次：直传托管桶与打包版本快照共用这个结果，两条路径不再各自归一
+        const userIgnore = normalizeIgnore(config.ignore, 'app.ignore', serviceName);
+        return this.deployAppStatic({
+            serviceName,
+            uploadDir,
+            resolvedDeployPath,
+            userIgnore
+        });
     }
     /**
-     * hosting 部署（固定静态流程，不写版本记录）
+     * hosting 部署：**只部署，不构建**（不写版本记录）
+     *
+     * 与 `deployApp` 同一口径：声明式部署（`tcb deploy` / MCP `deployApply`）的定位是
+     * 「只部署」，构建由用户自己完成或走 `tcb app build`（本地）。
+     *
+     * 为什么构建必须从这里移除、而不是只在 CLI 侧中立化：
+     * CLI 的 `neutralizeHostingForDeploy` 会清空 `buildCommand` 后再调用本方法，
+     * 因此从 CLI 进来看不出差别；但 MCP 的 `deployApply` 直接读 cloudbaserc 调用本方法，
+     * 不经过中立化 ⇒ 若构建留在这里，同一份 cloudbaserc 会出现
+     * 「CLI 不构建、MCP 构建」的行为分叉，且 `app` 已经不构建，
+     * 变成「app 不构建、hosting 构建」的半截状态。单一真相源只能放在本层。
+     *
+     * `buildCommand` / `installCommand` 仍被接收但**不再执行**：它们现在只是
+     * 「产物目录推断」的输入（见 `resolveArtifactDir`），配置无需改写即可平滑过渡。
      *
-     * 支持本地构建：buildCommand 非空时自动执行 build 后上传产物（依赖由用户自行安装，
-     * 不代为执行 npm install）；
-     * 纯静态（buildCommand 空/未配置且无法检测框架）时直接上传 outputDir（默认 root，保持现状）。
      * 访问地址 = https://{CdnDomain}{deployPath}（与 tcb hosting deploy 一致）
+     *
+     * @throws CloudBaseError `INVALID_PARAM` 路径越界 / outputDir 类型非法
+     * @throws CloudBaseError `BUILD_OUTPUT_NOT_FOUND` 产物目录不存在或为空
      */
     async deployHosting(options) {
         const { config, cwd = process.cwd() } = options;
         const name = config.name || 'default';
-        const root = path_1.default.resolve(cwd, config.root || '.');
-        const cloudPath = config.deployPath || '/';
-        // 1. 解析构建命令：显式 buildCommand > framework 映射 > package.json 自动探测 > null（纯静态）
-        const buildCommand = (0, framework_1.resolveBuildCommand)(config, root);
-        // 2. 有构建命令 → 本地构建（仅 build，依赖由用户自行安装）；纯静态 → 跳过构建直接上传
-        if (buildCommand) {
-            this.runLocalBuild(root, Object.assign(Object.assign({}, config), { buildCommand }), config.envVariables);
-        }
-        // 3. outputDir：由 framework.resolveHostingOutputDir 统一解析，
-        //    确保与 DeployOrchestrator(buildHostingPlans/persistState) 保持一致。
-        const outputDir = (0, framework_1.resolveHostingOutputDir)(config, root);
-        const hostingOptions = {
-            localPath: outputDir,
+        const root = resolveDeployRoot(cwd, config.root, 'hosting.root');
+        // 与 app 同口径：缺前导 `/` 自动补全（`web` → `/web`），非法字符仍拒绝。
+        // 不校验的后果：`cloudPath` 会原样进网关 `PathRewrite.Prefix`，相对写法导致
+        // 请求重写错位、经网关访问 404，而部署本身「成功」，问题被推到线上才暴露
+        const cloudPath = normalizeDeployPath(config.deployPath || '/', 'hosting.deployPath', true);
+        const uploadDir = resolveArtifactDir({ config, root, kind: 'hosting', name });
+        assertArtifactReady(uploadDir, name);
+        // 与 deployApp 同口径：入口归一次，下游（uploadArtifact）只复用结果
+        const userIgnore = normalizeIgnore(config.ignore, 'hosting.ignore', name);
+        await this.uploadArtifact({
+            localPath: uploadDir,
             cloudPath,
-            ignore: config.ignore || ['.DS_Store'],
+            // ignore 由 uploadArtifact 从 userIgnore 统一构造，这里不再重复传原始值
             // 声明式配置名为 entryFile，透传到 uploadFiles 时对应 entryFiles
             entryFiles: config.entryFile,
             // 一致性发布开关：任一开启即走一致性上传（uploadDirectoryConsistent）
             verify: config.verify,
             safe: config.safe,
             prune: config.prune
-        };
-        await this.environment.getHostingService().uploadFiles(hostingOptions);
+        }, userIgnore, name);
         const url = await this.resolveHostingUrl(cloudPath);
         return { name, url, wroteRecord: false };
     }
+    /**
+     * 产物直传静态托管（app / hosting 共用）。
+     *
+     * `userIgnore` 必须由调用方在入口用 `normalizeIgnore` 归一后传入：
+     * 归一化只做一次，避免「同一个 config.ignore 在两条路径上各归一一次」——
+     * 只要有一处被改回直接 spread 原始值，字符串 `'*.map'` 就会按字符展开成
+     * `['*','.','m','a','p']`，误杀大量产物且不报错。
+     */
+    async uploadArtifact(options, userIgnore, name) {
+        // mergeArtifactIgnore 内部去重：hosting.uploadFiles 入口还会再合并一次，
+        // 两边都用同一个函数才能保证「重复合并 = 幂等」，不会把清单叠成两份
+        await this.environment.getHostingService().uploadFiles(Object.assign(Object.assign({}, options), { ignore: (0, ignore_1.mergeArtifactIgnore)(userIgnore) }));
+    }
     /**
      * app 纯静态直传（对齐 tcb app deploy 的 deployStaticApp 分支）
      *
      * 1. hosting uploadFiles 直传产物（文件级上传，立即可访问，无需打 ZIP）
-     * 2. 后台异步 createApp(SkipBuild) 写部署记录（失败不影响文件访问）
+     * 2. createApp(SkipBuild) 写部署记录（失败时抛错，但说明产物已可访问）
      * 3. 跳过云端构建轮询，返回访问地址
+     *
+     * 调用前产物目录必须已解析并校验就绪（见 `deployApp`）。
      */
     async deployAppStatic(options) {
-        const { config, serviceName, projectPath, resolvedDeployPath } = options;
+        var _a;
+        const { serviceName, uploadDir, resolvedDeployPath, userIgnore } = options;
         const cloudAppService = this.environment.getCloudAppService();
-        // 1. 直传产物（outputDir 默认项目根；cloudPath 与云端构建分支的 deployCmd 保持一致，
-        //    避免同一服务名切换构建/纯静态时访问路径漂移）
-        //    默认排除 node_modules（对齐 CLI 纯静态 DEFAULT_APP_IGNORE），避免产物目录含依赖时上传失控
-        const uploadDir = path_1.default.resolve(projectPath, config.outputDir || '.');
-        await this.environment.getHostingService().uploadFiles({
+        // 不发 staticCmd（installCmd / buildCmd / deployCmd 都不传）：
+        // skip 分支在建完版本记录后直接 return，压根不读命令；而一旦平台侧让 skip 失效，
+        // 缺 deployCmd 会退化成按 FRAMEWORK_NAME 猜目录（`static` 落到 `*` → `dist`），
+        // 而 ZIP 以产物目录为根、包内没有 dist/ → 构建阶段失败、版本 FAILED。
+        // 这是刻意的：skip 是唯一设计路径，失效必须显性失败，而不是静默多跑一次流水线。
+        // 1. 直传产物（cloudPath 与版本记录里的 appPath 共用 resolvedDeployPath，避免访问路径漂移）
+        await this.uploadArtifact({
             localPath: uploadDir,
-            cloudPath: resolvedDeployPath,
-            ignore: ['.DS_Store', 'node_modules/**', '**/.DS_Store', ...(config.ignore || [])]
-        });
-        // 2. 后台异步写部署记录（fire-and-forget：文件已直传，记录失败不影响访问）
-        const recordTask = (async () => {
-            try {
-                const uploadResult = await cloudAppService.uploadCode({
-                    deployType: 'static-hosting',
-                    serviceName,
-                    localPath: projectPath,
-                    ignore: ['.git/**', ...(config.ignore || [])]
-                });
-                await cloudAppService.createApp({
-                    deployType: 'static-hosting',
-                    serviceName,
-                    buildType: 'ZIP',
-                    skipBuild: true,
-                    staticConfig: {
-                        cosTimestamp: uploadResult.unixTimestamp,
-                        appPath: resolvedDeployPath,
-                        framework: config.framework,
-                        staticCmd: {
-                            installCmd: '',
-                            buildCmd: '',
-                            deployCmd: `tcb hosting deploy ${config.outputDir || '.'} ${resolvedDeployPath}`
-                        }
-                    }
-                });
-            }
-            catch (_a) {
-                // 部署记录写入失败不影响已上传的文件访问
-            }
-        })();
-        recordTask.catch(() => { });
-        // 3. 访问地址：静态托管 CDN 域名 + 部署路径（与 tcb app deploy 纯静态分支一致）
-        const url = await this.resolveHostingUrl(resolvedDeployPath);
-        return { name: serviceName, url, wroteRecord: true };
-    }
-    /**
-     * app 云端构建：上传源码 ZIP → createApp 云端构建 → 写版本记录
-     */
-    async deployAppCloud(config, serviceName, projectPath) {
-        const cloudAppService = this.environment.getCloudAppService();
-        const uploadResult = await cloudAppService.uploadCode({
-            deployType: 'static-hosting',
-            serviceName,
-            localPath: projectPath,
-            // 云端构建：不排除 node_modules（云端 install 需要私有/离线依赖随包上传）
-            excludeNodeModules: false,
-            ignore: ['.git/**', ...(config.ignore || [])]
-        });
-        await cloudAppService.createApp({
-            deployType: 'static-hosting',
-            serviceName,
-            buildType: 'ZIP',
-            staticConfig: {
-                cosTimestamp: uploadResult.unixTimestamp,
-                appPath: config.deployPath || `/${serviceName}`,
-                staticCmd: {
-                    installCmd: config.installCommand || 'npm install',
-                    buildCmd: config.buildCommand || 'npm run build',
-                    deployCmd: `tcb hosting deploy ${config.outputDir || 'dist'} ${config.deployPath || `/${serviceName}`}`
+            cloudPath: resolvedDeployPath
+            // ignore 由 uploadArtifact 从入口归一后的 userIgnore 统一构造，不传原始值
+        }, userIgnore, serviceName);
+        // 2. 写部署记录（await：记录是部署结果的一部分，失败必须让调用方感知）
+        //
+        // 早期实现是 fire-and-forget + 恒返回 wroteRecord: true，导致记录写失败时
+        // 调用方仍以为成功、版本列表里却查不到，排查成本高。改为同步等待：
+        // 失败时抛错，但文案明确说明「产物已上传并可访问」，避免用户误以为要重传。
+        let wroteRecord = false;
+        // 上传阶段是否成功：决定 catch 文案能不能说「产物已上传并可访问」。
+        // 这个 try 同时包住 uploadCode 和 createApp，不区分阶段会让上传失败也报「记录写入失败」。
+        let uploaded = false;
+        try {
+            const uploadResult = await cloudAppService.uploadCode({
+                deployType: 'static-hosting',
+                serviceName,
+                // 这个 ZIP 只为满足 createApp 的 cosTimestamp 要求（skipBuild 下不会被构建），
+                // 但它就是版本快照本身，所以打包「产物目录」而不是项目根：
+                //   1. 语义正确 —— 记录里的快照应等于实际发布的内容，
+                //      打包项目根会让回滚/重建拿到源码而不是产物
+                //   2. 少传 —— 项目根会把源码、构建缓存一起传到 COS，
+                //      大仓库会明显变慢甚至撞上传超时（outputDir='.' 时两者相同）
+                localPath: uploadDir,
+                // 与直传托管桶**同一份清单**：快照是「实际发布内容」的版本记录，
+                // 两边排除范围不一致会让回滚拿到线上没有的文件（node_modules / .DS_Store）。
+                // 这里不传 excludeNodeModules: false，uploadCode 侧的
+                // node_modules 排除与本文具清单叠加，属幂等的二次保障。
+                ignore: (0, ignore_1.mergeArtifactIgnore)(userIgnore)
+            });
+            uploaded = true;
+            await cloudAppService.createApp({
+                deployType: 'static-hosting',
+                serviceName,
+                buildType: 'ZIP',
+                skipBuild: true,
+                staticConfig: {
+                    cosTimestamp: uploadResult.unixTimestamp,
+                    appPath: resolvedDeployPath,
+                    // 必须传 static：BuildServer 只在 framework=="static" 时才跳过构建，
+                    // 传真实框架（vite / react / other）会让 skipBuild 失效、真的跑流水线
+                    framework: SKIP_BUILD_FRAMEWORK
                 }
-            }
-        });
-        const url = await this.resolveAppUrl(serviceName, config.deployPath || `/${serviceName}`);
-        return { name: serviceName, url, wroteRecord: true };
+            });
+            wroteRecord = true;
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            // 按阶段给文案：上传失败时产物根本不可访问，说「已上传并可访问」会把用户引向错误方向
+            // （以为只是记录问题、不用重传）
+            throw new error_1.CloudBaseError(uploaded
+                ? `[${serviceName}] 产物已上传并可访问，但部署记录写入失败：${detail}`
+                : `[${serviceName}] 产物上传失败：${detail}`, { type: error_types_1.ERROR_TYPES.apiError });
+        }
+        // 3. 访问地址：优先云应用自己的 Domain，拿不到再回落静态托管 CDN 域名
+        //
+        // skipBuild 只跳过构建，云应用记录仍由 createApp 创建，DescribeCloudAppInfo 会返回
+        // 该应用独立的 Domain（用户可能已绑定自定义域名）。若把地址固定成托管 CDN 域名，
+        // 等于把应用域名（含自定义域名）丢掉，控制台 / CLI / MCP 展示的就不是用户实际使用的入口。
+        // 托管 CDN 仅在拿不到 Domain 时兜底，避免返回 undefined。
+        // 拼接规则与 CLI 的 buildAppUrl 同口径，见 resolveAppUrl 注释。
+        const url = (_a = (await this.resolveAppUrl(serviceName, resolvedDeployPath))) !== null && _a !== void 0 ? _a : (await this.resolveHostingUrl(resolvedDeployPath));
+        return { name: serviceName, url, wroteRecord };
     }
     /**
      * 解析 hosting 访问地址：https://{CdnDomain}{deployPath}
@@ -189,32 +525,16 @@ class StaticDeployer {
         }
     }
     /**
-     * 本地构建（仅执行 buildCommand，不安装依赖）
+     * 解析 app 访问地址（DescribeCloudAppInfo.Domain 为准，托管 CDN 仅兜底）
      *
-     * 只跑用户的构建命令，依赖由用户自行安装（对齐业界：Vercel/Netlify/Cloudflare
-     * 均不在本地构建时代装依赖）。installCommand 不再被本地执行 —— CLI 侧通过
-     * installCommand: '' 已可跳过云端安装；本地一律不装。
+     * 拼接规则与 CLI `lib/app/utils.js` 的 `buildAppUrl` 同口径：
      *
-     * - buildCommand：由调用方保证非空（hosting 经 resolveBuildCommand 判定；app local 由 if 判定）
-     * - envVariables：注入构建进程环境变量（值统一转字符串）
-     */
-    runLocalBuild(projectPath, config, envVariables) {
-        const buildCommand = config.buildCommand || '';
-        const env = Object.assign(Object.assign({}, process.env), stringifyEnvValues(envVariables));
-        try {
-            if (buildCommand) {
-                (0, child_process_1.execSync)(buildCommand, { cwd: projectPath, stdio: 'inherit', env });
-            }
-        }
-        catch (e) {
-            const detail = ((e === null || e === void 0 ? void 0 : e.stderr) || (e === null || e === void 0 ? void 0 : e.stdout) || (e === null || e === void 0 ? void 0 : e.message) || String(e)).toString().trim();
-            (0, error_1.throwApiError)(`本地构建失败：在 ${projectPath} 执行「${buildCommand}」失败。\n` +
-                `请先在项目目录手动执行该命令排查原因（常见原因：构建脚本报错、依赖未安装、lockfile 不一致）。\n` +
-                (detail ? `原始错误：${detail.slice(0, 500)}` : ''));
-        }
-    }
-    /**
-     * 解析 app 访问地址（describeAppInfo.Domain + appPath）
+     * - **独立域名**（不含 `tcloudbaseapp.com`，如 `*.webapps.tcloudbase.com` / 自定义域名）：
+     *   域名本身已定位到应用，**不拼路径**，返回 `https://{domain}/`。
+     *   控制台「访问域名」展示的就是裸域名，拼上 AppPath 反而 404
+     *   （AppPath 是托管桶内的目录，不是该域名下的 URL 路径）。
+     * - **环境级共享域名**（`*.tcloudbaseapp.com`）：桶被整个环境共用，必须拼路径定位应用，
+     *   优先用服务端返回的 `AppPath`（用户可能在控制台改过），本地 `appPath` 仅作 fallback。
      */
     async resolveAppUrl(serviceName, appPath) {
         try {
@@ -222,11 +542,18 @@ class StaticDeployer {
                 deployType: 'static-hosting',
                 serviceName
             });
-            if (!appInfo.Domain) {
+            const domain = appInfo === null || appInfo === void 0 ? void 0 : appInfo.Domain;
+            if (!domain) {
                 return undefined;
             }
-            const normalizedPath = appPath.startsWith('/') ? appPath : `/${appPath}`;
-            return `https://${appInfo.Domain}${normalizedPath}`;
+            const cleanDomain = domain.replace(/^https?:\/\//, '').replace(/\/$/, '');
+            if (!cleanDomain.includes('tcloudbaseapp.com')) {
+                return `https://${cleanDomain}/`;
+            }
+            const serverAppPath = appInfo === null || appInfo === void 0 ? void 0 : appInfo.AppPath;
+            const effectivePath = serverAppPath && serverAppPath !== '/' ? serverAppPath : appPath;
+            const cleanPath = effectivePath.replace(/\/$/, '');
+            return `https://${cleanDomain}${cleanPath}/`;
         }
         catch (_a) {
             return undefined;