@lazycatcloud/lzc-cli 1.3.17 → 2.0.0-pre.1

package/lib/app/lpk_build.js

@@ -1,25 +1,17 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import zlib from 'node:zlib';
 import logger from 'loglevel';
-import {
-	loadFromYaml,
-	isDirExist,
-	isDirSync,
-	isFileExist,
-	dumpToYaml,
-	envTemplateFile,
-	isValidPackageName,
-	tarContentDir,
-	isPngWithFile,
-	isMacOs,
-	isWindows,
-	isLinux,
-} from '../utils.js';
+import { isDirExist, isDirSync, isFileExist, dumpToYaml, envTemplateFile, isValidPackageName, tarContentDir, isPngWithFile, isMacOs, isWindows, isLinux } from '../utils.js';
 import spawn from 'cross-spawn';
-import { LpkManifest } from './lpk_create.js';
+import { loadEffectiveManifest, splitManifestAndPackageInfo, findManifestStaticFields, PACKAGE_FILE_NAME } from '../package_info.js';
+import { buildVarsFromEnvEntries, normalizeBuildEnvEntries, preprocessManifestFile } from './manifest_build.js';
 import archiver from 'archiver';
 import yaml from 'js-yaml';
+import { buildConfiguredImagesToTempDir } from './lpk_build_images.js';
+import { pipeline } from 'node:stream/promises';
 import { t } from '../i18n/index.js';
+import mergeWith from 'lodash.mergewith';
 
 async function archiveFolderTo(appDir, out, format = 'zip') {
 	return new Promise(async (resolve, reject) => {
@@ -46,6 +38,134 @@ async function archiveFolderTo(appDir, out, format = 'zip') {
 	});
 }
 
+async function gzipFileTo(inputPath, outputPath) {
+	const source = fs.createReadStream(inputPath);
+	const gzip = zlib.createGzip({ mtime: 0 });
+	const target = fs.createWriteStream(outputPath);
+	await pipeline(source, gzip, target);
+}
+
+function rewriteManifestEmbeddedImages(manifest, resolvedImageByAlias) {
+	const EMBED_PREFIX = 'embed:';
+	if (!resolvedImageByAlias || typeof resolvedImageByAlias !== 'object') {
+		return manifest;
+	}
+
+	const parseAlias = (rawValue) => {
+		const trimmed = String(rawValue ?? '').trim();
+		if (!trimmed.startsWith(EMBED_PREFIX)) {
+			return '';
+		}
+		const rest = trimmed.slice(EMBED_PREFIX.length).trim();
+		if (!rest) {
+			throw new Error(`Invalid image reference "${rawValue}", alias is required after "${EMBED_PREFIX}"`);
+		}
+		const at = rest.indexOf('@');
+		const alias = (at >= 0 ? rest.slice(0, at) : rest).trim();
+		if (!alias) {
+			throw new Error(`Invalid image reference "${rawValue}", alias is required after "${EMBED_PREFIX}"`);
+		}
+		return alias;
+	};
+
+	const walk = (value) => {
+		if (typeof value === 'string') {
+			const alias = parseAlias(value);
+			if (alias) {
+				const resolved = resolvedImageByAlias[alias];
+				if (!resolved) {
+					throw new Error(`Cannot resolve embedded image alias "${alias}" to final image reference`);
+				}
+				return `${EMBED_PREFIX}${alias}@${resolved}`;
+			}
+			return value;
+		}
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index += 1) {
+				value[index] = walk(value[index]);
+			}
+			return value;
+		}
+		if (value && typeof value === 'object') {
+			for (const [key, item] of Object.entries(value)) {
+				value[key] = walk(item);
+			}
+			return value;
+		}
+		return value;
+	};
+
+	return walk(manifest);
+}
+
+function rewriteManifestEmbeddedImagesInText(rawText, resolvedImageByAlias) {
+	if (!resolvedImageByAlias || typeof resolvedImageByAlias !== 'object') {
+		return rawText;
+	}
+	let output = String(rawText ?? '');
+	for (const [alias, resolved] of Object.entries(resolvedImageByAlias)) {
+		if (!alias || !resolved) {
+			continue;
+		}
+		const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		const pattern = new RegExp(`embed:${escapedAlias}(?!@sha256:[0-9a-fA-F]{64})`, 'g');
+		output = output.replace(pattern, `embed:${alias}@${resolved}`);
+	}
+	return output;
+}
+
+function rewriteTopLevelManifestScalarInText(rawText, key, value) {
+	const normalizedValue = String(value ?? '').trim();
+	if (!normalizedValue) {
+		return rawText;
+	}
+	const lines = String(rawText ?? '').split('\n');
+	const pattern = new RegExp(`^(\\s*)${key}:(\\s*)([^#]*?)(\\s*(#.*))?$`);
+	let replaced = false;
+	const output = lines.map((line) => {
+		if (replaced) {
+			return line;
+		}
+		const match = line.match(pattern);
+		if (!match) {
+			return line;
+		}
+		replaced = true;
+		const indent = match[1] ?? '';
+		const spacing = match[2] ?? ' ';
+		const comment = match[4] ?? '';
+		return `${indent}${key}:${spacing}${normalizedValue}${comment}`;
+	});
+	return output.join('\n');
+}
+
+function removeTopLevelManifestFieldsInText(rawText, keys) {
+	const wanted = new Set((keys ?? []).map((key) => String(key ?? '').trim()).filter(Boolean));
+	if (wanted.size === 0) {
+		return String(rawText ?? '');
+	}
+	const lines = String(rawText ?? '').split('\n');
+	const output = [];
+	let skipping = false;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		const indent = line.length - line.trimStart().length;
+		if (indent === 0 && !trimmed.startsWith('#')) {
+			const match = trimmed.match(/^([A-Za-z0-9_]+):/);
+			if (match && wanted.has(match[1])) {
+				skipping = true;
+				continue;
+			}
+			skipping = false;
+		}
+		if (!skipping) {
+			output.push(line);
+		}
+	}
+	return output.join('\n');
+}
+
 async function fetchIconTo(options, cwd, destDir) {
 	if (!options['icon']) {
 		logger.warn(t('lzc_cli.lib.app.lpk_build.fetch_icon_to_icon_empty_fail', '图标icon 没有指定'));
@@ -68,7 +188,12 @@ async function fetchIconTo(options, cwd, destDir) {
 	}
 
 	if (!isPngWithFile(iconPath)) {
-		logger.warn(t('lzc_cli.lib.app.lpk_build.fetch_icon_to_icon_not_is_png_fail', `图标icon {{ iconPath }} 验证失败(不是一个png格式)`, { iconPath, interpolation: { escapeValue: false } }));
+		logger.warn(
+			t('lzc_cli.lib.app.lpk_build.fetch_icon_to_icon_not_is_png_fail', `图标icon {{ iconPath }} 验证失败(不是一个png格式)`, {
+				iconPath,
+				interpolation: { escapeValue: false },
+			}),
+		);
 		return;
 	} else {
 		logger.debug(t('lzc_cli.lib.app.lpk_build.fetch_icon_to_icon_is_png', `图标icon {{ iconPath }} 验证成功(png格式)`, { iconPath, interpolation: { escapeValue: false } }));
@@ -97,7 +222,12 @@ async function fetchLzcDeployParamTo(options, cwd, destDir) {
 	}
 
 	if (!isFileExist(deployParamsPath)) {
-		logger.warn(t('lzc_cli.lib.app.lpk_build.fetch_lzc_deploy_param_to_not_exist', `deploy_params {{ deployParamsPath }} 不存在`, { deployParamsPath, interpolation: { escapeValue: false } }));
+		logger.warn(
+			t('lzc_cli.lib.app.lpk_build.fetch_lzc_deploy_param_to_not_exist', `deploy_params {{ deployParamsPath }} 不存在`, {
+				deployParamsPath,
+				interpolation: { escapeValue: false },
+			}),
+		);
 		return;
 	}
 
@@ -151,15 +281,126 @@ function convenientEnv() {
 	);
 }
 
+function formatBytes(bytes) {
+	const value = Number(bytes ?? 0);
+	if (!Number.isFinite(value) || value <= 0) {
+		return '0 B';
+	}
+	const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+	let size = value;
+	let unitIndex = 0;
+	while (size >= 1024 && unitIndex < units.length - 1) {
+		size /= 1024;
+		unitIndex += 1;
+	}
+	const digits = unitIndex === 0 ? 0 : 2;
+	return `${size.toFixed(digits)} ${units[unitIndex]}`;
+}
+
+function mergeBuildOptions(baseOptions, topOptions) {
+	return mergeWith({}, baseOptions ?? {}, topOptions ?? {}, (objValue, srcValue) => {
+		if (Array.isArray(srcValue)) {
+			return srcValue;
+		}
+		return undefined;
+	});
+}
+
+function applyPkgIdSuffix(packageId, suffix) {
+	const normalizedPackageId = String(packageId ?? '').trim();
+	const normalizedSuffix = String(suffix ?? '').trim();
+	if (!normalizedSuffix) {
+		return normalizedPackageId;
+	}
+	if (!normalizedPackageId) {
+		throw new Error('package is empty, cannot apply pkg_id_suffix');
+	}
+	return `${normalizedPackageId}.${normalizedSuffix}`;
+}
+
+export function validatePackageFileForArchiveFormat(hasPackageFile, archiveFormat) {
+	const format = String(archiveFormat ?? '')
+		.trim()
+		.toLowerCase();
+	if (format === 'tar' && !hasPackageFile) {
+		throw new Error('package.yml is required for tar-based LPK v2 packages');
+	}
+}
+
+function hasBuildEnvEntries(envEntries) {
+	return Array.isArray(envEntries) && envEntries.length > 0;
+}
+
+export function shouldUseV2PackageLayout({ forceV2 = false, hasPackageFile = false, hasImagesConfig = false, buildEnvEntries = [] } = {}) {
+	return !!forceV2 || !!hasPackageFile || !!hasImagesConfig || hasBuildEnvEntries(buildEnvEntries);
+}
+
+function logDeprecatedStaticFieldWarning(manifestPath, fields) {
+	if (!Array.isArray(fields) || fields.length === 0) {
+		return;
+	}
+	logger.warn(`Building LPK v2. Static package fields in ${manifestPath} are deprecated and will be written to package.yml: ${fields.join(', ')}`);
+}
+
+function normalizeBuildOptions(options) {
+	const normalized = { ...(options ?? {}) };
+	if (Object.prototype.hasOwnProperty.call(normalized, 'envs')) {
+		normalized['envs'] = normalizeBuildEnvEntries(normalized['envs']);
+	}
+	return normalized;
+}
+
+function loadYamlIfExists(filePath) {
+	if (!filePath || !isFileExist(filePath)) {
+		return {};
+	}
+	return yaml.load(fs.readFileSync(filePath, 'utf8')) ?? {};
+}
+
+async function loadTemplatedYamlIfExists(filePath, env) {
+	if (!filePath || !isFileExist(filePath)) {
+		return {};
+	}
+	return yaml.load(await envTemplateFile(filePath, env)) ?? {};
+}
+
+function isDevBuildConfigName(buildConfigFile) {
+	return path.basename(String(buildConfigFile ?? '').trim()) === 'lzc-build.dev.yml';
+}
+
+function resolveParentBuildConfigPath(optionsFilePath) {
+	if (!isDevBuildConfigName(optionsFilePath)) {
+		return '';
+	}
+	const parentPath = path.join(path.dirname(optionsFilePath), 'lzc-build.yml');
+	if (!isFileExist(parentPath)) {
+		throw new Error(`Build config file not found: ${parentPath}`);
+	}
+	return parentPath;
+}
+
+function detectBuildProfile(buildConfigFile) {
+	return isDevBuildConfigName(buildConfigFile) ? 'dev' : 'release';
+}
+
 export class LpkBuild {
-	constructor(cwd, buildConfigFile) {
+	constructor(cwd, buildConfigFile, options = {}) {
 		this.pwd = cwd ?? process.cwd();
+		this.forceV2 = !!options.forceV2;
 
 		this.optionsFilePath = path.join(this.pwd, buildConfigFile);
-		this.options = loadFromYaml(this.optionsFilePath);
+		this.parentOptionsFilePath = resolveParentBuildConfigPath(this.optionsFilePath);
+		this.options = normalizeBuildOptions(mergeBuildOptions(loadYamlIfExists(this.parentOptionsFilePath), loadYamlIfExists(this.optionsFilePath)));
+		this.buildProfile = detectBuildProfile(this.optionsFilePath);
 
 		this.manifestFilePath = this.options['manifest'] ? path.join(this.pwd, this.options['manifest']) : path.join(this.pwd, 'lzc-manifest.yml');
+		this.packageFilePath = path.join(this.pwd, PACKAGE_FILE_NAME);
 		this.manifest = null;
+		this.sourceManifest = null;
+		this.packageInfo = null;
+		this.hasPackageFile = false;
+		this.buildVars = null;
+		this.preprocessedManifestText = '';
 
 		this.beforeBuildPackageFn = [];
 		this.beforeDumpYamlFn = [];
@@ -169,9 +410,25 @@ export class LpkBuild {
 
 	// init 时替换 lzc-build.yml 中的模板字段
 	async init() {
-		const manifest = await this.getManifest();
+		const sourceLoaded = loadEffectiveManifest(this.manifestFilePath, {
+			packageFilePath: this.packageFilePath,
+		});
 		const primitive = convenientEnv();
-		this.options = yaml.load(await envTemplateFile(this.optionsFilePath, Object.assign({}, primitive, manifest)));
+		const baseTemplateEnv = Object.assign({}, primitive, sourceLoaded.manifest);
+		const firstParentOptions = await loadTemplatedYamlIfExists(this.parentOptionsFilePath, baseTemplateEnv);
+		const firstTopOptions = await loadTemplatedYamlIfExists(this.optionsFilePath, baseTemplateEnv);
+		const firstOptions = normalizeBuildOptions(mergeBuildOptions(firstParentOptions, firstTopOptions));
+		const buildVars = buildVarsFromEnvEntries(firstOptions['envs']);
+		const finalTemplateEnv = Object.assign({}, baseTemplateEnv, buildVars);
+		const parentOptions = await loadTemplatedYamlIfExists(this.parentOptionsFilePath, finalTemplateEnv);
+		const topOptions = await loadTemplatedYamlIfExists(this.optionsFilePath, finalTemplateEnv);
+		this.options = normalizeBuildOptions(mergeBuildOptions(parentOptions, topOptions));
+		this.manifest = null;
+		this.sourceManifest = null;
+		this.packageInfo = null;
+		this.hasPackageFile = false;
+		this.buildVars = buildVarsFromEnvEntries(this.options['envs']);
+		this.preprocessedManifestText = '';
 		return this;
 	}
 
@@ -197,17 +454,40 @@ export class LpkBuild {
 		this.beforeDumpLpkFn.push(fn);
 	}
 
+	getBuildVars() {
+		if (!this.buildVars) {
+			this.buildVars = buildVarsFromEnvEntries(this.options['envs']);
+		}
+		return this.buildVars;
+	}
+
 	async getManifest() {
 		if (this.manifest) {
 			return this.manifest;
 		}
 
-		let lpkM = new LpkManifest();
-		await lpkM.init(this.manifestFilePath);
-		this.manifest = lpkM.manifest;
-		// manifest使用 text/template模板时，标记为异常manifest
-		// 创建lpk时，直接将源文件拷入 lpk
-		this.excpManifest = lpkM.excpManifest;
+		this.preprocessedManifestText = preprocessManifestFile(this.manifestFilePath, {
+			profile: this.buildProfile,
+			envs: this.getBuildVars(),
+		});
+
+		const loaded = loadEffectiveManifest(this.manifestFilePath, {
+			manifestText: this.preprocessedManifestText,
+			packageFilePath: this.packageFilePath,
+		});
+		this.excpManifest = loaded.excpManifest;
+		this.sourceManifest = loaded.sourceManifest;
+		this.packageInfo = loaded.packageInfo;
+		this.hasPackageFile = loaded.hasPackageFile;
+		this.manifest = loaded.manifest;
+
+		const packageWithSuffix = applyPkgIdSuffix(this.manifest['package'], this.options['pkg_id_suffix']);
+		if (packageWithSuffix !== this.manifest['package']) {
+			this.manifest = { ...this.manifest, package: packageWithSuffix };
+			if (this.hasPackageFile) {
+				this.packageInfo = { ...(this.packageInfo ?? {}), package: packageWithSuffix };
+			}
+		}
 
 		if (!isValidPackageName(this.manifest['package'])) {
 			throw t('lzc_cli.lib.app.lpk_build.get_manifest_package_name_fail', `{{ package }} 含有非法字符，请使用正确的包名格式(java的包名格式)，如：cloud.lazycat.apps.video`, {
@@ -215,7 +495,7 @@ export class LpkBuild {
 			});
 		}
 
-		if (!this.manifest['application']['subdomain']) {
+		if (!this.manifest?.application?.subdomain) {
 			throw t('lzc_cli.lib.app.lpk_build.get_manifest_subdomain_empty', `application 模块下的 subdomain 字段不能为空`);
 		}
 
@@ -223,6 +503,8 @@ export class LpkBuild {
 	}
 
 	async exec() {
+		await this.getManifest();
+
 		if (this.beforeBuildPackageFn.length > 0) {
 			this.options = await this.beforeBuildPackageFn.reduce(async (prev, curr) => {
 				return await curr(await prev);
@@ -235,6 +517,7 @@ export class LpkBuild {
 			let p = spawn.sync(cmd, [cmdArgs, this.options['buildscript']], {
 				cwd: this.pwd,
 				stdio: 'inherit',
+				env: { ...process.env, ...this.getBuildVars() },
 			});
 			if (p.status != 0) {
 				throw t('lzc_cli.lib.app.lpk_build.exec_build_fail', `构建失败`);
@@ -245,9 +528,16 @@ export class LpkBuild {
 
 		// 输出路径
 		let packName = this.options['lpkPath'];
-		const pkgout = path.resolve(this.pwd, this.options['pkgout']);
-		if (!packName && !isDirExist(pkgout)) {
-			throw t('lzc_cli.lib.app.lpk_build.exec_pkgout_not_exist', `{{ pkgout }} 不存在`, { pkgout, interpolation: { escapeValue: false } });
+		let pkgout = '';
+		if (!packName) {
+			const rawPkgout = this.options['pkgout'];
+			if (rawPkgout !== undefined && rawPkgout !== null && typeof rawPkgout !== 'string') {
+				throw t('lzc_cli.lib.app.lpk_build.exec_pkgout_invalid_type', 'pkgout must be a string when specified');
+			}
+			pkgout = path.resolve(this.pwd, typeof rawPkgout === 'string' && rawPkgout.trim() !== '' ? rawPkgout : './');
+			if (!isDirExist(pkgout)) {
+				throw t('lzc_cli.lib.app.lpk_build.exec_pkgout_not_exist', `{{ pkgout }} 不存在`, { pkgout, interpolation: { escapeValue: false } });
+			}
 		}
 
 		const tempDir = fs.mkdtempSync('.lzc-cli-build');
@@ -255,31 +545,37 @@ export class LpkBuild {
 		let browserExtension = this.options['browser-extension'];
 		let aiPodService = this.options['ai-pod-service'];
 		try {
-			if (contentdir) {
+			const hasContentDir = !!contentdir;
+			const needsContentArchive = hasContentDir || this.beforeTarContentFn.length > 0;
+			let tempContentDir = '';
+			if (hasContentDir) {
 				contentdir = path.resolve(this.pwd, contentdir);
 				if (!isDirExist(contentdir)) {
 					throw `${contentdir} 不存在`;
 				}
 			} else {
 				logger.warn(t('lzc_cli.lib.app.lpk_build.exec_skip_copy_contentdir', '跳过拷贝 contentdir 内容'));
-				// 当没有指定的 contentdir 的时候，也生成一个空的文件夹
-				// 原因是：可能其他地方会复制内容进来，像 devshell 中的会在打包的时候，将ssh key拷贝进来
-				contentdir = fs.mkdtempSync(path.join(tempDir, 'fake-contentdir'));
 			}
 
-			// 开始打包 contentdir
-			if (this.beforeTarContentFn.length > 0) {
-				await this.beforeTarContentFn.reduce(async (prev, curr) => {
-					let _prev = await prev;
-					await curr(_prev, this.options);
-					return _prev;
-				}, contentdir);
+			if (needsContentArchive) {
+				if (!hasContentDir) {
+					// 没有显式 contentdir 时，仅在 hook 需要写入内容时创建临时目录。
+					tempContentDir = fs.mkdtempSync(path.join(tempDir, 'fake-contentdir'));
+					contentdir = tempContentDir;
+				}
+
+				if (this.beforeTarContentFn.length > 0) {
+					await this.beforeTarContentFn.reduce(async (prev, curr) => {
+						let _prev = await prev;
+						await curr(_prev, this.options);
+						return _prev;
+					}, contentdir);
+				}
+				await tarContentDir(['./'], path.join(tempDir, 'content.tar'), contentdir);
 			}
-			await tarContentDir(['./'], path.join(tempDir, 'content.tar'), contentdir);
 
-			// 如果是临时的 contentdir, 目录在打包完成后删除
-			if (!this.options['contentdir']) {
-				fs.rmSync(contentdir, { recursive: true });
+			if (tempContentDir) {
+				fs.rmSync(tempContentDir, { recursive: true });
 			}
 
 			if (browserExtension) {
@@ -291,7 +587,10 @@ export class LpkBuild {
 				} else if (isFileExist(browserExtension)) {
 					fs.copyFileSync(browserExtension, path.join(tempDir, 'extension.zip'));
 				} else {
-					throw t('lzc_cli.lib.app.lpk_build.exec_browser_extension_not_exist', `{{ browserExtension }} 不存在`, { browserExtension, interpolation: { escapeValue: false } });
+					throw t('lzc_cli.lib.app.lpk_build.exec_browser_extension_not_exist', `{{ browserExtension }} 不存在`, {
+						browserExtension,
+						interpolation: { escapeValue: false },
+					});
 				}
 			}
 
@@ -300,7 +599,7 @@ export class LpkBuild {
 				if (!isDirExist(aiPodService)) {
 					throw t('lzc_cli.lib.app.lpk_build.exec_ai_pos_service_not_exist', `{{ aiPodService }} 不存在`, {
 						aiPodService,
-						interpolation: { escapeValue: false }
+						interpolation: { escapeValue: false },
 					});
 				}
 				fs.cpSync(aiPodService, path.join(tempDir, 'ai-pod-service'), {
@@ -312,6 +611,9 @@ export class LpkBuild {
 			let manifest = await this.getManifest();
 			if (process.env.LZC_VERSION) {
 				manifest.version = process.env.LZC_VERSION;
+				if (this.hasPackageFile) {
+					this.packageInfo = { ...(this.packageInfo ?? {}), version: process.env.LZC_VERSION };
+				}
 			}
 			if (this.beforeDumpYamlFn.length > 0) {
 				manifest = await this.beforeDumpYamlFn.reduce(async (prev, curr) => {
@@ -319,19 +621,90 @@ export class LpkBuild {
 				}, manifest);
 			}
 
-			if (process.env.LZC_MANIFEST_TEMPLATE) {
-				logger.debug('copy origin manifest\n', this.manifestFilePath);
-				fs.copyFileSync(this.manifestFilePath, path.join(tempDir, 'manifest.yml'));
+			if (Object.prototype.hasOwnProperty.call(this.options, 'embed_images')) {
+				throw new Error('embed_images is removed, please use lzc-build.yml images and manifest embed:alias');
+			}
+			if (Object.prototype.hasOwnProperty.call(this.options, 'embed_all_images')) {
+				throw new Error('embed_all_images is removed');
+			}
+			if (Object.prototype.hasOwnProperty.call(this.options, 'upstream_registry')) {
+				throw new Error('upstream_registry is renamed to upstream_match');
+			}
+			if (Object.prototype.hasOwnProperty.call(this.options, 'upstream_match') || Object.prototype.hasOwnProperty.call(this.options, 'upstream-match')) {
+				throw new Error('upstream_match is moved to lzc-build.yml images.<alias>.upstream-match');
+			}
+
+			const hasImagesConfig = !!this.options['images'];
+
+			let embeddedImageSummary = null;
+			if (hasImagesConfig) {
+				const buildResult = await buildConfiguredImagesToTempDir(this.options['images'], manifest, this.pwd, tempDir, {
+					remote: this.options['remote'],
+				});
+				if (buildResult.imageCount > 0) {
+					embeddedImageSummary = buildResult;
+					manifest = rewriteManifestEmbeddedImages(manifest, buildResult.resolvedImageByAlias);
+				}
+			}
+
+			const useV2PackageLayout = shouldUseV2PackageLayout({
+				forceV2: this.forceV2,
+				hasPackageFile: this.hasPackageFile,
+				hasImagesConfig,
+				buildEnvEntries: this.options['envs'],
+			});
+			if (useV2PackageLayout) {
+				logDeprecatedStaticFieldWarning(this.manifestFilePath, findManifestStaticFields(this.sourceManifest));
+			}
+
+			let manifestOutput = manifest;
+			let packageInfoOutput = null;
+			if (useV2PackageLayout) {
+				const split = splitManifestAndPackageInfo(manifest, this.packageInfo);
+				manifestOutput = split.manifest;
+				packageInfoOutput = split.packageInfo;
+			}
+
+			const archiveFormat = useV2PackageLayout ? 'tar' : 'zip';
+			validatePackageFileForArchiveFormat(!!packageInfoOutput, archiveFormat);
+			if (!useV2PackageLayout) {
+				logger.warn('Building legacy LPK v1 metadata layout. Run "lzc-cli migrate" to move static package fields into package.yml.');
+			}
+			if (embeddedImageSummary && embeddedImageSummary.imageCount > 0) {
+				const contentTar = path.join(tempDir, 'content.tar');
+				const contentTarGz = path.join(tempDir, 'content.tar.gz');
+				if (isFileExist(contentTar)) {
+					await gzipFileTo(contentTar, contentTarGz);
+					fs.rmSync(contentTar, { force: true });
+				}
+			}
+
+			if (process.env.LZC_MANIFEST_TEMPLATE && archiveFormat === 'zip') {
+				logger.debug('copy processed manifest\n', this.manifestFilePath);
+				fs.writeFileSync(path.join(tempDir, 'manifest.yml'), this.preprocessedManifestText);
 			} else {
-				logger.debug('manifest\n', manifest);
-				// 异常的manifest，就将源文件给转到lpk内
+				logger.debug('manifest\n', manifestOutput);
 				if (this.excpManifest) {
-					fs.writeFileSync(path.join(tempDir, 'manifest.yml'), fs.readFileSync(this.manifestFilePath, 'utf8'));
+					let rawManifest = this.preprocessedManifestText || fs.readFileSync(this.manifestFilePath, 'utf8');
+					if (archiveFormat === 'zip') {
+						rawManifest = rewriteTopLevelManifestScalarInText(rawManifest, 'package', manifest.package);
+						rawManifest = rewriteTopLevelManifestScalarInText(rawManifest, 'version', manifest.version);
+					} else {
+						rawManifest = removeTopLevelManifestFieldsInText(rawManifest, Object.keys(packageInfoOutput ?? {}));
+					}
+					if (embeddedImageSummary?.resolvedImageByAlias) {
+						rawManifest = rewriteManifestEmbeddedImagesInText(rawManifest, embeddedImageSummary.resolvedImageByAlias);
+					}
+					fs.writeFileSync(path.join(tempDir, 'manifest.yml'), rawManifest);
 				} else {
-					dumpToYaml(manifest, path.join(tempDir, 'manifest.yml'));
+					dumpToYaml(manifestOutput, path.join(tempDir, 'manifest.yml'));
 				}
 			}
 
+			if (packageInfoOutput) {
+				dumpToYaml(packageInfoOutput, path.join(tempDir, PACKAGE_FILE_NAME));
+			}
+
 			// compose.override.yml
 			if (this.options['compose_override']) {
 				dumpToYaml(this.options['compose_override'], path.join(tempDir, 'compose.override.yml'));
@@ -346,14 +719,26 @@ export class LpkBuild {
 			}
 
 			if (!packName) {
-				packName = path.resolve(pkgout, `${manifest.package}-v${manifest.version}.lpk`);
+				const ext = '.lpk';
+				packName = path.resolve(pkgout, `${manifest.package}-v${manifest.version}${ext}`);
 			}
 
-			const lpkPath = await archiveFolderTo(tempDir, packName);
-			logger.info(`${t('lzc_cli.lib.app.lpk_build.exec_output_lpk_path', '输出lpk包 {{ path }}', {
-				path: lpkPath.path,
-				interpolation: { escapeValue: false } // https://www.i18next.com/translation-function/interpolation#unescape
-			})}`);
+			const lpkPath = await archiveFolderTo(tempDir, packName, archiveFormat);
+			logger.info(
+				`${t('lzc_cli.lib.app.lpk_build.exec_output_lpk_path', '输出lpk包 {{ path }}', {
+					path: lpkPath.path,
+					interpolation: { escapeValue: false }, // https://www.i18next.com/translation-function/interpolation#unescape
+				})}`,
+			);
+			if (embeddedImageSummary && embeddedImageSummary.imageCount > 0) {
+				logger.info('Embedded image upstream summary:');
+				for (const [alias, upstream] of Object.entries(embeddedImageSummary.upstreamByAlias ?? {})) {
+					logger.info(`- ${alias}: ${upstream || '(none, full embed)'}`);
+				}
+				logger.info(
+					`Embedded image layer size: ${formatBytes(embeddedImageSummary.embeddedLayerBytes)} (${embeddedImageSummary.embeddedLayerBytes} bytes, ${embeddedImageSummary.embeddedLayerCount} unique layers)`,
+				);
+			}
 
 			return lpkPath.path;
 		} finally {