@ruan-cat/vercel-deploy-tool 0.12.2 → 1.1.0

package/src/commands/deploy.ts

@@ -0,0 +1,50 @@
+import { Command } from "commander";
+import { consola } from "consola";
+import { config as dotenvxConfig } from "@dotenvx/dotenvx";
+import { loadConfig } from "../config/loader";
+import { executeDeploymentWorkflow } from "../core/tasks";
+
+/**
+ * 创建 deploy 命令
+ * @description
+ * 部署项目到 Vercel
+ *
+ * @example
+ * ```bash
+ * vercel-deploy-tool deploy
+ * vdt deploy
+ * ```
+ */
+export function createDeployCommand(): Command {
+	const command = new Command("deploy");
+
+	command
+		.description("部署项目到 Vercel")
+		.option("--env-path <path>", "指定 dotenv 文件路径，用于覆盖默认环境变量")
+		.action(async (options) => {
+			try {
+				// 允许部署时显式指定 env 文件
+				if (options?.envPath) {
+					process.env.VERCEL_DEPLOY_TOOL_ENV_PATH = options.envPath;
+					dotenvxConfig({ path: options.envPath });
+					consola.info(`已从 --env-path 加载环境变量: ${options.envPath}`);
+				}
+
+				consola.start("开始加载配置...");
+
+				const config = await loadConfig();
+
+				consola.start("开始执行部署工作流...");
+
+				await executeDeploymentWorkflow(config);
+
+				consola.success("部署完成！");
+			} catch (error) {
+				consola.error("部署失败:");
+				consola.error(error);
+				process.exit(1);
+			}
+		});
+
+	return command;
+}

package/src/commands/init.ts

@@ -0,0 +1,92 @@
+import { Command } from "commander";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { consola } from "consola";
+
+// 获取当前模块的目录
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * 创建 init 命令
+ * @description
+ * 初始化配置文件，生成 vercel-deploy-tool.config.ts 模板
+ *
+ * @example
+ * ```bash
+ * vercel-deploy-tool init
+ * vercel-deploy-tool init --force
+ * ```
+ */
+export function createInitCommand(): Command {
+	const command = new Command("init");
+
+	command
+		.description("初始化配置文件")
+		.option("-f, --force", "强制覆盖已存在的文件")
+		.action((options) => {
+			const cwd = process.cwd();
+			const configFile = "vercel-deploy-tool.config.ts";
+			const targetPath = join(cwd, configFile);
+
+			// 检查文件是否已存在
+			if (existsSync(targetPath) && !options.force) {
+				consola.warn(`配置文件已存在: ${configFile}`);
+				consola.info("使用 --force 选项可以覆盖");
+				return;
+			}
+
+			// 读取模板文件
+			const templatePath = join(__dirname, "..", "templates", configFile);
+
+			if (!existsSync(templatePath)) {
+				consola.error(`模板文件不存在: ${templatePath}`);
+				consola.error("请确保 @ruan-cat/vercel-deploy-tool 包已正确安装");
+				process.exit(1);
+			}
+
+			const content = readFileSync(templatePath, "utf-8");
+
+			// 写入配置文件
+			writeFileSync(targetPath, content, "utf-8");
+			consola.success(`已创建配置文件: ${configFile}`);
+
+			// 更新 package.json
+			const pkgPath = join(cwd, "package.json");
+			if (existsSync(pkgPath)) {
+				try {
+					const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+					if (!pkg.scripts) pkg.scripts = {};
+
+					// 添加 deploy-vercel 脚本
+					pkg.scripts["deploy-vercel"] = "vercel-deploy-tool deploy";
+
+					writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+					consola.success('已添加脚本: "deploy-vercel"');
+				} catch (error) {
+					consola.warn("更新 package.json 失败:", error);
+				}
+			}
+
+			// 显示后续操作提示
+			consola.box(`🎉 初始化完成！
+
+创建的文件:
+  • ${configFile} - Vercel 部署配置文件
+
+添加的脚本:
+  • deploy-vercel: vercel-deploy-tool deploy
+
+下一步:
+  1. 编辑 ${configFile} 填写你的配置
+  2. 确保环境变量已设置:
+     - VERCEL_TOKEN
+     - VERCEL_ORG_ID
+     - VERCEL_PROJECT_ID
+  3. 运行部署:
+     pnpm run deploy-vercel`);
+		});
+
+	return command;
+}

package/src/config/define-config.ts

@@ -0,0 +1,20 @@
+import type { VercelDeployConfig } from "./schema";
+
+/**
+ * 定义配置的辅助函数
+ * @description
+ * 提供类型提示和智能补全
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@ruan-cat/vercel-deploy-tool";
+ *
+ * export default defineConfig({
+ *   vercelProjectName: "my-project",
+ *   // ...
+ * });
+ * ```
+ */
+export function defineConfig(config: VercelDeployConfig): VercelDeployConfig {
+	return config;
+}

package/src/config/loader.ts

@@ -0,0 +1,95 @@
+import { loadConfig as c12LoadConfig } from "c12";
+import { consola } from "consola";
+import { isUndefined } from "lodash-es";
+import { config as dotenvxConfig } from "@dotenvx/dotenvx";
+import { printFormat } from "@ruan-cat/utils";
+import type { VercelDeployConfig } from "./schema";
+
+/** 配置文件的文件名称 */
+export const CONFIG_NAME = "vercel-deploy-tool";
+
+/** 默认配置 */
+const DEFAULT_CONFIG: VercelDeployConfig = {
+	vercelProjectName: "",
+	vercelToken: "",
+	vercelOrgId: "",
+	vercelProjectId: "",
+	deployTargets: [],
+};
+
+/**
+ * 异步加载配置（工厂函数模式）
+ * @description
+ * 从约定俗成的配置处，获得用户配置文件。不会在模块导入时自动执行，避免 top-level await 引起的执行时警告。
+ *
+ * 环境变量优先级：
+ * 1) 命令行传入的 env-path（通过 VERCEL_DEPLOY_TOOL_ENV_PATH 或 deploy 命令参数注入）
+ * 2) Node 进程已有的 process.env
+ * 3) c12 默认加载的 .env* 文件
+ *
+ * @example
+ * ```ts
+ * const config = await loadConfig();
+ * ```
+ */
+export async function loadConfig(): Promise<VercelDeployConfig> {
+	consola.start("开始读取配置文件 vercel-deploy-tool.config.* ...");
+
+	// 兼容 CLI 的 --env-path，允许指定自定义 dotenv 文件
+	const envPath = process.env.VERCEL_DEPLOY_TOOL_ENV_PATH;
+	if (envPath) {
+		dotenvxConfig({ path: envPath });
+		consola.info(`已从 VERCEL_DEPLOY_TOOL_ENV_PATH 加载 dotenv: ${envPath}`);
+	}
+
+	let config: VercelDeployConfig | undefined;
+
+	const loaded = await c12LoadConfig<VercelDeployConfig>({
+		cwd: process.cwd(),
+		name: CONFIG_NAME,
+		dotenv: true,
+		defaults: DEFAULT_CONFIG,
+	});
+
+	config = loaded.config;
+
+	// 环境变量覆盖
+	const vercelOrgId = process.env.VERCEL_ORG_ID;
+	const vercelProjectId = process.env.VERCEL_PROJECT_ID;
+	const vercelToken = process.env.VERCEL_TOKEN;
+
+	if (!isUndefined(vercelOrgId)) {
+		config.vercelOrgId = vercelOrgId;
+	}
+	if (!isUndefined(vercelProjectId)) {
+		config.vercelProjectId = vercelProjectId;
+	}
+	if (!isUndefined(vercelToken)) {
+		config.vercelToken = vercelToken;
+	}
+
+	consola.success("配置加载完成");
+	consola.box(printFormat(config));
+
+	return config;
+}
+
+let cachedConfigPromise: Promise<VercelDeployConfig> | null = null;
+
+/**
+ * 导出配置获取函数（带缓存）
+ * @description
+ * 首次调用会触发加载，后续复用结果。避免 top-level await。
+ *
+ * @example
+ * ```ts
+ * import { getConfig } from "@ruan-cat/vercel-deploy-tool";
+ * const config = await getConfig();
+ * ```
+ */
+export async function getConfig(): Promise<VercelDeployConfig> {
+	if (!cachedConfigPromise) {
+		cachedConfigPromise = loadConfig();
+	}
+	return cachedConfigPromise;
+}

package/src/config/schema.ts

@@ -0,0 +1,108 @@
+/**
+ * @description
+ * 从 drizzle-kit 学的类型验证技巧
+ */
+type Verify<T, U extends T> = U;
+
+/** 部署目标类型 */
+export type DeployTargetType = "static" | "userCommands";
+
+/** 基础配置 */
+export interface DeployTargetBase {
+	/** 部署目标分类 */
+	type: DeployTargetType;
+
+	/** 目标的工作目录 */
+	targetCWD: `./${string}`;
+
+	/** 生产环境的访问url */
+	url: string[];
+
+	/**
+	 * 是否需要vercel的build命令？
+	 * @description
+	 * 某些情况下用户已经能够准备好vercel的目录结构，不需要依赖于 `vercel build` 命令完成目录构建
+	 *
+	 * 故设计此配置允许用户直接跳过 `vercel build` 命令
+	 * @default true
+	 */
+	isNeedVercelBuild?: boolean;
+}
+
+/**
+ * 带有用户命令的配置
+ */
+export interface DeployTargetWithUserCommands extends DeployTargetBase {
+	type: Verify<DeployTargetType, "userCommands">;
+
+	/**
+	 * 用户命令
+	 * @description
+	 * 实际部署的构建命令，通常是真实参与部署的命令
+	 *
+	 * @example ["pnpm -C=./packages/docs-01-star build:docs"]
+	 * @example ["pnpm -C=./packages/monorepo-5 build:docs"]
+	 */
+	userCommands: string[];
+
+	/**
+	 * 部署输出路径
+	 *
+	 * @version 2
+	 * @description
+	 * 填写打包目录的路径即可。不包含glob语法。
+	 * @example "docs/.vitepress/dist"
+	 * @example "src/.vuepress/dist"
+	 */
+	outputDirectory: string;
+
+	/**
+	 * 是否移动打包目录至特定的vercel部署目录？
+	 * @description
+	 * 执行完用户命令后，一般会执行文件移动命令，以便于部署
+	 *
+	 * 该配置用于控制是否执行文件移动命令
+	 *
+	 * @default true
+	 */
+	isCopyDist?: boolean;
+}
+
+/** 部署目标的具体项目配置 */
+export type DeployTarget = DeployTargetBase | DeployTargetWithUserCommands;
+
+/** Vercel部署工具的配置 */
+export interface VercelDeployConfig {
+	/** 项目名称 */
+	vercelProjectName: string;
+
+	/** 用户token */
+	vercelToken: string;
+
+	/** 用户组织id */
+	vercelOrgId: string;
+
+	/** 用户项目id */
+	vercelProjectId: string;
+
+	/**
+	 * 用户提供的 vercel.json 配置文件
+	 * @description
+	 * 有时候用户需要提供自己的一套配置文件
+	 *
+	 * 这里提供配置路径
+	 */
+	vercelJsonPath?: string;
+
+	/** 在build命令阶段后执行的用户命令 */
+	afterBuildTasks?: string[];
+
+	/**
+	 * 部署目标
+	 * @description
+	 * 考虑到可能要部署一揽子的项目，所以这里使用数组
+	 *
+	 * 考虑monorepo的情况
+	 */
+	deployTargets: DeployTarget[];
+}

package/src/core/executor.ts

@@ -0,0 +1,50 @@
+import task from "tasuku";
+
+export { task };
+export type { TaskFunction } from "tasuku";
+
+/**
+ * 并行执行任务组
+ * @description
+ * 封装 tasuku 的 task.group，提供更简洁的 API
+ *
+ * @example
+ * ```ts
+ * await executeParallel("Link 项目", [
+ *   { name: "Link target 1", fn: async () => {...} },
+ *   { name: "Link target 2", fn: async () => {...} }
+ * ]);
+ * ```
+ */
+export async function executeParallel<T>(
+	title: string,
+	tasks: Array<{ name: string; fn: () => Promise<T> }>,
+	options?: { concurrency?: number },
+) {
+	return await task.group((task) => tasks.map((t) => task(t.name, t.fn)), options);
+}
+
+/**
+ * 顺序执行任务组
+ * @description
+ * 逐个执行任务，每个任务完成后再执行下一个
+ *
+ * @example
+ * ```ts
+ * await executeSequential("执行构建任务", [
+ *   { name: "Task 1", fn: async () => {...} },
+ *   { name: "Task 2", fn: async () => {...} }
+ * ]);
+ * ```
+ */
+export async function executeSequential<T = any>(
+	title: string,
+	tasks: Array<{ name: string; fn: () => Promise<T> }>,
+): Promise<T[]> {
+	const results: T[] = [];
+	for (const t of tasks) {
+		const result = await task(t.name, t.fn);
+		results.push(result.result);
+	}
+	return results;
+}

package/src/core/tasks/after-build.ts

@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+import { consola } from "consola";
+import { isUndefined, isEmpty } from "lodash-es";
+import type { VercelDeployConfig } from "../../config/schema";
+
+/**
+ * 创建 AfterBuild 任务列表
+ * @description
+ * 在 build 命令阶段后执行的用户命令
+ */
+export function createAfterBuildTasks(config: VercelDeployConfig) {
+	const afterBuildTasks = config.afterBuildTasks;
+
+	if (isUndefined(afterBuildTasks) || isEmpty(afterBuildTasks)) {
+		return [
+			{
+				name: "AfterBuild: 无任务",
+				fn: async (): Promise<string | undefined> => {
+					consola.warn("当前没有有意义的 afterBuildTasks 任务配置");
+					return undefined;
+				},
+			},
+		];
+	}
+
+	return afterBuildTasks.map((command) => ({
+		name: `AfterBuild: ${command}`,
+		fn: async (): Promise<string | undefined> => {
+			consola.start(`开始 afterBuild 任务: ${command}`);
+
+			const result = spawnSync(command, [], {
+				encoding: "utf-8",
+				stdio: "inherit",
+				shell: true,
+			});
+
+			if (result.error) {
+				consola.error(`afterBuild 任务失败: ${command}`);
+				throw result.error;
+			}
+
+			consola.success(`完成 afterBuild 任务: ${command}`);
+			return result.stdout;
+		},
+	}));
+}

package/src/core/tasks/alias.ts

@@ -0,0 +1,37 @@
+import { spawnSync } from "node:child_process";
+import { concat } from "lodash-es";
+import { consola } from "consola";
+import type { VercelDeployConfig } from "../../config/schema";
+import { createVercelSpawnOptions, getVercelTokenArg, getVercelScopeArg } from "../vercel";
+
+/**
+ * 创建 Alias 任务
+ * @description
+ * 旨在于封装类似于这样的命令：
+ *
+ * vc alias set deployment-url.vercel.app custom-domain.com -t TOKEN --scope ORG_ID
+ *
+ * @see https://vercel.community/t/deployment-via-gitlab-ci-to-dev-domain/523/3
+ */
+export function createAliasTask(config: VercelDeployConfig, vercelUrl: string, userUrl: string) {
+	return {
+		name: `Alias: ${userUrl}`,
+		fn: async () => {
+			const args = concat(["alias", "set", vercelUrl, userUrl], getVercelTokenArg(config), getVercelScopeArg(config));
+
+			consola.start(`开始别名任务: ${userUrl}`);
+
+			const result = spawnSync("vercel", args, createVercelSpawnOptions());
+
+			if (result.error) {
+				consola.error(`别名任务失败: ${userUrl}`);
+				throw result.error;
+			}
+
+			consola.success(`完成别名任务，可用的别名地址为:`);
+			consola.box(`https://${userUrl}`);
+
+			return result.stdout;
+		},
+	};
+}

package/src/core/tasks/build.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { concat } from "lodash-es";
+import { consola } from "consola";
+import type { VercelDeployConfig, DeployTarget } from "../../config/schema";
+import { createVercelSpawnOptions, getVercelTokenArg, getVercelLocalConfigArg, getTargetCWDArg } from "../vercel";
+
+/**
+ * 创建 Build 任务
+ * @description
+ * 旨在于封装类似于这样的命令：
+ *
+ * vc build --yes --prod --cwd=./packages/docs -A ./vercel.null.json -t TOKEN
+ */
+export function createBuildTask(config: VercelDeployConfig, target: DeployTarget) {
+	return {
+		name: `Build: ${target.targetCWD}`,
+		fn: async () => {
+			const targetPath = resolve(target.targetCWD);
+
+			if (!fs.existsSync(targetPath)) {
+				const err = new Error(`目标目录不存在，请先构建: ${target.targetCWD}`);
+				consola.error(err.message);
+				throw err;
+			}
+
+			const args = concat(
+				["build"],
+				["--yes"],
+				["--prod"],
+				getTargetCWDArg(target),
+				getVercelLocalConfigArg(),
+				getVercelTokenArg(config),
+			);
+
+			consola.start(`开始 build 任务: ${target.targetCWD}`);
+
+			const result = spawnSync("vercel", args, createVercelSpawnOptions());
+
+			if (result.error) {
+				consola.error(`build 任务失败: ${target.targetCWD}`);
+				throw result.error;
+			}
+
+			consola.success(`完成 build 任务: ${target.targetCWD}`);
+			return result.stdout;
+		},
+	};
+}

package/src/core/tasks/copy-dist.ts

@@ -0,0 +1,59 @@
+import { resolve } from "node:path";
+import { rmSync, mkdirSync, cpSync } from "node:fs";
+import { consola } from "consola";
+import type { DeployTargetWithUserCommands } from "../../config/schema";
+import { VERCEL_OUTPUT_STATIC } from "../../utils/vercel-null-config";
+
+/**
+ * 创建文件复制任务列表
+ * @description
+ * 针对单个部署目标，生成一系列移动目录的任务：
+ * 1. 删除目录
+ * 2. 新建目录
+ * 3. 复制粘贴
+ */
+export function createCopyDistTasks(target: DeployTargetWithUserCommands) {
+	const targetCWD = target.targetCWD;
+	const outputDirectory = target.outputDirectory;
+
+	/**
+	 * 路径拼接工具
+	 * @private
+	 * 仅考虑为内部使用，不是通用工具
+	 */
+	function joinPath<T extends string>(dir: T) {
+		return resolve(process.cwd(), targetCWD, dir);
+	}
+
+	const pathVercelOutputStatic = joinPath(VERCEL_OUTPUT_STATIC);
+	const pathOutputDirectory = joinPath(outputDirectory);
+
+	return [
+		{
+			name: `删除目录: ${pathVercelOutputStatic}`,
+			fn: async () => {
+				consola.start(`开始删除文件任务: ${pathVercelOutputStatic}`);
+				rmSync(pathVercelOutputStatic, { recursive: true, force: true });
+				consola.success(`删除该路径的文件: ${pathVercelOutputStatic}`);
+			},
+		},
+		{
+			name: `创建目录: ${pathVercelOutputStatic}`,
+			fn: async () => {
+				consola.start(`开始创建文件夹任务: ${pathVercelOutputStatic}`);
+				mkdirSync(pathVercelOutputStatic, { recursive: true });
+				consola.success(`创建的新目录为: ${pathVercelOutputStatic}`);
+			},
+		},
+		{
+			name: `复制文件: ${pathOutputDirectory} -> ${pathVercelOutputStatic}`,
+			fn: async () => {
+				consola.start(`开始文件复制任务`);
+				consola.info(`从 ${pathOutputDirectory} 开始`);
+				consola.info(`复制到 ${pathVercelOutputStatic} 内`);
+				cpSync(pathOutputDirectory, pathVercelOutputStatic, { recursive: true });
+				consola.success(`完成文件复制任务`);
+			},
+		},
+	];
+}

package/src/core/tasks/deploy.ts

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { concat } from "lodash-es";
+import { consola } from "consola";
+import type { VercelDeployConfig, DeployTarget } from "../../config/schema";
+import { createVercelSpawnOptions, getVercelTokenArg, getTargetCWDArg } from "../vercel";
+
+/**
+ * 创建 Deploy 任务
+ * @description
+ * 旨在于封装类似于这样的命令：
+ *
+ * vc deploy --yes --prebuilt --prod --cwd=./packages/docs -t TOKEN
+ */
+export function createDeployTask(config: VercelDeployConfig, target: DeployTarget) {
+	return {
+		name: `Deploy: ${target.targetCWD}`,
+		fn: async () => {
+			const targetPath = resolve(target.targetCWD);
+
+			if (!fs.existsSync(targetPath)) {
+				const err = new Error(`目标目录不存在，请先构建: ${target.targetCWD}`);
+				consola.error(err.message);
+				throw err;
+			}
+
+			const args = concat(
+				["deploy"],
+				["--yes"],
+				["--prebuilt"],
+				["--prod"],
+				getTargetCWDArg(target),
+				getVercelTokenArg(config),
+			);
+
+			consola.start(`开始部署任务: ${target.targetCWD}`);
+
+			const result = spawnSync("vercel", args, createVercelSpawnOptions("pipe"));
+
+			if (result.error) {
+				consola.error(`部署失败了: ${target.targetCWD}`);
+				consola.error(result.error);
+				throw result.error;
+			}
+
+			const vercelUrl = result.stdout.toString().trim();
+			consola.success(`完成部署任务，生成的url为:`);
+			consola.box(vercelUrl);
+
+			return vercelUrl;
+		},
+	};
+}