@zhipu/zp-cli 0.0.2 → 0.0.4

package/README.md

@@ -16,10 +16,21 @@ zpc pack
 # 在服务器上：目录内需有 <projectName>-dist.zip + zpc.config.*（配置不要打进压缩包）
 zpc deploy
 zpc deploy --force      # 允许抢占冲突的 nginx proxy
+
+# 盘点部署目录与 nginx 配置，标注已记录 / 未记录 / 记录但缺失
+zpc check
 ```
 
+`zpc deploy` 若发现无 `~/.zpc` 部署记录、但 api/web 部署目录非空或已有本项目 nginx 配置，会交互询问：
+
+1. 清空目标文件夹并覆盖（全量，旧目录备份为带时间戳的 `.bak-*`）
+2. 使用增量部署（api 保留 `excludeOnIncremental` 指定项，默认 `public`；web 全量覆盖）
+3. 取消部署（默认；非交互环境同样默认取消）
+
 可选环境变量：`DEPLOY_DIR`、`DEPLOY_FORCE`；`ZPC_HOME` 覆盖 `~/.zpc`（部署状态记录）；测试可用 `ZPC_API_ROOT` / `ZPC_WEB_ROOT` / `ZPC_NGINX_DEFAULT_D` / `ZPC_DEPLOY_SKIP_RUNTIME`。
 
+`api.excludeOnIncremental`：增量部署时排除、不覆盖的目录或文件名列表，默认 `["public"]`；仅对 api 生效，指定项在增量部署后保留服务器上的既有内容。
+
 ## 部署约定
 
 `zpc.config` 中的 `projectName` 即下文 `<system-tag>`。

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { a as findConfigFile, c as loadConfig, l as templateFileName, n as SCHEMA_FILE_NAME, o as isConfigFormat, r as configFileName, s as listConfigFiles, t as CONFIG_FORMATS } from "./config-BZc9pg7J.mjs";
+import { a as findConfigFile, c as loadConfig, l as templateFileName, n as SCHEMA_FILE_NAME, o as isConfigFormat, r as configFileName, s as listConfigFiles, t as CONFIG_FORMATS } from "./config-DzcldbBT.mjs";
 import { createRequire } from "node:module";
 import fs, { mkdtempSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -8,7 +8,7 @@ import os, { tmpdir } from "node:os";
 import chalk from "chalk";
 import zlib from "node:zlib";
 //#region package.json
-var version = "0.0.2";
+var version = "0.0.4";
 var description = "内部单命令部署工具";
 //#endregion
 //#region src/utils/deploy-paths.ts
@@ -321,17 +321,20 @@ function listNamedDirs(parent) {
 	if (!fs.existsSync(parent)) return [];
 	return fs.readdirSync(parent, { withFileTypes: true }).filter((d) => d.isDirectory() && isSafeDirName(d.name) && !d.name.startsWith(".")).map((d) => d.name);
 }
-/** 原子风格替换目录：删旧 `.bak` → 现目录改名为 `.bak` → 拷入新内容。 */
+function backupTimestamp() {
+	const d = /* @__PURE__ */ new Date();
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+/**
+* 原子风格替换目录：现目录改名为带时间戳的唯一 `.bak-*` 备份 → 拷入新内容。
+* 备份名含时间戳，多次覆盖不会互相覆盖，历史版本得以保留；失败从该备份恢复。
+*/
 function deployDir(src, dest, log) {
 	fs.mkdirSync(path.dirname(dest), { recursive: true });
-	const bak = `${dest}.bak`;
-	if (fs.existsSync(bak)) {
-		log(`删除旧备份 ${bak}`);
-		fs.rmSync(bak, {
-			recursive: true,
-			force: true
-		});
-	}
+	const stamp = backupTimestamp();
+	let bak = `${dest}.bak-${stamp}`;
+	for (let i = 1; fs.existsSync(bak); i++) bak = `${dest}.bak-${stamp}-${i}`;
 	if (fs.existsSync(dest)) {
 		log(`备份 ${dest} -> ${bak}`);
 		fs.renameSync(dest, bak);
@@ -348,8 +351,8 @@ function deployDir(src, dest, log) {
 	}
 }
 const API_INCREMENTAL_FILES = ["package.json", "bootstrap.js"];
-/** api 增量部署：只替换 dist 与根部 package.json / bootstrap.js，不碰 public。 */
-function deployApiIncremental(src, dest, log) {
+/** api 增量部署：只替换 dist 与根部 package.json / bootstrap.js，不覆盖 excludeOnIncremental 指定项。 */
+function deployApiIncremental(src, dest, exclude, log) {
 	const distSrc = path.join(src, "dist");
 	if (!fs.existsSync(distSrc)) throw new Error(`[deploy] ${src} 缺少 dist，无法增量部署`);
 	fs.mkdirSync(dest, { recursive: true });
@@ -375,8 +378,15 @@ function deployApiIncremental(src, dest, log) {
 		if (!fs.existsSync(from)) throw new Error(`[deploy] ${src} 缺少 ${file}，无法增量部署`);
 		fs.cpSync(from, path.join(dest, file));
 	}
-	fs.mkdirSync(path.join(dest, "public"), { recursive: true });
-	log(`增量部署 ${src} -> ${dest}（更新 dist、${API_INCREMENTAL_FILES.join("、")}，保留 public）`);
+	for (const entry of exclude) {
+		const destEntry = path.join(dest, entry);
+		if (fs.existsSync(destEntry)) continue;
+		const srcEntry = path.join(src, entry);
+		if (fs.existsSync(srcEntry) && !fs.statSync(srcEntry).isDirectory()) continue;
+		fs.mkdirSync(destEntry, { recursive: true });
+	}
+	const skipText = exclude.length ? `，跳过 ${exclude.join("、")}` : "";
+	log(`增量部署 ${src} -> ${dest}（更新 dist、${API_INCREMENTAL_FILES.join("、")}${skipText}）`);
 }
 async function installAndReloadApi(name, dest, item, log) {
 	if (!fs.existsSync(path.join(dest, "package.json"))) throw new Error(`[deploy] ${dest} 缺少 package.json，无法 pnpm i`);
@@ -488,6 +498,115 @@ function markProjectFullDeployed(root, projectName) {
 	};
 	writeDeployStateFile(state);
 }
+/** 返回 ~/.zpc/deploy-state.json 中已记录的所有 projectName（去重、排序）。 */
+function listRecordedProjectNames() {
+	const state = readDeployStateFile();
+	return [...new Set(Object.values(state.projects).map((p) => p.projectName))].sort();
+}
+//#endregion
+//#region src/utils/check-state.ts
+/** 从 nginx 配置的 `owned-by: projectName/name` 头解析出 projectName。 */
+function nginxProjectName(text) {
+	const owned = parseNginxOwnedBy(text);
+	if (!owned) return null;
+	const idx = owned.indexOf("/");
+	return idx >= 0 ? owned.slice(0, idx) : owned;
+}
+/** 盘点部署痕迹（api/web 目录 + nginx 配置）与部署记录，合并成按系统分组的结果。 */
+function collectSystemChecks() {
+	const recorded = new Set(listRecordedProjectNames());
+	const apiByProject = /* @__PURE__ */ new Map();
+	for (const projectName of listNamedDirs(getApiRoot())) apiByProject.set(projectName, listNamedDirs(path.join(getApiRoot(), projectName)));
+	const webByProject = /* @__PURE__ */ new Map();
+	for (const projectName of listNamedDirs(getWebRoot())) webByProject.set(projectName, listNamedDirs(path.join(getWebRoot(), projectName)));
+	const nginxByProject = /* @__PURE__ */ new Map();
+	const unownedNginxConfs = [];
+	const nginxDir = getNginxDefaultD();
+	if (fs.existsSync(nginxDir)) for (const name of fs.readdirSync(nginxDir)) {
+		if (!name.endsWith(".conf")) continue;
+		const full = path.join(nginxDir, name);
+		let text = "";
+		try {
+			text = fs.readFileSync(full, "utf8");
+		} catch {}
+		const projectName = nginxProjectName(text);
+		if (projectName) {
+			const arr = nginxByProject.get(projectName) ?? [];
+			arr.push(full);
+			nginxByProject.set(projectName, arr);
+		} else unownedNginxConfs.push(full);
+	}
+	return {
+		systems: [.../* @__PURE__ */ new Set([
+			...recorded,
+			...apiByProject.keys(),
+			...webByProject.keys(),
+			...nginxByProject.keys()
+		])].sort().map((projectName) => ({
+			projectName,
+			recorded: recorded.has(projectName),
+			apiDirs: apiByProject.get(projectName) ?? [],
+			webDirs: webByProject.get(projectName) ?? [],
+			nginxConfs: nginxByProject.get(projectName) ?? []
+		})),
+		unownedNginxConfs
+	};
+}
+//#endregion
+//#region src/utils/log.ts
+function tagged(tag, message) {
+	return `${chalk.cyan(`[${tag}]`)} ${message}`;
+}
+/** 带命令前缀的彩色日志：info 默认、success 绿、warn 黄。 */
+function createLogger(tag) {
+	return {
+		info: (message) => {
+			console.log(tagged(tag, message));
+		},
+		success: (message) => {
+			console.log(tagged(tag, chalk.green(message)));
+		},
+		warn: (message) => {
+			console.log(tagged(tag, chalk.yellow(message)));
+		}
+	};
+}
+function logError(message) {
+	console.error(chalk.red(message));
+}
+//#endregion
+//#region src/commands/check.ts
+const log$3 = createLogger("check");
+function systemStatus(system) {
+	if (!system.recorded) return "未记录";
+	return system.apiDirs.length > 0 || system.webDirs.length > 0 || system.nginxConfs.length > 0 ? "已记录" : "记录但缺失";
+}
+function runCheck() {
+	const { systems, unownedNginxConfs } = collectSystemChecks();
+	if (systems.length === 0 && unownedNginxConfs.length === 0) {
+		log$3.info("未发现任何部署记录或部署痕迹");
+		return;
+	}
+	for (const system of systems) {
+		const status = systemStatus(system);
+		const head = `[${status}] ${system.projectName}`;
+		if (status === "已记录") log$3.info(head);
+		else log$3.warn(head);
+		if (!(system.apiDirs.length > 0 || system.webDirs.length > 0 || system.nginxConfs.length > 0)) continue;
+		if (system.apiDirs.length > 0) log$3.info(`  api: ${system.apiDirs.join(", ")}`);
+		if (system.webDirs.length > 0) log$3.info(`  web: ${system.webDirs.join(", ")}`);
+		if (system.nginxConfs.length > 0) log$3.info(`  nginx: ${system.nginxConfs.join(", ")}`);
+	}
+	if (unownedNginxConfs.length > 0) {
+		log$3.warn(`[未归属 nginx 配置] ${unownedNginxConfs.length} 个`);
+		for (const conf of unownedNginxConfs) log$3.warn(`  ${conf}`);
+	}
+}
+function createCheckCommand() {
+	return new Command("check").description("盘点部署目录与 nginx 配置，标注已记录 / 未记录 / 记录但缺失").action(async () => {
+		runCheck();
+	});
+}
 //#endregion
 //#region src/utils/dist-zip.ts
 const ZPC_GITIGNORE_HEADER = "# zpc files";
@@ -511,8 +630,8 @@ function ensureZpcGitignore(projectRoot) {
 	return true;
 }
 //#endregion
-//#region src/utils/incremental-mode.ts
-function isDirectoryNonEmpty(dir) {
+//#region src/utils/deploy-conflict.ts
+function isDirectoryNonEmpty$1(dir) {
 	if (!fs.existsSync(dir)) return false;
 	try {
 		return fs.readdirSync(dir).length > 0;
@@ -520,55 +639,80 @@ function isDirectoryNonEmpty(dir) {
 		return false;
 	}
 }
-/** 配置中 api 在部署根目录下已存在且非空的目录。 */
-function findNonemptyApiDeployDirs(config) {
+/** 收集「无 ~/.zpc 记录」时应提示用户的部署痕迹：api/web 目录非空、已存在/冲突的 nginx 配置。 */
+function collectDeployConflicts(config) {
 	const projectName = config.projectName;
-	if (!projectName) return [];
-	const found = [];
+	const conflicts = [];
+	if (!projectName) return conflicts;
 	for (const item of config.api ?? []) {
-		const deployDir = path.join(getApiRoot(), projectName, item.name);
-		if (isDirectoryNonEmpty(deployDir)) found.push(deployDir);
+		const dir = path.join(getApiRoot(), projectName, item.name);
+		if (isDirectoryNonEmpty$1(dir)) conflicts.push({
+			kind: "api-dir",
+			message: `api 部署目录非空: ${dir}`
+		});
 	}
-	return found;
-}
-/**
-* 全量 / 增量判定（pack 只读、deploy 读后写入）：
-* 1. ~/.zpc/deploy-state.json 有记录 → 增量
-* 2. 无记录但 api 部署目录非空 → 增量并提示
-* 3. 无记录但 zip 含增量标记 → 增量
-* 4. 否则全量
-*/
-function resolveIncrementalMode(projectRoot, config, options = {}) {
-	if (hasFullDeployRecord(projectRoot)) return { incremental: true };
-	const existingDeployDirs = findNonemptyApiDeployDirs(config);
-	if (existingDeployDirs.length > 0) return {
-		incremental: true,
-		existingDeployHint: `无 ~/.zpc 部署记录，但检测到 api 部署目录非空：${existingDeployDirs.map((dir) => path.normalize(dir)).join(", ")}。将按增量处理（api 保留 public，跳过 web）；若确需全量请清空部署目录并删除 deploy-state 中对应记录`
-	};
-	if (options.zipIsIncremental) return { incremental: true };
-	return { incremental: false };
-}
-//#endregion
-//#region src/utils/log.ts
-function tagged(tag, message) {
-	return `${chalk.cyan(`[${tag}]`)} ${message}`;
-}
-/** 带命令前缀的彩色日志：info 默认、success 绿、warn 黄。 */
-function createLogger(tag) {
-	return {
-		info: (message) => {
-			console.log(tagged(tag, message));
-		},
-		success: (message) => {
-			console.log(tagged(tag, chalk.green(message)));
-		},
-		warn: (message) => {
-			console.log(tagged(tag, chalk.yellow(message)));
+	for (const item of config.web ?? []) {
+		const dir = path.join(getWebRoot(), projectName, item.name);
+		if (isDirectoryNonEmpty$1(dir)) conflicts.push({
+			kind: "web-dir",
+			message: `web 部署目录非空: ${dir}`
+		});
+	}
+	const defaultD = getNginxDefaultD();
+	if (!fs.existsSync(defaultD)) return conflicts;
+	const proxies = (config.api ?? []).map((item) => item.proxy).filter((p) => !!p);
+	for (const name of fs.readdirSync(defaultD)) {
+		if (!name.endsWith(".conf")) continue;
+		const full = path.join(defaultD, name);
+		let text;
+		try {
+			text = fs.readFileSync(full, "utf8");
+		} catch {
+			continue;
 		}
-	};
-}
-function logError(message) {
-	console.error(chalk.red(message));
+		const owned = parseNginxOwnedBy(text);
+		if (owned?.startsWith(`${projectName}/`) || name.startsWith(`${projectName}-`)) {
+			conflicts.push({
+				kind: "nginx",
+				message: `已存在本项目 nginx 配置: ${full}`
+			});
+			continue;
+		}
+		for (const proxy of proxies) if (confDefinesProxy(text, proxy)) {
+			conflicts.push({
+				kind: "nginx",
+				message: `nginx 配置 ${full} 已定义 proxy ${nginxLocation(proxy)}（归属 ${owned ?? "未知"}）`
+			});
+			break;
+		}
+	}
+	return conflicts;
+}
+function isInteractive() {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** 交互询问部署方式；非 TTY 环境直接返回取消（默认）。 */
+async function promptDeployResolution() {
+	if (!isInteractive()) return "cancel";
+	const { select } = await import("@inquirer/prompts");
+	return await select({
+		message: "检测到已有部署痕迹（无 ~/.zpc 记录），请选择部署方式：",
+		choices: [
+			{
+				name: "清空目标文件夹并覆盖（全量，旧目录将备份）",
+				value: "full"
+			},
+			{
+				name: "使用增量部署（api 保留排除项，web 全量覆盖）",
+				value: "incremental"
+			},
+			{
+				name: "取消部署",
+				value: "cancel"
+			}
+		],
+		default: "cancel"
+	});
 }
 //#endregion
 //#region src/utils/zip.ts
@@ -707,15 +851,16 @@ async function deployKind(stagingDir, items, kind, destRoot, projectName, increm
 		if (!fs.existsSync(src)) throw new Error(`[deploy] 配置中有 ${kind}/${item.name}，但压缩包中没有对应目录`);
 		const dest = path.join(destRoot, projectName, item.name);
 		const pm2Name = `${projectName}-${item.name}`;
-		if (kind === "api" && incremental && fs.existsSync(dest)) deployApiIncremental(src, dest, log$2.info);
+		const apiItem = kind === "api" ? item : null;
+		if (apiItem && incremental && fs.existsSync(dest)) deployApiIncremental(src, dest, apiItem.excludeOnIncremental ?? [], log$2.info);
 		else {
-			if (kind === "api" && incremental && !fs.existsSync(dest)) log$2.warn(`${dest} 不存在，增量改为全量部署`);
+			if (apiItem && incremental && !fs.existsSync(dest)) log$2.warn(`${dest} 不存在，增量改为全量部署`);
 			deployDir(src, dest, log$2.info);
 		}
-		if (kind === "api" && !shouldSkipDeployRuntime()) await installAndReloadApi(pm2Name, dest, item, log$2.info);
+		if (apiItem && !shouldSkipDeployRuntime()) await installAndReloadApi(pm2Name, dest, apiItem, log$2.info);
 	}
 }
-async function runDeploy(dir, options) {
+async function runDeploy(dir, options, prompt = promptDeployResolution) {
 	const force = Boolean(options.force) || process.env.DEPLOY_FORCE === "1" || process.env.DEPLOY_FORCE === "true";
 	const projectDir = resolveProjectDir(dir);
 	const stagingDir = path.join(projectDir, ".deploy-staging");
@@ -739,16 +884,33 @@ async function runDeploy(dir, options) {
 		throw new Error(`[deploy] 解压失败: ${message}`);
 	}
 	const zipIsIncremental = fs.existsSync(path.join(stagingDir, INCREMENTAL_MARKER));
-	const deployMode = resolveIncrementalMode(projectDir, config, { zipIsIncremental });
-	const incremental = deployMode.incremental;
+	const hadRecord = hasFullDeployRecord(projectDir);
+	let incremental;
+	let resolvedFromConflicts = false;
+	if (hadRecord) incremental = true;
+	else {
+		const conflicts = collectDeployConflicts(config);
+		if (conflicts.length > 0) {
+			for (const conflict of conflicts) log$2.warn(conflict.message);
+			const choice = await prompt();
+			if (choice === "cancel") {
+				log$2.warn("已取消部署");
+				fs.rmSync(stagingDir, {
+					recursive: true,
+					force: true
+				});
+				return;
+			}
+			incremental = choice === "incremental";
+			resolvedFromConflicts = true;
+		} else incremental = zipIsIncremental;
+	}
 	try {
-		log$2.info(`模式: ${incremental ? "增量（api 保留 public，跳过 web）" : "全量"}`);
-		if (deployMode.existingDeployHint) log$2.warn(deployMode.existingDeployHint);
-		else if (!incremental) log$2.info("首次部署该项目，完成后将记录到 ~/.zpc/deploy-state.json");
+		log$2.info(`模式: ${incremental ? "增量（api 保留排除项，web 全量覆盖）" : "全量"}`);
+		if (!incremental && !hadRecord) log$2.info("首次部署该项目，完成后将记录到 ~/.zpc/deploy-state.json");
 		if (force) log$2.warn("已启用 --force（允许抢占冲突的 nginx proxy）");
 		await deployKind(stagingDir, config.api, "api", getApiRoot(), config.projectName, incremental);
-		if (!incremental) await deployKind(stagingDir, config.web, "web", getWebRoot(), config.projectName, false);
-		else if (config.web?.length) log$2.warn("增量模式跳过 web 部署");
+		await deployKind(stagingDir, config.web, "web", getWebRoot(), config.projectName, false);
 	} finally {
 		fs.rmSync(stagingDir, {
 			recursive: true,
@@ -762,11 +924,11 @@ async function runDeploy(dir, options) {
 	if (!hasFullDeployRecord(projectDir)) {
 		markProjectFullDeployed(projectDir, config.projectName);
 		if (!incremental) log$2.info("已记录全量部署状态到 ~/.zpc/deploy-state.json，下次 deploy 将默认增量");
-		else if (deployMode.existingDeployHint) log$2.info("已根据现有部署目录建立部署记录，下次 deploy 将默认增量");
+		else if (resolvedFromConflicts) log$2.info("已根据现有部署目录建立部署记录，下次 deploy 将默认增量");
 		else if (zipIsIncremental) log$2.info("已记录部署状态，下次 deploy 将默认增量");
 	}
 	const apiCount = config.api?.length ?? 0;
-	const webCount = incremental ? 0 : config.web?.length ?? 0;
+	const webCount = config.web?.length ?? 0;
 	const prefix = `${config.projectName}/<name>`;
 	log$2.success(`完成: api ${apiCount} 个 -> ${getApiRoot()}/${prefix}，web ${webCount} 个 -> ${getWebRoot()}/${prefix}`);
 }
@@ -808,12 +970,62 @@ function createInitCommand() {
 	});
 }
 //#endregion
+//#region src/utils/incremental-mode.ts
+function isDirectoryNonEmpty(dir) {
+	if (!fs.existsSync(dir)) return false;
+	try {
+		return fs.readdirSync(dir).length > 0;
+	} catch {
+		return false;
+	}
+}
+/** 配置中所有部署目录（api + web）里已存在且非空的目录。 */
+function findNonemptyDeployDirs(config) {
+	const projectName = config.projectName;
+	if (!projectName) return [];
+	const found = [];
+	for (const item of config.api ?? []) {
+		const deployDir = path.join(getApiRoot(), projectName, item.name);
+		if (isDirectoryNonEmpty(deployDir)) found.push(deployDir);
+	}
+	for (const item of config.web ?? []) {
+		const deployDir = path.join(getWebRoot(), projectName, item.name);
+		if (isDirectoryNonEmpty(deployDir)) found.push(deployDir);
+	}
+	return found;
+}
+/**
+* 全量 / 增量判定（pack 只读、deploy 读后写入）：
+* 1. ~/.zpc/deploy-state.json 有记录 → 增量
+* 2. 无记录但 api/web 部署目录非空 → 交由调用方决策（不直接判定）
+* 3. 无记录但 zip 含增量标记 → 增量
+* 4. 否则全量
+*/
+function resolveIncrementalMode(projectRoot, config, options = {}) {
+	if (hasFullDeployRecord(projectRoot)) return {
+		incremental: true,
+		existingDeployDirs: []
+	};
+	const existingDeployDirs = findNonemptyDeployDirs(config);
+	if (existingDeployDirs.length > 0) return {
+		incremental: false,
+		existingDeployDirs
+	};
+	if (options.zipIsIncremental) return {
+		incremental: true,
+		existingDeployDirs: []
+	};
+	return {
+		incremental: false,
+		existingDeployDirs: []
+	};
+}
+//#endregion
 //#region src/commands/pack.ts
 const log = createLogger("pack");
-function resolveProjects(root, config, incremental) {
+function resolveProjects(root, config) {
 	const projects = [];
-	const kinds = incremental ? ["api"] : ["api", "web"];
-	for (const kind of kinds) {
+	for (const kind of ["api", "web"]) {
 		const items = config[kind];
 		if (items == null) continue;
 		for (const item of items) {
@@ -829,7 +1041,7 @@ function resolveProjects(root, config, incremental) {
 			});
 		}
 	}
-	if (projects.length === 0) throw new Error(incremental ? "[pack] 增量打包需要配置中至少有一个 api 项目" : "[pack] 配置中没有 api / web 项目");
+	if (projects.length === 0) throw new Error("[pack] 配置中没有 api / web 项目");
 	return projects;
 }
 function resolveBuildEnv(project, config) {
@@ -895,7 +1107,8 @@ function stageApi(project, dest, incremental) {
 	copyRequiredFile(path.join(project.absPath, "package.json"), dest, "package.json");
 	copyRequiredFile(path.join(project.absPath, "bootstrap.js"), dest, "bootstrap.js");
 	if (incremental) {
-		log.warn(`api/${project.name} 增量：跳过 public`);
+		const excluded = project.excludeOnIncremental ?? [];
+		log.warn(excluded.length ? `api/${project.name} 增量：跳过 ${excluded.join("、")}` : `api/${project.name} 增量：不排除任何目录/文件`);
 		return;
 	}
 	const publicDir = path.join(project.absPath, "public");
@@ -926,14 +1139,17 @@ async function runPack(dir, options) {
 	const { file, config } = await loadConfig(projectRoot);
 	const zipPath = distZipPath(projectRoot, config.projectName);
 	const packMode = resolveIncrementalMode(projectRoot, config);
-	const incremental = packMode.incremental;
+	const incremental = packMode.incremental || packMode.existingDeployDirs.length > 0;
 	log.info(`项目目录: ${projectRoot}`);
 	log.info(`配置: ${file}`);
 	log.info(`项目: ${config.projectName}`);
-	log.info(`模式: ${incremental ? "增量（仅 api，不含 public）" : "全量"}`);
-	if (packMode.existingDeployHint) log.warn(packMode.existingDeployHint);
+	log.info(`模式: ${incremental ? "增量（api 不含排除项，web 全量）" : "全量"}`);
+	if (packMode.existingDeployDirs.length > 0) {
+		const listed = packMode.existingDeployDirs.map((dir) => path.normalize(dir)).join(", ");
+		log.warn(`无 ~/.zpc 部署记录，但检测到部署目录非空：${listed}。将按增量处理（api 保留排除项，web 全量覆盖）；若确需全量请清空部署目录并删除 deploy-state 中对应记录`);
+	}
 	if (options.concurrency !== void 0) log.info(`并行上限: ${options.concurrency}`);
-	const projects = resolveProjects(projectRoot, config, incremental);
+	const projects = resolveProjects(projectRoot, config);
 	await buildAll(projects, config, options);
 	stageDist(stagingDir, projectRoot, projects, incremental);
 	try {
@@ -964,7 +1180,7 @@ function createPackCommand() {
 //#endregion
 //#region src/utils/program.ts
 function createProgram() {
-	const program = new Command().name("zpc").description(description).version(version).showHelpAfterError().addCommand(createInitCommand()).addCommand(createPackCommand()).addCommand(createDeployCommand());
+	const program = new Command().name("zpc").description(description).version(version).showHelpAfterError().addCommand(createInitCommand()).addCommand(createPackCommand()).addCommand(createDeployCommand()).addCommand(createCheckCommand());
 	program.action(() => {
 		program.outputHelp();
 	});

package/dist/{config-BZc9pg7J.mjs → config-DzcldbBT.mjs}

@@ -13,6 +13,8 @@ const CONFIG_FORMATS = [
 	"cjs",
 	"json"
 ];
+/** 增量部署默认排除、不覆盖的目录/文件名。 */
+const DEFAULT_EXCLUDE_ON_INCREMENTAL = ["public"];
 function defineConfig(config) {
 	return config;
 }
@@ -66,9 +68,9 @@ function validateConfig(config, source) {
 function optionalAppList(value, kind, source) {
 	if (value == null) return [];
 	if (!Array.isArray(value)) throw new Error(`[config] ${source} 中 ${kind} 必须是数组`);
-	return value.map((item, index) => parseAppConfig(item, `${source} ${kind}[${index}]`));
+	return value.map((item, index) => parseAppConfig(item, kind, `${source} ${kind}[${index}]`));
 }
-function parseAppConfig(item, label) {
+function parseAppConfig(item, kind, label) {
 	if (!isPlainObject(item)) throw new Error(`[config] ${label} 必须是对象`);
 	if (typeof item.path !== "string" || item.path.trim() === "") throw new Error(`[config] ${label} 缺少 path`);
 	if (!isSafeName(item.name)) throw new Error(`[config] ${label} 缺少合法 name`);
@@ -81,8 +83,15 @@ function parseAppConfig(item, label) {
 		parsed.proxy = item.proxy;
 	}
 	if (item.buildEnv != null) parsed.buildEnv = parseEnvMap(item.buildEnv, `${label} buildEnv`);
-	if (item.env != null) parsed.env = parseEnvMap(item.env, `${label} env`);
-	return parsed;
+	if (kind === "web") return parsed;
+	const api = { ...parsed };
+	if (item.env != null) api.env = parseEnvMap(item.env, `${label} env`);
+	api.excludeOnIncremental = item.excludeOnIncremental != null ? parseExcludeOnIncremental(item.excludeOnIncremental, `${label} excludeOnIncremental`) : [...DEFAULT_EXCLUDE_ON_INCREMENTAL];
+	return api;
+}
+function parseExcludeOnIncremental(value, label) {
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !isSafeName(entry))) throw new Error(`[config] ${label} 必须是字符串数组（目录/文件名，不含路径分隔符）`);
+	return value;
 }
 function parseEnvMap(value, label) {
 	if (!isPlainObject(value)) throw new Error(`[config] ${label} 必须是对象`);

package/dist/index.d.mts

@@ -2,6 +2,7 @@
 declare const CONFIG_FORMATS: readonly ["ts", "mts", "cts", "js", "mjs", "cjs", "json"];
 type ConfigFormat = (typeof CONFIG_FORMATS)[number];
 type ZpcEnvMap = Record<string, string | number | boolean>;
+/** api / web 应用配置公共字段 */
 interface ZpcAppConfig {
   /** 相对项目根的源码目录 */
   path: string;
@@ -11,14 +12,21 @@ interface ZpcAppConfig {
   proxy?: string;
   /** 仅构建期注入 */
   buildEnv?: ZpcEnvMap;
+}
+/** api 应用配置（额外含运行时 env 与增量部署排除项） */
+interface ZpcApiConfig extends ZpcAppConfig {
   /** 仅运行时注入（pm2） */
   env?: ZpcEnvMap;
+  /** 增量部署时排除、不覆盖的目录/文件名；默认 ["public"] */
+  excludeOnIncremental?: string[];
 }
+/** web 应用配置（静态站点，仅构建期 buildEnv，无运行时 env） */
+interface ZpcWebConfig extends ZpcAppConfig {}
 interface ZpcConfig {
   projectName: string;
-  api?: ZpcAppConfig[];
-  web?: ZpcAppConfig[];
+  api?: ZpcApiConfig[];
+  web?: ZpcWebConfig[];
 }
 declare function defineConfig(config: ZpcConfig): ZpcConfig;
 //#endregion
-export { type ConfigFormat, type ZpcAppConfig, type ZpcConfig, type ZpcEnvMap, defineConfig };
+export { type ConfigFormat, type ZpcApiConfig, type ZpcAppConfig, type ZpcConfig, type ZpcEnvMap, type ZpcWebConfig, defineConfig };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { i as defineConfig } from "./config-BZc9pg7J.mjs";
+import { i as defineConfig } from "./config-DzcldbBT.mjs";
 export { defineConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhipu/zp-cli",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "内部单命令部署工具",
   "bin": {
     "zpc": "./dist/cli.mjs"
@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@commander-js/extra-typings": "^15.0.0",
+    "@inquirer/prompts": "^8.6.0",
     "@vue-tui/components": "^0.3.0",
     "@vue-tui/runtime": "^0.3.0",
     "chalk": "^6.0.0",
@@ -55,6 +56,21 @@
     "@alcalzone/ansi-tokenize": "0.3.0",
     "@babel/parser": "7.29.8",
     "@commander-js/extra-typings": "15.0.0",
+    "@inquirer/ansi": "2.0.7",
+    "@inquirer/checkbox": "5.2.2",
+    "@inquirer/confirm": "6.2.0",
+    "@inquirer/core": "12.0.0",
+    "@inquirer/editor": "5.3.0",
+    "@inquirer/expand": "5.1.2",
+    "@inquirer/external-editor": "3.0.4",
+    "@inquirer/figures": "2.0.8",
+    "@inquirer/input": "5.1.3",
+    "@inquirer/number": "4.2.0",
+    "@inquirer/password": "5.1.2",
+    "@inquirer/prompts": "8.6.0",
+    "@inquirer/rawlist": "5.3.2",
+    "@inquirer/search": "4.3.0",
+    "@inquirer/select": "5.2.2",
     "@vue-tui/components": "0.3.0",
     "@vue-tui/runtime": "0.3.0",
     "@vue/compiler-core": "3.5.41",
@@ -69,16 +85,24 @@
       "5.6.2",
       "6.0.0"
     ],
+    "chardet": "2.2.0",
     "cli-boxes": "3.0.0",
     "cli-truncate": "6.1.1",
+    "cli-width": "4.1.0",
     "commander": "15.0.0",
     "entities": "7.0.1",
     "environment": "1.1.0",
     "estree-walker": "2.0.2",
+    "fast-string-truncated-width": "3.0.3",
+    "fast-string-width": "3.0.2",
+    "fast-wrap-ansi": "0.2.2",
     "get-east-asian-width": "1.6.0",
+    "iconv-lite": "0.7.3",
     "is-fullwidth-code-point": "5.1.0",
     "jiti": "2.7.0",
+    "mute-stream": "3.0.0",
     "patch-console": "2.0.0",
+    "safer-buffer": "2.1.2",
     "signal-exit": "4.1.0",
     "slice-ansi": "9.0.0",
     "source-map-js": "1.2.1",

package/src/templates/zpc.config.schema.json

@@ -54,6 +54,15 @@
         "env": {
           "$ref": "#/definitions/envMap",
           "description": "仅运行时注入（pm2）"
+        },
+        "excludeOnIncremental": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "default": ["public"],
+          "description": "增量部署时排除、不覆盖的目录/文件名；仅 api 生效，默认 [\"public\"]"
         }
       }
     },