ylyx-cli 1.0.16 → 1.1.1

package/lib/deploy.js

@@ -1,529 +1,509 @@
-const path = require('path');
-const fs = require('fs-extra');
-const ora = require('ora');
-const inquirer = require('inquirer');
-const archiver = require('archiver');
-const { readProjectConfig } = require('./utils');
-
-let spinner = null; // 加载实例
-
-function formatTimestampCompact(date = new Date()) {
-  const pad2 = (n) => String(n).padStart(2, '0');
-  const yyyy = date.getFullYear();
-  const MM = pad2(date.getMonth() + 1);
-  const dd = pad2(date.getDate());
-  const HH = pad2(date.getHours());
-  const mm = pad2(date.getMinutes());
-  const ss = pad2(date.getSeconds());
-  return `${yyyy}${MM}${dd}${HH}${mm}${ss}`;
-}
-
-function formatTimestampForLog(date = new Date()) {
-  const pad2 = (n) => String(n).padStart(2, '0');
-  const yyyy = date.getFullYear();
-  const MM = pad2(date.getMonth() + 1);
-  const dd = pad2(date.getDate());
-  const HH = pad2(date.getHours());
-  const mm = pad2(date.getMinutes());
-  const ss = pad2(date.getSeconds());
-  return `${yyyy}-${MM}-${dd} ${HH}:${mm}:${ss}`;
-}
-
-function formatBytes(bytes) {
-  const n = Number(bytes) || 0;
-  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
-  let v = n;
-  let i = 0;
-  while (v >= 1024 && i < units.length - 1) {
-    v /= 1024;
-    i++;
-  }
-  const fixed = i === 0 ? 0 : v < 10 ? 2 : v < 100 ? 1 : 0;
-  return `${v.toFixed(fixed)}${units[i]}`;
-}
-
-function createDeployLogger({ env, buildDirName, outDir }) {
-  const logDir = path.join(outDir || path.join(process.cwd(), '.ylyx-deploy'), 'logs');
-  fs.ensureDirSync(logDir);
-  const fileName = `deploy-${env || 'unknown'}-${buildDirName || 'build'}-${formatTimestampCompact(
-    new Date()
-  )}.log`;
-  const logPath = path.join(logDir, fileName);
-  const stream = fs.createWriteStream(logPath, { flags: 'a' });
-
-  const log = (msg) => {
-    const line = `[${formatTimestampForLog(new Date())}] ${msg}\n`;
-    try {
-      stream.write(line);
-    } catch (e) {
-      // ignore
-    }
-  };
-
-  // 只记录“操作/目录/时间”的精简日志
-  const logOp = (op, target, extra) => {
-    const parts = [`op=${op}`];
-    if (target) parts.push(`target=${target}`);
-    if (extra) parts.push(`extra=${extra}`);
-    log(parts.join(' '));
-  };
-
-  const close = () =>
-    new Promise((resolve) => {
-      try {
-        stream.end(resolve);
-      } catch (e) {
-        resolve();
-      }
-    });
-
-  return { logPath, log, logOp, close };
-}
-
-function listLocalFilesWithSize(rootDir) {
-  const out = [];
-  const stack = [rootDir];
-  while (stack.length) {
-    const current = stack.pop();
-    const entries = fs.readdirSync(current);
-    for (const e of entries) {
-      const p = path.join(current, e);
-      const st = fs.statSync(p);
-      if (st.isDirectory()) stack.push(p);
-      else if (st.isFile()) {
-        out.push({
-          localPath: p,
-          relPosix: path.relative(rootDir, p).replace(/\\/g, '/'),
-          size: st.size,
-          mtimeMs: st.mtimeMs,
-        });
-      }
-    }
-  }
-  out.sort((a, b) => a.relPosix.localeCompare(b.relPosix));
-  return out;
-}
-
-function sanitizeBuildDirName(name) {
-  // 用户要求：项目名称来源于 buildDir 字段；同时确保文件名安全
-  return String(name || 'build')
-    .replace(/[\\/]/g, '')
-    .replace(/[^a-zA-Z0-9._-]/g, '')
-    .slice(0, 80);
-}
-
-function getBuildDirBaseName({ buildDir, localDir }) {
-  // buildDir 可能是路径：只取最后一级目录名
-  if (buildDir != null && String(buildDir).trim()) {
-    const normalized = String(buildDir).trim().replace(/\\/g, '/').replace(/\/+$/, '');
-    const last = normalized.split('/').filter(Boolean).pop();
-    if (last) return sanitizeBuildDirName(last);
-  }
-  // 兜底：使用 localDir 的最后一段目录名
-  return sanitizeBuildDirName(path.basename(path.resolve(localDir || process.cwd())));
-}
-
-function normalizeAndValidateRemoteDir(remoteDir) {
-  if (!remoteDir || typeof remoteDir !== 'string') return null;
-  // 统一成 Linux 风格
-  const raw = remoteDir.trim().replace(/\\/g, '/');
-  // 必须是绝对路径
-  if (!raw.startsWith('/')) {
-    throw new Error(
-      `deploy.remoteDir 必须是 Linux 绝对路径，并且只能在 /usr/local/nginx/html/* 下（当前: ${remoteDir})`
-    );
-  }
-
-  // 归一化，消除 .. 等
-  const resolved = path.posix.resolve(raw);
-  const base = '/usr/local/nginx/html';
-  const baseWithSlash = base + '/';
-
-  // 只允许 /usr/local/nginx/html/*（必须是子目录，不允许刚好等于 base）
-  if (!resolved.startsWith(baseWithSlash)) {
-    throw new Error(
-      `deploy.remoteDir 只能设置为 ${baseWithSlash}* 下的目录（当前: ${resolved}）`
-    );
-  }
-  if (resolved === base) {
-    throw new Error(`deploy.remoteDir 不能是 ${base} 根目录，请设置为其子目录（例如 ${baseWithSlash}my-app）`);
-  }
-  // 再防一次：禁止路径段包含 ..（即便 resolve 已处理，这里保证输入约束更明确）
-  const rel = resolved.slice(baseWithSlash.length);
-  if (!rel || rel.split('/').some((seg) => seg === '..')) {
-    throw new Error(`deploy.remoteDir 非法：不允许包含 ..（当前: ${resolved}）`);
-  }
-
-  return resolved;
-}
-
-async function zipDirAsTopFolder({ srcDir, zipPath, topFolderName }) {
-  fs.ensureDirSync(path.dirname(zipPath));
-  await new Promise((resolve, reject) => {
-    const output = fs.createWriteStream(zipPath);
-    const archive = archiver('zip', { zlib: { level: 9 } });
-
-    output.on('close', resolve);
-    output.on('error', reject);
-    archive.on('warning', (err) => {
-      if (err && err.code === 'ENOENT') return;
-      reject(err);
-    });
-    archive.on('error', reject);
-
-    archive.pipe(output);
-    // 关键：zip 内顶层目录名强制为 buildDirName
-    archive.directory(srcDir, topFolderName);
-    archive.finalize();
-  });
-}
-
-function hashLettersFromSha256(buf, lettersLen = 12) {
-  const alphabet = 'abcdefghijklmnop'; // 16 letters for 0..15
-  let out = '';
-  for (let i = 0; i < buf.length && out.length < lettersLen; i++) {
-    const b = buf[i];
-    out += alphabet[(b >> 4) & 0xf];
-    if (out.length >= lettersLen) break;
-    out += alphabet[b & 0xf];
-  }
-  return out.slice(0, lettersLen);
-}
-
-function computeDirHashLetters(localDir) {
-  const crypto = require('crypto');
-  const h = crypto.createHash('sha256');
-  const files = listLocalFilesWithSize(localDir);
-  for (const f of files) {
-    h.update(f.relPosix);
-    h.update('\n');
-    h.update(String(f.size || 0));
-    h.update('\n');
-    h.update(String(Math.floor(f.mtimeMs || 0)));
-    h.update('\n');
-  }
-  const digest = h.digest();
-  return hashLettersFromSha256(digest, 12);
-}
-
-async function chooseDeployEnv(env) {
-  if (env === 'test' || env === 'prod') return env;
-  const ans = await inquirer.prompt([
-    {
-      type: 'list',
-      name: 'env',
-      message: '请选择部署环境',
-      choices: [
-        { name: '部署测试服（上传到服务器）', value: 'test' },
-        { name: '部署正式服（不上传，仅压缩）', value: 'prod' },
-      ],
-      default: 'test',
-    },
-  ]);
-  return ans.env;
-}
-
-async function uploadDirWithProgress({ sftp, localDir, remoteDirPosix, onProgress }) {
-  const files = listLocalFilesWithSize(localDir);
-  const totalBytes = files.reduce((sum, f) => sum + (f.size || 0), 0);
-  if (files.length === 0) return { totalBytes: 0, uploadedBytes: 0, fileCount: 0 };
-
-  // 先创建需要的目录（去重）
-  const dirSet = new Set();
-  for (const f of files) {
-    const remoteFile = path.posix.join(remoteDirPosix, f.relPosix);
-    dirSet.add(path.posix.dirname(remoteFile));
-  }
-  // 目录从浅到深创建，避免多余失败
-  const dirs = Array.from(dirSet).sort((a, b) => a.length - b.length);
-  for (const d of dirs) {
-    await sftp.mkdir(d, true);
-  }
-
-  let uploadedBytes = 0;
-  let lastRenderAt = 0;
-  const render = (state) => {
-    if (typeof onProgress !== 'function') return;
-    const now = Date.now();
-    // 轻微节流，避免刷屏
-    if (now - lastRenderAt < 80 && state && state.force !== true) return;
-    lastRenderAt = now;
-    onProgress(state);
-  };
-
-  for (let i = 0; i < files.length; i++) {
-    const f = files[i];
-    const remoteFile = path.posix.join(remoteDirPosix, f.relPosix);
-    let lastTransferred = 0;
-
-    await sftp.fastPut(f.localPath, remoteFile, {
-      step: (transferred) => {
-        // transferred：当前文件已传输的总字节数（累计）
-        const delta = Math.max(0, Number(transferred || 0) - lastTransferred);
-        lastTransferred = Number(transferred || 0);
-        uploadedBytes += delta;
-        render({
-          uploadedBytes,
-          totalBytes,
-          fileIndex: i + 1,
-          fileCount: files.length,
-          currentFile: f.relPosix,
-        });
-      },
-    });
-
-    // fastPut 有时不会触发 step（极小文件/实现差异），这里兜底补齐本文件剩余字节
-    if (lastTransferred < f.size) {
-      uploadedBytes += f.size - lastTransferred;
-    }
-    render({
-      uploadedBytes,
-      totalBytes,
-      fileIndex: i + 1,
-      fileCount: files.length,
-      currentFile: f.relPosix,
-      force: true,
-    });
-  }
-
-  return { totalBytes, uploadedBytes, fileCount: files.length };
-}
-
-function resolveDeployConfig(overrides = {}) {
-  const projectConfig = readProjectConfig();
-  const deploy = (projectConfig && projectConfig.deploy) || {};
-
-  function parseDotEnvFile(envPath) {
-    if (!fs.existsSync(envPath)) return {};
-    const content = fs.readFileSync(envPath, 'utf-8');
-    const lines = content.split(/\r?\n/);
-    const out = {};
-    for (const raw of lines) {
-      const line = raw.trim();
-      if (!line || line.startsWith('#')) continue;
-      const idx = line.indexOf('=');
-      if (idx < 0) continue;
-      const key = line.slice(0, idx).trim();
-      let value = line.slice(idx + 1).trim();
-      if (
-        (value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))
-      ) {
-        value = value.slice(1, -1);
-      }
-      out[key] = value;
-    }
-    return out;
-  }
-
-  function normalizePublicUrlToDir(publicUrl) {
-    // 与 config.js 规则保持一致：忽略完整 URL；去掉首尾 /；把 \ 转 /
-    if (!publicUrl || typeof publicUrl !== 'string') return '';
-    let v = publicUrl.trim();
-    v = v.replace(/\\/g, '/');
-    if (/^https?:\/\//i.test(v)) return '';
-    v = v.replace(/^\/+/, '').replace(/\/+$/, '');
-    return v;
-  }
-
-  // localDir 默认优先从项目 .env.production 推导（VUE_APP_PUBLIC_URL -> 目录名）
-  const envProdPath = path.join(process.cwd(), '.env.production');
-  const envProd = parseDotEnvFile(envProdPath);
-  const publicUrlDir = normalizePublicUrlToDir(envProd.VUE_APP_PUBLIC_URL);
-  const inferredFromEnvProd = publicUrlDir ? path.resolve(process.cwd(), publicUrlDir) : null;
-
-  // localDir 默认使用项目 buildDir（打包输出目录）
-  // 规则：优先 deploy.localDir；否则使用 .env.production 的 VUE_APP_PUBLIC_URL；否则使用 .ylyxrc.json 的 buildDir；最后才回退 ./EXTERNAL_DIGIC
-  const inferredLocalDir =
-    deploy.localDir ||
-    inferredFromEnvProd ||
-    (projectConfig && projectConfig.buildDir ? path.resolve(process.cwd(), projectConfig.buildDir) : null);
-
-  if (!inferredLocalDir) {
-    throw new Error(
-      '无法确定 deploy.localDir（本地打包目录）。请设置以下任意一种：\n' +
-        '- 在 .ylyxrc.json 配置 deploy.localDir\n' +
-        '- 在项目 .env.production 配置 VUE_APP_PUBLIC_URL（相对路径，如 /dist/app/）\n' +
-        '- 在 .ylyxrc.json 配置 buildDir（可相对/绝对路径）'
-    );
-  }
-
-  const cfg = {
-    env: overrides.env ?? deploy.env,
-    buildDir: overrides.buildDir ?? deploy.buildDir ?? projectConfig.buildDir,
-    host: overrides.host ?? deploy.host,
-    port: String(overrides.port ?? deploy.port ?? '22'),
-    username: overrides.username ?? deploy.username,
-    password: overrides.password ?? deploy.password,
-    localDir: overrides.localDir ?? inferredLocalDir,
-    remoteDir: normalizeAndValidateRemoteDir(overrides.remoteDir ?? deploy.remoteDir),
-    zipAfter: overrides.zipAfter ?? deploy.zipAfter ?? false,
-    zipOutDir: overrides.zipOutDir ?? deploy.zipOutDir ?? path.join(process.cwd(), '.ylyx-deploy'),
-  };
-
-  return cfg;
-}
-
-/**
- * 执行部署（递归上传目录到远端）
- * 测试服：上传到服务器（可选部署后压缩）
- * 正式服：不上传，仅压缩
- * @param {{env?:'test'|'prod',host?:string,port?:string|number,username?:string,password?:string,localDir?:string,remoteDir?:string,zipAfter?:boolean,zipOutDir?:string}} overrides
- */
-async function deploy(overrides = {}) {
-  const cfg = resolveDeployConfig(overrides);
-  const localFolderPath = cfg.localDir;
-  const remoteFolderPath = cfg.remoteDir;
-
-  const env = await chooseDeployEnv(cfg.env);
-  const buildDirNameForLog = getBuildDirBaseName({ buildDir: cfg.buildDir, localDir: localFolderPath });
-  const logger = createDeployLogger({ env, buildDirName: buildDirNameForLog, outDir: cfg.zipOutDir });
-  logger.logOp('DEPLOY_START', '', `env=${env}`);
-  logger.logOp('LOCAL_DIR', localFolderPath);
-  if (remoteFolderPath) logger.logOp('REMOTE_DIR', remoteFolderPath);
-
-  if (!fs.existsSync(localFolderPath)) {
-    logger.logOp('ERROR', localFolderPath, 'localDir_not_exists');
-    await logger.close();
-    throw new Error(`本地目录不存在：${path.resolve(localFolderPath)}`);
-  }
-
-  // 正式服：仅压缩
-  if (env === 'prod') {
-    const buildDirName = buildDirNameForLog;
-    const ts = formatTimestampCompact(new Date());
-    const hashLetters = computeDirHashLetters(localFolderPath); // 纯字母
-    // 优化命名：更可读、更易分割（buildDir-时间-哈希）
-    const zipBaseName = `${buildDirName}-${ts}-${hashLetters}`;
-    fs.ensureDirSync(cfg.zipOutDir);
-    const zipName = `${zipBaseName}.zip`;
-    const zipPath = path.join(cfg.zipOutDir, zipName);
-    logger.logOp('ZIP_START', zipPath);
-
-    const zipSpinner = ora(`开始压缩：${zipName}`).start();
-    try {
-      await zipDirAsTopFolder({ srcDir: localFolderPath, zipPath, topFolderName: buildDirName });
-      zipSpinner.succeed(`压缩完成：${path.relative(process.cwd(), zipPath)}`);
-      logger.logOp('ZIP_DONE', zipPath);
-    } catch (e) {
-      zipSpinner.fail('压缩失败');
-      logger.logOp('ERROR', zipPath, `zip_failed:${e && e.message ? e.message : String(e)}`);
-      await logger.close();
-      throw e;
-    }
-    logger.logOp('DEPLOY_END', '', 'prod');
-    await logger.close();
-    return;
-  }
-
-  // 测试服：上传到服务器
-  if (!cfg.host) throw new Error('缺少 deploy.host（测试服上传需要）');
-  if (!cfg.username) throw new Error('缺少 deploy.username（测试服上传需要）');
-  if (!cfg.password) throw new Error('缺少 deploy.password（测试服上传需要）');
-  if (!remoteFolderPath) {
-    logger.logOp('ERROR', '', 'missing_remoteDir');
-    await logger.close();
-    throw new Error('缺少 deploy.remoteDir（测试服上传需要）：请在 .ylyxrc.json 的 deploy.remoteDir 配置远端部署目录');
-  }
-
-  let Client;
-  try {
-    Client = require('ssh2-sftp-client');
-  } catch (e) {
-    throw new Error(
-      "缺少依赖：ssh2-sftp-client。\n" +
-        "如果你在 ylyx-cli 仓库本地跑：请先在 ylyx-cli 目录执行 `npm i`。\n" +
-        "如果你用 npx：请确认你运行的是已发布且包含依赖的版本，或清理 npx 缓存后重试。"
-    );
-  }
-
-  const sftp = new Client();
-  try {
-    spinner = ora('连接服务器...').start();
-    logger.logOp('SFTP_CONNECT', cfg.host, `port=${cfg.port} username=${cfg.username}`);
-    await sftp.connect({
-      host: cfg.host,
-      port: cfg.port,
-      username: cfg.username,
-      password: cfg.password,
-    });
-
-    spinner.text = '服务器连接成功，准备清理远端目录...';
-    logger.logOp('REMOTE_DELETE_START', remoteFolderPath);
-    try {
-      await sftp.rmdir(remoteFolderPath, true);
-      logger.logOp('REMOTE_DELETE_DONE', remoteFolderPath);
-    } catch (e) {
-      // ignore
-      logger.logOp('REMOTE_DELETE_SKIP', remoteFolderPath, e && e.message ? e.message : 'ignored');
-    }
-    await sftp.mkdir(remoteFolderPath, true);
-    logger.logOp('REMOTE_MKDIR', remoteFolderPath);
-
-    const remoteDirPosix = remoteFolderPath.replace(/\\/g, '/');
-    spinner.text = '开始上传目录...';
-    logger.logOp('UPLOAD_START', remoteDirPosix, `from=${localFolderPath}`);
-    const { uploadedBytes, totalBytes, fileCount } = await uploadDirWithProgress({
-      sftp,
-      localDir: localFolderPath,
-      remoteDirPosix,
-      onProgress: ({ uploadedBytes: up, totalBytes: tot, fileIndex, fileCount: cnt, currentFile }) => {
-        const percent = tot ? ((up / tot) * 100).toFixed(2) : '100.00';
-        const shortFile = currentFile ? currentFile.slice(-60) : '';
-        spinner.text = `上传进度: ${percent}% (${formatBytes(up)}/${formatBytes(tot)}) 文件:${fileIndex}/${cnt} ${shortFile}`;
-      },
-    });
-    spinner.succeed(`上传成功：${formatBytes(uploadedBytes)}/${formatBytes(totalBytes)}，共 ${fileCount} 个文件`);
-    logger.logOp('UPLOAD_DONE', remoteDirPosix, `files=${fileCount} bytes=${uploadedBytes}/${totalBytes}`);
-  } catch (err) {
-    if (spinner) spinner.fail('部署失败');
-    logger.logOp('ERROR', '', err && err.message ? err.message : String(err));
-    await logger.close();
-    throw err;
-  } finally {
-    try {
-      await sftp.end();
-    } catch (e) {}
-    if (spinner) spinner.info('部署结束');
-  }
-
-  // 测试服可选：部署后压缩（延续之前的可选开关）
-  if (cfg.zipAfter) {
-    const buildDirName = buildDirNameForLog;
-    const ts = formatTimestampCompact(new Date());
-    const hashLetters = computeDirHashLetters(localFolderPath); // 纯字母
-    const zipBaseName = `${buildDirName}-${ts}-${hashLetters}`;
-    fs.ensureDirSync(cfg.zipOutDir);
-    const zipName = `${zipBaseName}.zip`;
-    const zipPath = path.join(cfg.zipOutDir, zipName);
-    logger.logOp('ZIP_START', zipPath);
-
-    const zipSpinner = ora(`开始压缩：${zipName}`).start();
-    try {
-      await zipDirAsTopFolder({ srcDir: localFolderPath, zipPath, topFolderName: buildDirName });
-      zipSpinner.succeed(`压缩完成：${path.relative(process.cwd(), zipPath)}`);
-      logger.logOp('ZIP_DONE', zipPath);
-    } catch (e) {
-      zipSpinner.fail('压缩失败');
-      logger.logOp('ERROR', zipPath, `zip_failed:${e && e.message ? e.message : String(e)}`);
-      await logger.close();
-      throw e;
-    }
-  }
-
-  logger.logOp('DEPLOY_END', '', 'test');
-  await logger.close();
-}
-
-module.exports = {
-  deploy,
-  resolveDeployConfig,
-};
-
-// 允许直接 node lib/deploy.js 运行（从 .ylyxrc.json 读取 deploy 配置）
-if (require.main === module) {
-  deploy().catch((e) => {
-    console.error(e);
-    process.exit(1);
-  });
-}
+const path = require('path');
+const fs = require('fs-extra');
+const ora = require('ora');
+const inquirer = require('inquirer');
+const archiver = require('archiver');
+const { readProjectConfig } = require('./utils');
+const { assertConfigMigrated, findEnvironment, getConfigPath } = require('./environments');
+
+let spinner = null; // 加载实例
+
+function formatTimestampCompact(date = new Date()) {
+  const pad2 = (n) => String(n).padStart(2, '0');
+  const yyyy = date.getFullYear();
+  const MM = pad2(date.getMonth() + 1);
+  const dd = pad2(date.getDate());
+  const HH = pad2(date.getHours());
+  const mm = pad2(date.getMinutes());
+  const ss = pad2(date.getSeconds());
+  return `${yyyy}${MM}${dd}${HH}${mm}${ss}`;
+}
+
+function formatTimestampForLog(date = new Date()) {
+  const pad2 = (n) => String(n).padStart(2, '0');
+  const yyyy = date.getFullYear();
+  const MM = pad2(date.getMonth() + 1);
+  const dd = pad2(date.getDate());
+  const HH = pad2(date.getHours());
+  const mm = pad2(date.getMinutes());
+  const ss = pad2(date.getSeconds());
+  return `${yyyy}-${MM}-${dd} ${HH}:${mm}:${ss}`;
+}
+
+function formatBytes(bytes) {
+  const n = Number(bytes) || 0;
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let v = n;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  const fixed = i === 0 ? 0 : v < 10 ? 2 : v < 100 ? 1 : 0;
+  return `${v.toFixed(fixed)}${units[i]}`;
+}
+
+function createDeployLogger({ env, buildDirName, outDir }) {
+  const logDir = path.join(outDir || path.join(process.cwd(), '.ylyx-deploy'), 'logs');
+  fs.ensureDirSync(logDir);
+  const fileName = `deploy-${env || 'unknown'}-${buildDirName || 'build'}-${formatTimestampCompact(
+    new Date()
+  )}.log`;
+  const logPath = path.join(logDir, fileName);
+  const stream = fs.createWriteStream(logPath, { flags: 'a' });
+
+  const log = (msg) => {
+    const line = `[${formatTimestampForLog(new Date())}] ${msg}\n`;
+    try {
+      stream.write(line);
+    } catch (e) {
+      // ignore
+    }
+  };
+
+  // 只记录“操作/目录/时间”的精简日志
+  const logOp = (op, target, extra) => {
+    const parts = [`op=${op}`];
+    if (target) parts.push(`target=${target}`);
+    if (extra) parts.push(`extra=${extra}`);
+    log(parts.join(' '));
+  };
+
+  const close = () =>
+    new Promise((resolve) => {
+      try {
+        stream.end(resolve);
+      } catch (e) {
+        resolve();
+      }
+    });
+
+  return { logPath, log, logOp, close };
+}
+
+function listLocalFilesWithSize(rootDir) {
+  const out = [];
+  const stack = [rootDir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current);
+    for (const e of entries) {
+      const p = path.join(current, e);
+      const st = fs.statSync(p);
+      if (st.isDirectory()) stack.push(p);
+      else if (st.isFile()) {
+        out.push({
+          localPath: p,
+          relPosix: path.relative(rootDir, p).replace(/\\/g, '/'),
+          size: st.size,
+          mtimeMs: st.mtimeMs,
+        });
+      }
+    }
+  }
+  out.sort((a, b) => a.relPosix.localeCompare(b.relPosix));
+  return out;
+}
+
+function sanitizeBuildDirName(name) {
+  // 用户要求：项目名称来源于 buildDir 字段；同时确保文件名安全
+  return String(name || 'build')
+    .replace(/[\\/]/g, '')
+    .replace(/[^a-zA-Z0-9._-]/g, '')
+    .slice(0, 80);
+}
+
+function getBuildDirBaseName({ buildDir, localDir }) {
+  // buildDir 可能是路径：只取最后一级目录名
+  if (buildDir != null && String(buildDir).trim()) {
+    const normalized = String(buildDir).trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    const last = normalized.split('/').filter(Boolean).pop();
+    if (last) return sanitizeBuildDirName(last);
+  }
+  // 兜底：使用 localDir 的最后一段目录名
+  return sanitizeBuildDirName(path.basename(path.resolve(localDir || process.cwd())));
+}
+
+function normalizeAndValidateRemoteDir(remoteDir) {
+  if (!remoteDir || typeof remoteDir !== 'string') return null;
+  // 统一成 Linux 风格
+  const raw = remoteDir.trim().replace(/\\/g, '/');
+  // 必须是绝对路径
+  if (!raw.startsWith('/')) {
+    throw new Error(
+      `deploy.remoteDir 必须是 Linux 绝对路径，并且只能在 /usr/local/nginx/html/* 下（当前: ${remoteDir})`
+    );
+  }
+
+  // 归一化，消除 .. 等
+  const resolved = path.posix.resolve(raw);
+  const base = '/usr/local/nginx/html';
+  const baseWithSlash = base + '/';
+
+  // 只允许 /usr/local/nginx/html/*（必须是子目录，不允许刚好等于 base）
+  if (!resolved.startsWith(baseWithSlash)) {
+    throw new Error(
+      `deploy.remoteDir 只能设置为 ${baseWithSlash}* 下的目录（当前: ${resolved}）`
+    );
+  }
+  if (resolved === base) {
+    throw new Error(`deploy.remoteDir 不能是 ${base} 根目录，请设置为其子目录（例如 ${baseWithSlash}my-app）`);
+  }
+  // 再防一次：禁止路径段包含 ..（即便 resolve 已处理，这里保证输入约束更明确）
+  const rel = resolved.slice(baseWithSlash.length);
+  if (!rel || rel.split('/').some((seg) => seg === '..')) {
+    throw new Error(`deploy.remoteDir 非法：不允许包含 ..（当前: ${resolved}）`);
+  }
+
+  return resolved;
+}
+
+async function zipDirAsTopFolder({ srcDir, zipPath, topFolderName }) {
+  fs.ensureDirSync(path.dirname(zipPath));
+  await new Promise((resolve, reject) => {
+    const output = fs.createWriteStream(zipPath);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', resolve);
+    output.on('error', reject);
+    archive.on('warning', (err) => {
+      if (err && err.code === 'ENOENT') return;
+      reject(err);
+    });
+    archive.on('error', reject);
+
+    archive.pipe(output);
+    // 关键：zip 内顶层目录名强制为 buildDirName
+    archive.directory(srcDir, topFolderName);
+    archive.finalize();
+  });
+}
+
+function hashLettersFromSha256(buf, lettersLen = 12) {
+  const alphabet = 'abcdefghijklmnop'; // 16 letters for 0..15
+  let out = '';
+  for (let i = 0; i < buf.length && out.length < lettersLen; i++) {
+    const b = buf[i];
+    out += alphabet[(b >> 4) & 0xf];
+    if (out.length >= lettersLen) break;
+    out += alphabet[b & 0xf];
+  }
+  return out.slice(0, lettersLen);
+}
+
+function computeDirHashLetters(localDir) {
+  const crypto = require('crypto');
+  const h = crypto.createHash('sha256');
+  const files = listLocalFilesWithSize(localDir);
+  for (const f of files) {
+    h.update(f.relPosix);
+    h.update('\n');
+    h.update(String(f.size || 0));
+    h.update('\n');
+    h.update(String(Math.floor(f.mtimeMs || 0)));
+    h.update('\n');
+  }
+  const digest = h.digest();
+  return hashLettersFromSha256(digest, 12);
+}
+
+// 注意：这里"环境不存在或不可部署"的判断逻辑与 resolveDeployConfig 内部的
+// findEnvironment + deployMethod==='none' 检查在语义上等价，只是分别在
+// "交互选择阶段"和"最终解析阶段"各自独立校验一次（后者作为独立导出函数，
+// 必须能脱离 chooseDeployEnv 单独工作，因此不合并成一个函数）。
+async function chooseDeployEnv(projectConfig, envArg) {
+  const environments = (projectConfig.environments || []).filter((e) => e.deployMethod !== 'none');
+
+  if (envArg) {
+    if (!environments.some((e) => e.name === envArg)) {
+      const available = environments.map((e) => e.name).join(', ') || '(无)';
+      throw new Error(`环境 "${envArg}" 不可部署或不存在\n可部署环境: ${available}`);
+    }
+    return envArg;
+  }
+
+  if (environments.length === 0) {
+    throw new Error('没有可部署的环境（所有环境的 deployMethod 均为 none，或未定义 environments）');
+  }
+
+  const ans = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'env',
+      message: '请选择部署环境',
+      choices: environments.map((e) => ({
+        name: `${e.name}（${e.deployMethod === 'upload' ? '上传到服务器' : '仅压缩'}）`,
+        value: e.name,
+      })),
+    },
+  ]);
+  return ans.env;
+}
+
+async function uploadDirWithProgress({ sftp, localDir, remoteDirPosix, onProgress }) {
+  const files = listLocalFilesWithSize(localDir);
+  const totalBytes = files.reduce((sum, f) => sum + (f.size || 0), 0);
+  if (files.length === 0) return { totalBytes: 0, uploadedBytes: 0, fileCount: 0 };
+
+  // 先创建需要的目录（去重）
+  const dirSet = new Set();
+  for (const f of files) {
+    const remoteFile = path.posix.join(remoteDirPosix, f.relPosix);
+    dirSet.add(path.posix.dirname(remoteFile));
+  }
+  // 目录从浅到深创建，避免多余失败
+  const dirs = Array.from(dirSet).sort((a, b) => a.length - b.length);
+  for (const d of dirs) {
+    await sftp.mkdir(d, true);
+  }
+
+  let uploadedBytes = 0;
+  let lastRenderAt = 0;
+  const render = (state) => {
+    if (typeof onProgress !== 'function') return;
+    const now = Date.now();
+    // 轻微节流，避免刷屏
+    if (now - lastRenderAt < 80 && state && state.force !== true) return;
+    lastRenderAt = now;
+    onProgress(state);
+  };
+
+  for (let i = 0; i < files.length; i++) {
+    const f = files[i];
+    const remoteFile = path.posix.join(remoteDirPosix, f.relPosix);
+    let lastTransferred = 0;
+
+    await sftp.fastPut(f.localPath, remoteFile, {
+      step: (transferred) => {
+        // transferred：当前文件已传输的总字节数（累计）
+        const delta = Math.max(0, Number(transferred || 0) - lastTransferred);
+        lastTransferred = Number(transferred || 0);
+        uploadedBytes += delta;
+        render({
+          uploadedBytes,
+          totalBytes,
+          fileIndex: i + 1,
+          fileCount: files.length,
+          currentFile: f.relPosix,
+        });
+      },
+    });
+
+    // fastPut 有时不会触发 step（极小文件/实现差异），这里兜底补齐本文件剩余字节
+    if (lastTransferred < f.size) {
+      uploadedBytes += f.size - lastTransferred;
+    }
+    render({
+      uploadedBytes,
+      totalBytes,
+      fileIndex: i + 1,
+      fileCount: files.length,
+      currentFile: f.relPosix,
+      force: true,
+    });
+  }
+
+  return { totalBytes, uploadedBytes, fileCount: files.length };
+}
+
+function resolveDeployConfig(envName, overrides = {}, projectConfig) {
+  if (!projectConfig) {
+    projectConfig = readProjectConfig();
+    assertConfigMigrated(projectConfig, fs.existsSync(getConfigPath()));
+  }
+  const env = findEnvironment(projectConfig, envName);
+
+  if (env.deployMethod === 'none') {
+    throw new Error(`环境 "${env.name}" 不支持部署（deployMethod=none）`);
+  }
+
+  const buildDir = overrides.buildDir ?? env.buildDir;
+  const localDirRaw = overrides.localDir ?? env.localDir ?? buildDir;
+  const localDir = localDirRaw ? path.resolve(process.cwd(), localDirRaw) : null;
+
+  if (!localDir) {
+    throw new Error(
+      `无法确定环境 "${env.name}" 的本地目录（用于上传/压缩）。请在 .ylyxrc.json 该环境条目配置 localDir 或 buildDir`
+    );
+  }
+
+  const cfg = {
+    name: env.name,
+    deployMethod: env.deployMethod,
+    buildDir,
+    host: overrides.host ?? env.host,
+    port: String(overrides.port ?? env.port ?? '22'),
+    username: overrides.username ?? env.username,
+    password: overrides.password ?? env.password,
+    localDir,
+    remoteDir: normalizeAndValidateRemoteDir(overrides.remoteDir ?? env.remoteDir),
+    zipAfter: overrides.zipAfter ?? env.zipAfter ?? false,
+    zipOutDir: path.resolve(process.cwd(), overrides.zipOutDir ?? env.zipOutDir ?? './.ylyx-deploy'),
+  };
+
+  return cfg;
+}
+
+/**
+ * 执行部署（按环境的 deployMethod 分支：upload=SFTP 上传，zip=仅压缩）
+ * @param {{env?:string,host?:string,port?:string|number,username?:string,password?:string,localDir?:string,remoteDir?:string,zipAfter?:boolean,zipOutDir?:string,buildDir?:string}} overrides
+ */
+async function deploy(overrides = {}) {
+  const projectConfig = readProjectConfig();
+  assertConfigMigrated(projectConfig, fs.existsSync(getConfigPath()));
+
+  const envName = await chooseDeployEnv(projectConfig, overrides.env);
+  const cfg = resolveDeployConfig(envName, overrides, projectConfig);
+  const localFolderPath = cfg.localDir;
+  const remoteFolderPath = cfg.remoteDir;
+
+  const buildDirNameForLog = getBuildDirBaseName({ buildDir: cfg.buildDir, localDir: localFolderPath });
+  const logger = createDeployLogger({ env: cfg.name, buildDirName: buildDirNameForLog, outDir: cfg.zipOutDir });
+  logger.logOp('DEPLOY_START', '', `env=${cfg.name}`);
+  logger.logOp('LOCAL_DIR', localFolderPath);
+  if (remoteFolderPath) logger.logOp('REMOTE_DIR', remoteFolderPath);
+
+  if (!fs.existsSync(localFolderPath)) {
+    logger.logOp('ERROR', localFolderPath, 'localDir_not_exists');
+    await logger.close();
+    throw new Error(`本地目录不存在：${path.resolve(localFolderPath)}`);
+  }
+
+  // deployMethod=zip：仅压缩，不上传
+  if (cfg.deployMethod === 'zip') {
+    const buildDirName = buildDirNameForLog;
+    const ts = formatTimestampCompact(new Date());
+    const hashLetters = computeDirHashLetters(localFolderPath); // 纯字母
+    const zipBaseName = `${buildDirName}-${ts}-${hashLetters}`;
+    fs.ensureDirSync(cfg.zipOutDir);
+    const zipName = `${zipBaseName}.zip`;
+    const zipPath = path.join(cfg.zipOutDir, zipName);
+    logger.logOp('ZIP_START', zipPath);
+
+    const zipSpinner = ora(`开始压缩：${zipName}`).start();
+    try {
+      await zipDirAsTopFolder({ srcDir: localFolderPath, zipPath, topFolderName: buildDirName });
+      zipSpinner.succeed(`压缩完成：${path.relative(process.cwd(), zipPath)}`);
+      logger.logOp('ZIP_DONE', zipPath);
+    } catch (e) {
+      zipSpinner.fail('压缩失败');
+      logger.logOp('ERROR', zipPath, `zip_failed:${e && e.message ? e.message : String(e)}`);
+      await logger.close();
+      throw e;
+    }
+    logger.logOp('DEPLOY_END', '', cfg.name);
+    await logger.close();
+    return;
+  }
+
+  // deployMethod=upload：上传到服务器
+  if (!cfg.host) throw new Error(`缺少环境 "${cfg.name}" 的 host（上传需要）`);
+  if (!cfg.username) throw new Error(`缺少环境 "${cfg.name}" 的 username（上传需要）`);
+  if (!cfg.password) throw new Error(`缺少环境 "${cfg.name}" 的 password（上传需要）`);
+  if (!remoteFolderPath) {
+    logger.logOp('ERROR', '', 'missing_remoteDir');
+    await logger.close();
+    throw new Error(`缺少环境 "${cfg.name}" 的 remoteDir（上传需要）：请在 .ylyxrc.json 该环境条目配置 remoteDir`);
+  }
+
+  let Client;
+  try {
+    Client = require('ssh2-sftp-client');
+  } catch (e) {
+    throw new Error(
+      "缺少依赖：ssh2-sftp-client。\n" +
+        "如果你在 ylyx-cli 仓库本地跑：请先在 ylyx-cli 目录执行 `npm i`。\n" +
+        "如果你用 npx：请确认你运行的是已发布且包含依赖的版本，或清理 npx 缓存后重试。"
+    );
+  }
+
+  const sftp = new Client();
+  try {
+    spinner = ora('连接服务器...').start();
+    logger.logOp('SFTP_CONNECT', cfg.host, `port=${cfg.port} username=${cfg.username}`);
+    await sftp.connect({
+      host: cfg.host,
+      port: cfg.port,
+      username: cfg.username,
+      password: cfg.password,
+    });
+
+    spinner.text = '服务器连接成功，准备清理远端目录...';
+    logger.logOp('REMOTE_DELETE_START', remoteFolderPath);
+    try {
+      await sftp.rmdir(remoteFolderPath, true);
+      logger.logOp('REMOTE_DELETE_DONE', remoteFolderPath);
+    } catch (e) {
+      // ignore
+      logger.logOp('REMOTE_DELETE_SKIP', remoteFolderPath, e && e.message ? e.message : 'ignored');
+    }
+    await sftp.mkdir(remoteFolderPath, true);
+    logger.logOp('REMOTE_MKDIR', remoteFolderPath);
+
+    const remoteDirPosix = remoteFolderPath.replace(/\\/g, '/');
+    spinner.text = '开始上传目录...';
+    logger.logOp('UPLOAD_START', remoteDirPosix, `from=${localFolderPath}`);
+    const { uploadedBytes, totalBytes, fileCount } = await uploadDirWithProgress({
+      sftp,
+      localDir: localFolderPath,
+      remoteDirPosix,
+      onProgress: ({ uploadedBytes: up, totalBytes: tot, fileIndex, fileCount: cnt, currentFile }) => {
+        const percent = tot ? ((up / tot) * 100).toFixed(2) : '100.00';
+        const shortFile = currentFile ? currentFile.slice(-60) : '';
+        spinner.text = `上传进度: ${percent}% (${formatBytes(up)}/${formatBytes(tot)}) 文件:${fileIndex}/${cnt} ${shortFile}`;
+      },
+    });
+    spinner.succeed(`上传成功：${formatBytes(uploadedBytes)}/${formatBytes(totalBytes)}，共 ${fileCount} 个文件`);
+    logger.logOp('UPLOAD_DONE', remoteDirPosix, `files=${fileCount} bytes=${uploadedBytes}/${totalBytes}`);
+  } catch (err) {
+    if (spinner) spinner.fail('部署失败');
+    logger.logOp('ERROR', '', err && err.message ? err.message : String(err));
+    await logger.close();
+    throw err;
+  } finally {
+    try {
+      await sftp.end();
+    } catch (e) {}
+    if (spinner) spinner.info('部署结束');
+  }
+
+  // 上传后可选：再压缩一份（延续之前的可选开关）
+  if (cfg.zipAfter) {
+    const buildDirName = buildDirNameForLog;
+    const ts = formatTimestampCompact(new Date());
+    const hashLetters = computeDirHashLetters(localFolderPath); // 纯字母
+    const zipBaseName = `${buildDirName}-${ts}-${hashLetters}`;
+    fs.ensureDirSync(cfg.zipOutDir);
+    const zipName = `${zipBaseName}.zip`;
+    const zipPath = path.join(cfg.zipOutDir, zipName);
+    logger.logOp('ZIP_START', zipPath);
+
+    const zipSpinner = ora(`开始压缩：${zipName}`).start();
+    try {
+      await zipDirAsTopFolder({ srcDir: localFolderPath, zipPath, topFolderName: buildDirName });
+      zipSpinner.succeed(`压缩完成：${path.relative(process.cwd(), zipPath)}`);
+      logger.logOp('ZIP_DONE', zipPath);
+    } catch (e) {
+      zipSpinner.fail('压缩失败');
+      logger.logOp('ERROR', zipPath, `zip_failed:${e && e.message ? e.message : String(e)}`);
+      await logger.close();
+      throw e;
+    }
+  }
+
+  logger.logOp('DEPLOY_END', '', cfg.name);
+  await logger.close();
+}
+
+module.exports = {
+  deploy,
+  resolveDeployConfig,
+};
+
+// 允许直接 node lib/deploy.js 运行（从 .ylyxrc.json 读取 deploy 配置）
+if (require.main === module) {
+  deploy().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}