@uni-helper/vite-plugin-uni-pages 0.4.8 → 0.5.0

package/dist/index.mjs

@@ -1,69 +1,65 @@
 import { createRequire } from "node:module";
 import path, { dirname, extname, join, resolve } from "node:path";
 import process from "node:process";
-import { babelParse, isCallOf } from "ast-kit";
 import chokidar from "chokidar";
 import MagicString from "magic-string";
 import { createLogger, normalizePath } from "vite";
-import fs, { existsSync } from "node:fs";
 import { platform } from "@uni-helper/uni-env";
 import { CommentArray, parse, stringify } from "comment-json";
 import Debug from "debug";
-import detectIndent from "detect-indent";
-import detectNewline from "detect-newline";
+import groupBy from "lodash.groupby";
 import { loadConfig } from "unconfig";
-import writeFileAtomic from "write-file-atomic";
+import fs, { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import lockfile from "proper-lockfile";
 import { globSync } from "tinyglobby";
 import vm from "node:vm";
-import babelGenerator from "@babel/generator";
-import groupBy from "lodash.groupby";
-import * as ts from "typescript";
+import babelGenerate from "@babel/generator";
 import * as t from "@babel/types";
 import { parse as parse$1 } from "@vue/compiler-sfc";
+import { babelParse, isCallOf } from "ast-kit";
+import * as ts from "typescript";
+import writeFileAtomic from "write-file-atomic";
 //#region src/constant.ts
-/** Virtual module identifier for Vite module resolution */
+/** Vite 模块解析用的虚拟模块标识 */
 const MODULE_ID_VIRTUAL = "virtual:uni-pages";
-/** Resolved virtual module identifier with \0 prefix to avoid conflicts with other modules */
+/** 加 \0 前缀解析后的虚拟模块标识，避免与其他模块冲突 */
 const RESOLVED_MODULE_ID_VIRTUAL = `\0${MODULE_ID_VIRTUAL}`;
-/** Output filename, the uni-app page configuration file */
+/** 输出文件名，即 uni-app 的页面配置文件 */
 const OUTPUT_NAME = "pages.json";
-/** Supported page file extensions */
+/** 支持的页面文件扩展名 */
 const FILE_EXTENSIONS = [
 	"vue",
 	"nvue",
 	"uvue"
 ];
 //#endregion
-//#region ../../node_modules/.pnpm/@antfu+utils@9.3.0/node_modules/@antfu/utils/dist/index.mjs
-function slash(str) {
-	return str.replace(/\\/g, "/");
-}
-//#endregion
 //#region src/declaration.ts
 /**
-* Generate TypeScript declaration file content
-* Provide type hints for uni-app navigation APIs (navigateTo, redirectTo, switchTab, reLaunch)
-* Ensure page paths get type checking at compile time
+* 生成 TypeScript 声明文件内容
+* 为 uni-app 的导航 API（navigateTo、redirectTo、switchTab、reLaunch）提供类型提示，
+* 让页面路径在编译期获得类型检查
 *
-* @param ctx - Page context instance
-* @returns Declaration file code string
+* @param input - 合并后的路由数据
+* @returns 声明文件代码字符串
 */
-function getDeclaration(ctx) {
-	const subPagesPath = ctx.subPageMetaData.map((sub) => {
+function getDeclaration(input) {
+	const subPagePaths = input.subPackages.map((sub) => {
 		return sub.pages.map((v) => `"/${normalizePath(join(sub.root, v.path))}"`);
 	}).flat();
-	const tabsPagesPath = ctx.pagesGlobConfig?.tabBar?.list?.map((v) => {
-		return `"/${v.pagePath}"`;
-	}) ?? [];
+	const tabBarRawPaths = input.tabBar?.list?.map((v) => v.pagePath) ?? input.globConfig?.tabBar?.list?.map((v) => v.pagePath) ?? [];
+	const tabBarPathSet = new Set(tabBarRawPaths);
+	const allPagePaths = [...input.pages.filter((page) => !tabBarPathSet.has(page.path)).map((v) => `"/${v.path}"`), ...subPagePaths];
+	const tabBarPagePaths = tabBarRawPaths.map((p) => `"/${p}"`);
 	return `/* eslint-disable */
 /* prettier-ignore */
+/* oxlint-disable */
+/* oxfmt-ignore */
 // @ts-nocheck
 // Generated by vite-plugin-uni-pages
 
 type _LocationUrl =
-  ${[...ctx.pageMetaData.filter((page) => !tabsPagesPath.includes(page.path)).map((v) => `"/${v.path}"`), ...subPagesPath].join(" |\n  ")};
+  ${allPagePaths.length > 0 ? allPagePaths.join(" |\n  ") : "string"};
 
 interface NavigateToOptions {
   url: _LocationUrl;
@@ -71,7 +67,7 @@ interface NavigateToOptions {
 interface RedirectToOptions extends NavigateToOptions {}
 
 interface SwitchTabOptions {
-  ${tabsPagesPath.length ? `url: ${tabsPagesPath.join(" | ")}` : ""}
+  ${tabBarPagePaths.length ? `url: ${tabBarPagePaths.join(" | ")}` : ""}
 }
 
 type ReLaunchOptions = NavigateToOptions | SwitchTabOptions;
@@ -89,327 +85,192 @@ declare module "virtual:uni-pages" {
 `;
 }
 /**
-* Write file, automatically create directories
-* @param filePath - File path
-* @param content - File content
+* 写入文件，自动创建所在目录
+* @param filePath - 文件路径
+* @param content - 文件内容
 */
 async function writeFile$1(filePath, content) {
 	await mkdir(dirname(filePath), { recursive: true });
 	return await writeFile(filePath, content, "utf-8");
 }
 /**
-* Write declaration file to disk
-* Only writes when content changes to avoid unnecessary file operations
+* 将声明文件写入磁盘
+* 仅在内容变化时写入，避免不必要的文件操作
 *
-* @param ctx - Page context instance
-* @param filepath - Declaration file output path
+* @param input - 合并后的路由数据
+* @param filepath - 声明文件输出路径
 */
-async function writeDeclaration(ctx, filepath) {
+async function writeDeclaration(input, filepath) {
 	const originalContent = existsSync(filepath) ? await readFile(filepath, "utf-8") : "";
-	const code = getDeclaration(ctx);
+	const code = getDeclaration(input);
 	if (!code) return;
 	if (code !== originalContent) await writeFile$1(filepath, code);
 }
 //#endregion
-//#region src/utils.ts
-/**
-* Invalidate virtual module to trigger HMR update
-* When page configuration changes, the virtual module needs to be invalidated to regenerate content
-*
-* @param server - Vite dev server instance
-*/
-function invalidatePagesModule(server) {
-	const { moduleGraph } = server;
-	const mods = moduleGraph.getModulesByFile(RESOLVED_MODULE_ID_VIRTUAL);
-	if (mods) {
-		const seen = /* @__PURE__ */ new Set();
-		mods.forEach((mod) => {
-			moduleGraph.invalidateModule(mod, seen);
-		});
-	}
-}
+//#region src/logger.ts
 /**
-* Debug logging utility
-* Uses debug package for leveled log output
-* Enable via environment variable DEBUG=vite-plugin-uni-pages:*
+* 调试日志工具
+* 基于 debug 包做分级日志输出
+* 通过环境变量 DEBUG=vite-plugin-uni-pages:* 开启
 */
 const debug = {
-	/** HMR related logs */
+	/** HMR 相关日志 */
 	hmr: Debug("vite-plugin-uni-pages:hmr"),
-	/** Configuration options related logs */
+	/** 配置项相关日志 */
 	options: Debug("vite-plugin-uni-pages:options"),
-	/** Main package page scanning logs */
+	/** 主包页面扫描日志 */
 	pages: Debug("vite-plugin-uni-pages:pages"),
-	/** Sub-package page scanning logs */
+	/** 子包页面扫描日志 */
 	subPages: Debug("vite-plugin-uni-pages:subPages"),
-	/** Error logs */
+	/** 错误日志 */
 	error: Debug("vite-plugin-uni-pages:error"),
-	/** Cache related logs */
+	/** 缓存相关日志 */
 	cache: Debug("vite-plugin-uni-pages:cache"),
-	/** Declaration file generation logs */
+	/** 声明文件生成日志 */
 	declaration: Debug("vite-plugin-uni-pages:declaration"),
-	/** definePage macro parsing logs */
+	/** definePage 宏解析日志 */
 	definePage: Debug("vite-plugin-uni-pages:definePage")
 };
+//#endregion
+//#region src/files.ts
 /**
-* Convert file extensions array to glob pattern
-* @param extensions - File extensions array
-* @returns Glob pattern string
+* 解析给定上下文下可作为有效页面的文件列表。
 */
-function extsToGlob(extensions) {
-	return extensions.length > 1 ? `{${extensions.join(",")}}` : extensions[0] || "";
+function getPageFiles(path, options) {
+	const { exclude } = options;
+	const ext = FILE_EXTENSIONS.length > 1 ? `{${FILE_EXTENSIONS.join(",")}}` : FILE_EXTENSIONS[0] || "";
+	return globSync(`**/*.${ext}`, {
+		ignore: exclude,
+		onlyFiles: true,
+		cwd: path
+	});
 }
 /**
-* Check if file is a target page file
-* Determine if the file extension is in the supported page file types list
+* 检查文件是否为目标页面文件
+* 判断文件扩展名是否在支持的页面文件类型列表中
 *
-* @param path - File path
-* @returns Whether it's a target file
+* @param path - 文件路径
+* @returns 是否为目标文件
 */
 function isTargetFile(path) {
 	const ext = path.split(".").pop();
 	return FILE_EXTENSIONS.includes(ext);
 }
 /**
-* merge page meta data array by path and assign style
-* @param pageMetaData  page meta data array
-* TODO: support merge middleware
-*/
-function mergePageMetaDataArray(pageMetaData) {
-	const pageMetaDataObj = groupBy(pageMetaData, "path");
-	const result = [];
-	for (const path in pageMetaDataObj) {
-		const _pageMetaData = pageMetaDataObj[path];
-		const options = _pageMetaData[0];
-		for (const page of _pageMetaData) {
-			options.style = Object.assign(options.style ?? {}, page.style ?? {});
-			Object.assign(options, page);
-		}
-		result.push(options);
-	}
-	return result;
-}
-/**
-* Convert TypeScript / JavaScript script code to object/function
+* 根据项目根目录与输出目录解析 pages.json 文件路径
 *
-* @param options - Configuration required for script execution
-* @param options.imports - List of module import statements to include
-* @param options.code - TypeScript code content to execute
-* @param options.filename - Script filename for error location and context
-* @returns Script execution result, if export is a function then execute and return its return value
-*/
-async function parseCode(options) {
-	const { imports = [], code, filename } = options;
-	let jsCode = "";
-	try {
-		const tmpCode = `${imports.join("\n")}\n export default ${code}`;
-		jsCode = ts.transpileModule(tmpCode, {
-			compilerOptions: {
-				module: ts.ModuleKind.CommonJS,
-				target: ts.ScriptTarget.ES2022,
-				noEmit: true,
-				strict: false,
-				noImplicitAny: false,
-				strictNullChecks: false,
-				strictFunctionTypes: false,
-				strictBindCallApply: false,
-				strictPropertyInitialization: false,
-				noImplicitThis: false,
-				alwaysStrict: false,
-				allowJs: true,
-				checkJs: false,
-				skipLibCheck: true,
-				esModuleInterop: true,
-				removeComments: true
-			},
-			jsDocParsingMode: ts.JSDocParsingMode.ParseNone
-		}).outputText;
-		const dir = path.dirname(filename);
-		const vmContext = {
-			module: {},
-			exports: {},
-			__filename: filename,
-			__dirname: dir,
-			require: createRequire(dir),
-			import: (id) => import(id),
-			setTimeout,
-			clearTimeout,
-			setInterval,
-			clearInterval,
-			setImmediate,
-			clearImmediate,
-			console,
-			URL,
-			URLSearchParams,
-			performance,
-			global: globalThis,
-			globalThis
-		};
-		await new vm.Script(jsCode, { filename }).runInNewContext(vmContext, { timeout: 1e3 });
-		return vmContext.exports.default || vmContext.exports;
-	} catch (error) {
-		throw new Error(`EXEC SCRIPT FAIL IN ${filename}: ${error.message} \n\n${jsCode}\n\n`);
-	}
-}
-/**
-* Async sleep function
-* @param ms - Sleep duration in milliseconds
-* @returns Promise object
+* @param root - 项目根目录
+* @param outDir - 相对 root 的 pages.json 输出目录
+* @returns pages.json 绝对路径
 */
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+function resolvePagesJsonPath(root, outDir) {
+	return path.join(root, outDir, OUTPUT_NAME);
 }
 /**
-* Get default export of a module
-* Compatible with CommonJS and ES Module export styles
+* 确保这个路径上有一个能用的 pages.json 文件。
 *
-* @param expr - Module object
-* @returns Default export value
-*/
-function getDefaultExport(expr) {
-	return expr.default === void 0 ? expr : expr.default;
-}
-/** Babel code generator for converting AST back to code */
-const babelGenerate = getDefaultExport(babelGenerator);
-//#endregion
-//#region src/files.ts
-/**
-* Resolves the files that are valid pages for the given context.
-*/
-function getPageFiles(path, options) {
-	const { exclude } = options;
-	return globSync(`**/*.${extsToGlob(FILE_EXTENSIONS)}`, {
-		ignore: exclude,
-		onlyFiles: true,
-		cwd: path
-	});
-}
-/**
-* Check the pages.json file at the specified path, create an empty pages.json file if it doesn't exist or is not a valid file
-* @param path - File path to check
-* @returns boolean - Whether the operation was successful
+* 文件不存在时创建一个占位文件，占位内容很快会被下一次生成覆盖。
+* 已存在的文件绝不删除重建：删它会悄悄弄丢手写的内容（只读的文件
+* 也能被删除，只要它所在的目录可写），所以"路径存在但不是普通文件、
+* 或者读不了也写不了"都算必须由用户自己修的硬错误（例如
+* `chmod u+w`）。
+*
+* @param path - 待检查的文件路径
+* @throws 路径存在但不是普通文件、缺少读写权限，或占位文件创建失败时
+*          抛出
 */
 function checkPagesJsonFileSync(path) {
-	/**
-	* Create an empty pages.json file
-	* @param path - File path
-	* @returns boolean - Whether the creation was successful
-	*/
-	const createEmptyFile = (path) => {
-		try {
-			fs.writeFileSync(path, JSON.stringify({ pages: [{ path: "" }] }, null, 2), { encoding: "utf-8" });
-			return true;
-		} catch {
-			return false;
-		}
-	};
-	/**
-	* Delete the file at the specified path
-	* @param path - File path
-	* @returns boolean - Whether the deletion was successful
-	*/
-	const unlinkFile = (path) => {
-		try {
-			fs.unlinkSync(path);
-			return true;
-		} catch {
-			return false;
-		}
-	};
 	try {
-		try {
-			fs.accessSync(path, fs.constants.F_OK);
-		} catch {
-			return createEmptyFile(path);
-		}
-		if (!fs.statSync(path).isFile()) {
-			if (!unlinkFile(path)) return false;
-			return createEmptyFile(path);
-		}
-		try {
-			fs.accessSync(path, fs.constants.R_OK | fs.constants.W_OK);
-			return true;
-		} catch {
-			if (!unlinkFile(path)) return false;
-			return createEmptyFile(path);
-		}
+		fs.accessSync(path, fs.constants.F_OK);
+	} catch {
+		fs.writeFileSync(path, JSON.stringify({ pages: [{ path: "" }] }, null, 2), { encoding: "utf-8" });
+		return;
+	}
+	if (!fs.statSync(path).isFile()) throw new Error(`[vite-plugin-uni-pages] ${path} exists but is not a regular file. Remove it manually if it is not needed; the plugin refuses to delete or overwrite it.`);
+	try {
+		fs.accessSync(path, fs.constants.R_OK | fs.constants.W_OK);
 	} catch {
-		return createEmptyFile(path);
+		throw new Error(`[vite-plugin-uni-pages] ${path} is not readable and writable. The plugin rewrites pages.json on every run; fix the file permissions (e.g. chmod u+w) or remove the read-only flag. The plugin refuses to delete and recreate the file because that would lose its content.`);
 	}
 }
 /**
-* Run a task while holding an exclusive file lock.
+* 同一个进程里按文件路径排的等待队列（先来后到）。
 *
-* Unlike {@link writeFileWithLock}, this protects the whole read-modify-write
-* critical section. The lock is held from the moment `task` starts until it
-* resolves, so concurrent processes cannot observe or overwrite a half-written
-* state. This is required by pages.json generation, where the new content
-* depends on the current content (other platforms' `#ifdef` blocks).
+* 同进程的调用方先在这里排队，不直接去抢 OS 锁：抢锁靠不断重试，
+* 可能有人运气差总抢不到（比如 dev server 启动时监听器 `add` 事件
+* 一拥而上）。排队保证人人都轮得到。下面的 OS 锁负责挡住其他进程。
+*/
+const lockQueues = /* @__PURE__ */ new Map();
+/**
+* 拿到文件的独占锁后运行任务，运行完自动放锁。
+*
+* 它保护"读文件 → 算新内容 → 写回"的整个过程：锁从 `task` 开始
+* 一直拿到它结束，别的进程看不到、也覆盖不了写了一半的文件。
+* pages.json 的生成靠这一点：新内容要根据当前文件来算（里面有其他
+* 平台的 `#ifdef` 块）。
+*
+* 同进程的调用方先在上面那条按路径的队列里排队，再碰 OS 锁；下面的
+* 重试只用来等其他进程放锁。
 *
-* @param path - File path used as the lock target
-* @param task - Async work to run inside the lock; return value is forwarded
-* @param retry - Number of retries when lock acquisition fails, defaults to 3
-* @returns The value resolved by `task`, or `undefined` if the lock could not be acquired
+* @param path - 要加锁的文件路径
+* @param task - 在锁内运行的异步任务；返回值原样返回给调用方
+* @param retry - 锁被别人拿着时的重试次数，默认 3
+* @returns `task` 的结果；一直拿不到锁时为 `undefined`
 */
-async function withFileLock(path, task, retry = 3) {
-	if (retry <= 0) {
-		debug.error(`${path} Failed to acquire file lock, task aborted`);
-		return;
-	}
-	let release;
-	try {
+function withFileLock(path, task, retry = 3) {
+	const current = (lockQueues.get(path) ?? Promise.resolve()).catch(() => {}).then(() => acquireAndRun(path, task, retry));
+	lockQueues.set(path, current);
+	return current;
+}
+/** 去拿 OS 级的锁（拿不到就等一会儿再试，防的是其他进程），拿到后运行任务 */
+async function acquireAndRun(path, task, retry) {
+	for (let attempt = retry; attempt > 0; attempt--) {
+		let release;
 		try {
 			release = await lockfile.lock(path, { realpath: false });
 		} catch {
 			await sleep(500);
-			return withFileLock(path, task, retry - 1);
+			continue;
+		}
+		try {
+			return await task();
+		} finally {
+			await release();
 		}
-		return await task();
-	} finally {
-		if (release) await release();
 	}
+	debug.error(`${path} Failed to acquire file lock, task aborted`);
 }
 /**
-* Safely write file using file lock
-* Avoid data corruption caused by concurrent writes through file lock
-* Use atomic write to ensure file write integrity
-*
-* Note: this only makes the *write* atomic. Callers that need to read the
-* current content before computing the new one must use {@link withFileLock}
-* so the read and write belong to the same critical section.
-*
-* @param path - File path
-* @param content - File content
-* @param retry - Number of retries when lock acquisition fails, defaults to 3
+* 异步休眠函数
+* @param ms - 休眠毫秒数
+* @returns 指定延时后 resolve 的 Promise
 */
-async function writeFileWithLock(path, content, retry = 3) {
-	return withFileLock(path, async () => {
-		await writeFileAtomic(path, content);
-	}, retry);
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 //#endregion
 //#region src/options.ts
 /**
-* Resolve user configuration options
-* Merge user-provided configuration with default values and handle path resolution
+* 解析用户配置项
+* 将用户提供的配置与默认值合并，并处理路径解析
 *
-* @param userOptions - User configuration options
-* @param viteRoot - Vite project root directory
-* @returns Resolved configuration options
+* @param userOptions - 用户配置项
+* @param viteRoot - Vite 项目根目录
+* @returns 解析后的配置项
 */
 function resolveOptions(userOptions, viteRoot = process.cwd()) {
 	const { dts = true, configSource = "pages.config", homePage = ["pages/index", "pages/index/index"], mergePages = true, dir = "src/pages", subPackages = [], outDir = "src", exclude = [
 		"node_modules",
 		".git",
 		"**/__*__/**"
-	], minify = false, debug = false, onBeforeLoadUserConfig = () => {}, onAfterLoadUserConfig = () => {}, onBeforeScanPages = () => {}, onAfterScanPages = () => {}, onBeforeMergePageMetaData = () => {}, onAfterMergePageMetaData = () => {}, onBeforeWriteFile = () => {}, onAfterWriteFile = () => {} } = userOptions;
-	const root = viteRoot || slash(process.env.VITE_ROOT_DIR || process.cwd());
+	], minify = false, insertFinalNewline = false, indent = 2, eol = "\n", debug = false, onBeforeLoadUserConfig = () => {}, onAfterLoadUserConfig = () => {}, onBeforeScanPages = () => {}, onAfterScanPages = () => {}, onBeforeMergePageMetaData = () => {}, onAfterMergePageMetaData = () => {}, onBeforeWriteFile = () => {}, onAfterWriteFile = () => {} } = userOptions;
+	const root = viteRoot || normalizePath(process.env.VITE_ROOT_DIR || process.cwd());
 	const resolvedDirs = resolvePageDirs(dir, root, exclude);
 	const subPackageRootMap = /* @__PURE__ */ new Map();
 	const resolvedSubDirs = [];
-	for (const sub of subPackages) if (typeof sub === "string") resolvedSubDirs.push(slash(sub));
+	for (const sub of subPackages) if (typeof sub === "string") resolvedSubDirs.push(normalizePath(sub));
 	else {
-		const dirPath = slash(sub.dir);
+		const dirPath = normalizePath(sub.dir);
 		resolvedSubDirs.push(dirPath);
 		subPackageRootMap.set(dirPath, sub.root);
 	}
@@ -427,6 +288,9 @@ function resolveOptions(userOptions, viteRoot = process.cwd()) {
 		exclude,
 		root,
 		minify,
+		insertFinalNewline,
+		indent,
+		eol,
 		debug,
 		onBeforeLoadUserConfig,
 		onAfterLoadUserConfig,
@@ -439,10 +303,14 @@ function resolveOptions(userOptions, viteRoot = process.cwd()) {
 	};
 }
 /**
-* Resolves the page dirs for its for its given globs
+* 根据给定的 glob 模式解析页面目录
+* @param dir - 页面目录 glob 模式
+* @param root - 项目根目录
+* @param exclude - 需要排除的 glob 模式
+* @returns 匹配到的目录路径
 */
 function resolvePageDirs(dir, root, exclude) {
-	return globSync(slash(dir), {
+	return globSync(normalizePath(dir), {
 		ignore: exclude,
 		onlyDirectories: true,
 		expandDirectories: false,
@@ -451,115 +319,118 @@ function resolvePageDirs(dir, root, exclude) {
 	});
 }
 //#endregion
-//#region src/page.ts
+//#region src/condition.ts
+/** 判断一个值是否为普通对象（非 null、非数组） */
+function isPlainObject(val) {
+	return typeof val === "object" && val !== null && !Array.isArray(val);
+}
 /**
-* Page class representing a Vue page file
+* 把 `partial` 合并进 `base`，两边都不改动
 *
-* Responsibilities:
-* 1. Read page file content
-* 2. Parse page metadata defined by definePage macro
-* 3. Provide tabBar configuration information
-* 4. Track page file change status
+* 对象一层层往里合并；数组和普通值直接整个替换。规则和
+* @uni-ku/pages-json 保持一致。
 */
-var Page = class {
-	/** Page context instance */
-	ctx;
-	/** Page path information containing relative and absolute paths */
-	path;
-	/** Page URI used for pages.json path field */
-	uri;
-	/** Whether the page has changed, used for incremental update judgment */
-	changed = true;
-	/** Raw JSON string of page metadata for change detection */
-	raw = "";
-	/** Parsed page metadata */
-	meta;
-	/**
-	* Create a page instance
-	* @param ctx - Page context instance
-	* @param path - Page path information
-	*/
-	constructor(ctx, path) {
-		this.ctx = ctx;
-		this.path = path;
-		this.uri = normalizePath(path.relativePath.replace(extname(path.relativePath), ""));
+function deepMerge(base, partial) {
+	const result = { ...base };
+	for (const key of Object.keys(partial)) {
+		const baseVal = result[key];
+		const partialVal = partial[key];
+		result[key] = isPlainObject(baseVal) && isPlainObject(partialVal) ? deepMerge(baseVal, partialVal) : partialVal;
 	}
-	/**
-	* Get page metadata
-	* Parse configuration defined by definePage macro and return metadata for pages.json
-	*
-	* @param forceUpdate - Whether to force update, ignoring cache
-	* @returns Page metadata object
-	*/
-	async getPageMeta(forceUpdate = false) {
-		if (forceUpdate || !this.meta) await this.read();
-		const { path, tabBar: _, ...others } = this.meta || {};
-		return {
-			path: path ?? this.uri,
-			...others
-		};
+	return result;
+}
+function toPlatforms(platform) {
+	return Array.isArray(platform) ? platform : [platform];
+}
+/** uni-app 生态中同一浏览器目标的平台标识别名 */
+const H5_ALIASES = ["h5", "web"];
+/**
+* `platform` 是否匹配 `platforms` 列表
+*
+* uni-env 的 `isH5`/`isWeb` 同时认 `h5` 和 `web` 两个写法（较新的
+* uni-app H5 构建设置的是 UNI_PLATFORM=web），所以列表里写了其中
+* 任何一个写法，都算匹配。
+*/
+function platformMatches(platforms, platform) {
+	if (platforms.includes(platform)) return true;
+	return H5_ALIASES.includes(platform) && platforms.some((p) => H5_ALIASES.includes(p));
+}
+/**
+* 可以链式调用的"按平台写配置"对象
+*
+* 用户在函数式 definePage 里通过 define() 创建。分支按写的顺序生效，
+* 后写的同名键会盖掉先写的。
+*/
+var DefineConditional = class {
+	/** 所有平台共用的基础配置 */
+	base;
+	/** 按写的顺序记下的条件分支 */
+	branches = [];
+	constructor(base) {
+		this.base = base;
 	}
-	/**
-	* Get page tabBar configuration
-	* Extract tabBar related configuration from definePage macro
-	*
-	* @param forceUpdate - Whether to force update, ignoring cache
-	* @returns tabBar configuration object, or undefined if page doesn't define tabBar
-	*/
-	async getTabBar(forceUpdate = false) {
-		if (forceUpdate || !this.meta) await this.read();
-		const { tabBar } = this.meta || {};
-		if (tabBar === void 0) return;
-		return {
-			...tabBar,
-			pagePath: tabBar.pagePath || this.uri,
-			index: tabBar.index ?? 0
-		};
+	/** 仅在给定平台应用 `partial` */
+	ifdef(platform, partial) {
+		this.branches.push({
+			condition: "ifdef",
+			platforms: toPlatforms(platform),
+			partial
+		});
+		return this;
 	}
-	/**
-	* Check if the page has changed
-	* @returns Whether the page has changed
-	*/
-	hasChanged() {
-		return this.changed;
+	/** 在除给定平台之外的所有平台应用 `partial` */
+	ifndef(platform, partial) {
+		this.branches.push({
+			condition: "ifndef",
+			platforms: toPlatforms(platform),
+			partial
+		});
+		return this;
 	}
 	/**
-	* Read page file and parse metadata
-	* Extract configuration defined by definePage macro from Vue SFC
+	* 算出某个平台最终用的普通配置：从基础配置开始，按写的顺序把每个
+	* 匹配的分支合并进去。平台列表里 `h5` 和 `web` 互相通用（见
+	* platformMatches）。
 	*/
-	async read() {
-		let meta;
-		try {
-			meta = await this.readPageMetaFromFile();
-		} catch (err) {
-			debug.error(err);
-			return;
-		}
-		let raw = "";
-		try {
-			raw = JSON.stringify(meta);
-		} catch {}
-		this.changed = this.raw !== raw;
-		this.meta = meta;
-		this.raw = raw;
-	}
-	async readPageMetaFromFile() {
-		try {
-			const meta = await tryPageMetaFromMacro(parseSFC(await fs.promises.readFile(this.path.absolutePath, { encoding: "utf-8" }), { filename: this.path.absolutePath }));
-			if (meta) return meta;
-			return { type: "page" };
-		} catch (err) {
-			throw new Error(`Read page meta fail in ${this.path.relativePath}\n${err.message}`);
-		}
+	resolve(platform) {
+		let result = this.base;
+		for (const branch of this.branches) if (branch.condition === "ifdef" ? platformMatches(branch.platforms, platform) : !platformMatches(branch.platforms, platform)) result = deepMerge(result, branch.partial);
+		return result;
 	}
 };
+/** 判断宏求值的结果是不是一个条件定义 */
+function isConditional(obj) {
+	return obj instanceof DefineConditional;
+}
+/**
+* 把条件定义算成某个平台的普通配置
+*
+* 简单包了一层 {@link DefineConditional.resolve}，调用方不用导入
+* 这个类。
+*/
+function resolveConditional(cond, platform) {
+	return cond.resolve(platform);
+}
+//#endregion
+//#region src/macro.ts
+/**
+* definePage 宏的解析与求值
+*
+* 这个文件负责看懂一个 definePage 宏要的全部步骤：解析 Vue 单文件
+* 组件、逐个 script 块解析（单个块失败不影响别的块）、找到宏调用、
+* 收集 import 语句、放进沙箱求值。外部只用两个函数：
+* evaluateDefinePage（扫描时用）和 findDefinePageMacro（转换时用）。
+*
+* 两个入口都从 {@link parseSfcBlocks} 的块模型取宏：「两边按同一套
+* 规则找到同一个宏」由这个共享模型保证，不靠两边各自实现再对齐。
+*/
 /**
-* Parse Vue Single File Component (SFC)
-* Compatible with different versions of @vue/compiler-sfc
+* 解析 Vue 单文件组件（SFC）
+* 兼容不同版本的 @vue/compiler-sfc
 *
-* @param code - Vue SFC source code
-* @param options - Parse options
-* @returns SFC descriptor object
+* @param code - Vue SFC 源码
+* @param options - 解析选项
+* @returns SFC descriptor 对象
 */
 function parseSFC(code, options) {
 	return parse$1(code, {
@@ -571,39 +442,112 @@ function parseSFC(code, options) {
 	});
 }
 /**
-* Try to extract page metadata defined by definePage macro from SFC
-* Support using definePage in script setup or regular script
+* 把 SFC 的两个 script 块各自解析成 AST（共享的块模型）。
+*
+* 块序固定先 `<script setup>` 后 `<script>`；一个块解析失败不拦另一
+* 个块（宏多半写在另一个块里，比如 @babel/parser 8 删掉的旧版
+* `assert { ... }` import 属性会让还在用它的块失败）。失败记录在块
+* 的 `error` 上，由调用方决定上报还是抛出。
+*
+* @param code - Vue SFC 源码
+* @param filename - 用于错误提示和模块解析的 SFC 文件名
+* @returns 按固定顺序排列的块列表
+*/
+function parseSfcBlocks(code, filename) {
+	const sfc = parseSFC(code, { filename });
+	const blocks = [];
+	for (const [name, script] of [["<script setup>", sfc.scriptSetup], ["<script>", sfc.script]]) {
+		if (!script) continue;
+		try {
+			const body = babelParse(script.content, script.lang || "js").body;
+			blocks.push({
+				name,
+				body,
+				imports: findImports(body)
+			});
+		} catch (error) {
+			blocks.push({
+				name,
+				body: [],
+				imports: [],
+				error
+			});
+		}
+	}
+	return blocks;
+}
+/**
+* 求值 Vue SFC 里的 definePage 宏，返回页面信息
 *
-* @param sfc - Vue SFC descriptor
-* @returns Page metadata object, or undefined if definePage is not found
+* 扫描时用。解析或求值出错时，错误会交给调用方（Page.read），它会把
+* 这个页面退回成只含路径的简单信息。
+*
+* @param code - Vue SFC 源码
+* @param filename - SFC 文件名，用于错误提示和模块解析
+* @param platform - 当前平台标识，传给函数式宏；默认取 uni-env 的平台
+* @returns 页面信息对象；宏明确退出（definePage(null) 或函数返回
+* null）时为 `null`；没找到 definePage 时为 undefined
 */
-async function tryPageMetaFromMacro(sfc) {
-	const sfcScript = sfc.scriptSetup || sfc.script;
-	if (!sfcScript) return;
-	const ast = babelParse(sfcScript.content, sfcScript.lang || "js", { plugins: [["importAttributes", { deprecatedAssertSyntax: true }]] });
-	const macro = findMacro(ast.body, sfc.filename);
-	if (macro) {
-		const imports = findImports(ast.body).filter((imp) => !!imp.specifiers.length).map((imp) => babelGenerate(imp).code);
+async function evaluateDefinePage(code, filename, platform$2 = platform) {
+	const blocks = parseSfcBlocks(code, filename);
+	for (const { body, error } of blocks) {
+		if (error) continue;
+		const macro = findMacro(body, filename);
+		if (!macro) continue;
 		const [macroOption] = macro.arguments;
-		const code = babelGenerate(macroOption).code;
+		if (!macroOption) return void 0;
+		const macroCode = babelGenerate(macroOption).code;
 		const parsed = await parseCode({
-			imports,
-			code,
-			filename: sfc.filename
+			imports: pickEvalImports(blocks.map((block) => block.imports), macroOption),
+			code: macroCode,
+			filename
 		});
+		const parsedMeta = typeof parsed === "function" ? await parsed({
+			platform: platform$2,
+			define: (base) => new DefineConditional(base)
+		}) : parsed;
+		const resolvedMeta = isConditional(parsedMeta) ? parsedMeta.resolve(platform$2) : parsedMeta;
+		if (resolvedMeta === null) return null;
 		return {
 			type: "page",
-			...typeof parsed === "function" ? await Promise.resolve(parsed()) : await Promise.resolve(parsed)
+			...resolvedMeta
 		};
 	}
+	const failed = blocks.find((block) => block.error);
+	if (failed) throw failed.error;
+}
+/**
+* 在 Vue SFC 中定位 definePage 宏调用但不求值
+*
+* 转换插件用它找到宏再删掉，不求值。块解析失败通过 `onParseError`
+* 报出来，不抛错。
+*
+* @param code - Vue SFC 源码
+* @param filename - 用于错误上报的 SFC 文件名
+* @param options - 可选的按块解析失败钩子
+* @param options.onParseError - 以失败的 script 块名与错误对象调用
+* @returns definePage 调用表达式，未找到时为 undefined
+*/
+function findDefinePageMacro(code, filename, options = {}) {
+	for (const { name, body, error } of parseSfcBlocks(code, filename)) {
+		if (error) {
+			options.onParseError?.(name, error);
+			continue;
+		}
+		const macro = findMacro(body, filename);
+		if (macro) return macro;
+	}
 }
 /**
-* Find definePage macro call in AST
-* Support function expressions, arrow functions and object expressions as arguments
+* 在 AST 中查找 definePage 宏调用
+* 支持函数表达式、箭头函数与对象表达式作为参数
+*
+* 已知限制：只在块的顶层语句里找，包进 if/try 等语句块里的调用
+* 不在此列（用户侧的说明写在 README 的 definePage 章节）
 *
-* @param stmts - AST statement array
-* @param filename - Filename for error reporting
-* @returns definePage call expression, or undefined if not found
+* @param stmts - AST 语句数组
+* @param filename - 用于错误上报的文件名
+* @returns definePage 调用表达式，未找到时为 undefined
 */
 function findMacro(stmts, filename) {
 	let macro;
@@ -617,74 +561,1065 @@ function findMacro(stmts, filename) {
 	}
 	if (!macro) return;
 	const [opt] = macro.arguments;
-	if (opt && !t.isFunctionExpression(opt) && !t.isArrowFunctionExpression(opt) && !t.isObjectExpression(opt)) {
-		debug.definePage(`definePage() 参数仅支持函数或对象：${filename}`);
+	if (opt && !t.isFunctionExpression(opt) && !t.isArrowFunctionExpression(opt) && !t.isObjectExpression(opt) && !t.isNullLiteral(opt)) {
+		debug.definePage(`definePage() only supports a function, object literal or null as argument: ${filename}`);
 		return;
 	}
 	return macro;
 }
 /**
-* Extract all import declarations from AST
-* Used to provide necessary imports when executing definePage arguments
+* 从 AST 中提取全部导入声明
+* 用于在执行 definePage 参数时提供必要的导入
 *
-* @param stmts - AST statement array
-* @returns Import declaration array
+* @param stmts - AST 语句数组
+* @returns 导入声明数组
 */
 function findImports(stmts) {
-	const imports = [];
-	for (const stmt of stmts) if (t.isImportDeclaration(stmt)) imports.push(stmt);
-	return imports;
+	return stmts.filter(t.isImportDeclaration);
 }
-//#endregion
-//#region src/context.ts
 /**
-* Page context class responsible for page scanning, config loading, page metadata merging and pages.json generation
+* 从两个 script 块的全部 import 里，挑出宏参数真正用到的那些语句。
 *
-* Core responsibilities:
-* 1. Scan page directories and collect page files
-* 2. Load user configuration files (pages.config.ts, etc.)
-* 3. Parse page metadata (definePage macro)
-* 4. Merge page configurations and generate pages.json
-* 5. Provide virtual module and HMR support
+* 挑选按"名字被宏引用"来：没被用到的 import 不进沙箱，免得为了求值
+* 一个宏，把整个页面的依赖都加载一遍（比如普通 `<script>` 里 import
+* 的 `.vue` 组件，require 加载不动它，还会让本来好好的页面求值失败）。
+* 两个块里写了完全相同的 import 时只留一份，不然编译出的代码会重复
+* 声明同一个名字
 */
-var PageContext = class {
-	_server;
-	/** Parsed configuration object from user config file (pages.config.ts) */
-	pagesGlobConfig;
-	/** Source path list of user configuration files */
-	pagesConfigSourcePaths = [];
-	/** Main package page map, key is the absolute path of the page file */
+function pickEvalImports(allBlocks, macroArg) {
+	const referenced = /* @__PURE__ */ new Set();
+	collectReferencedIdentifiers(macroArg, referenced);
+	const codes = /* @__PURE__ */ new Set();
+	for (const imports of allBlocks) for (const imp of imports) {
+		if (!imp.specifiers.some((spec) => referenced.has(spec.local.name))) continue;
+		codes.add(babelGenerate(imp).code);
+	}
+	return [...codes];
+}
+/**
+* 递归收集节点里出现的标识符名字。
+*
+* 故意宁可多收、不可漏收：`obj.key` 里的 key、`{ style: s }` 里的
+* style 这类"名字位置"的标识符也会被收进来。多收的后果只是多带一条
+* import（那条语句本来就写在用户自己的文件里），漏收才会让宏求值
+* 莫名失败
+*/
+function collectReferencedIdentifiers(node, names) {
+	if (Array.isArray(node)) {
+		for (const item of node) collectReferencedIdentifiers(item, names);
+		return;
+	}
+	if (node === null || typeof node !== "object") return;
+	const astNode = node;
+	if (astNode.type === "Identifier") {
+		names.add(astNode.name);
+		return;
+	}
+	if (astNode.type === "MemberExpression" && !astNode.computed) {
+		collectReferencedIdentifiers(astNode.object, names);
+		return;
+	}
+	if (astNode.type === "ObjectProperty" && !astNode.computed) {
+		collectReferencedIdentifiers(astNode.value, names);
+		return;
+	}
+	for (const [key, value] of Object.entries(astNode)) {
+		if (key === "loc") continue;
+		collectReferencedIdentifiers(value, names);
+	}
+}
+/**
+* 将 TypeScript / JavaScript 脚本代码转换为对象/函数
+*
+* @param options - 脚本执行所需配置
+* @param options.imports - 需要包含的模块导入语句列表
+* @param options.code - 待执行的 TypeScript 代码内容
+* @param options.filename - 用于错误定位与上下文的脚本文件名
+* @returns 脚本执行结果，export 为函数时会执行并返回其返回值
+*/
+async function parseCode(options) {
+	const { imports = [], code, filename } = options;
+	let jsCode = "";
+	try {
+		const tmpCode = `${imports.join("\n")}\n export default ${code}`;
+		jsCode = ts.transpileModule(tmpCode, {
+			compilerOptions: {
+				module: ts.ModuleKind.CommonJS,
+				target: ts.ScriptTarget.ES2022,
+				noEmit: true,
+				strict: false,
+				noImplicitAny: false,
+				strictNullChecks: false,
+				strictFunctionTypes: false,
+				strictBindCallApply: false,
+				strictPropertyInitialization: false,
+				noImplicitThis: false,
+				alwaysStrict: false,
+				allowJs: true,
+				checkJs: false,
+				skipLibCheck: true,
+				esModuleInterop: true,
+				removeComments: true
+			},
+			jsDocParsingMode: ts.JSDocParsingMode.ParseNone
+		}).outputText;
+		const dir = path.dirname(filename);
+		const vmContext = {
+			module: {},
+			exports: {},
+			__filename: filename,
+			__dirname: dir,
+			require: createRequire(path.join(dir, "define-page.mjs")),
+			import: (id) => import(id),
+			setTimeout,
+			clearTimeout,
+			setInterval,
+			clearInterval,
+			setImmediate,
+			clearImmediate,
+			console,
+			URL,
+			URLSearchParams,
+			performance,
+			global: globalThis,
+			globalThis
+		};
+		await new vm.Script(jsCode, { filename }).runInNewContext(vmContext, { timeout: 1e3 });
+		const exportsObj = vmContext.exports;
+		return "default" in exportsObj ? exportsObj.default : exportsObj;
+	} catch (error) {
+		throw new Error(`EXEC SCRIPT FAIL IN ${filename}: ${error.message} \n\n${jsCode}\n\n`);
+	}
+}
+//#endregion
+//#region src/page.ts
+/**
+* 表示一个 Vue 页面文件的 Page 类
+*
+* 职责：
+* 1. 读取页面文件内容
+* 2. 解析 definePage 宏定义的页面配置
+* 3. 提供 tabBar 配置信息
+* 4. 跟踪页面文件变更状态
+*/
+var Page = class {
+	/** 页面上下文实例 */
+	ctx;
+	/** 页面路径信息，包含相对路径与绝对路径 */
+	path;
+	/** 页面 URI，用于 pages.json 的 path 字段 */
+	uri;
+	/** 页面是否发生变化，用于增量更新判断 */
+	changed = true;
+	/**
+	* 页面是否通过 `definePage(null)` 或函数式宏在当前平台返回 null 而
+	* 退出了 pages.json
+	*/
+	skipped = false;
+	/** 页面文件是否至少被读取过一次 */
+	loaded = false;
+	/** 页面配置的原始 JSON 字符串，用于变更检测 */
+	raw = "";
+	/** 解析后的页面配置 */
+	meta;
+	/**
+	* 创建页面实例
+	* @param ctx - 页面上下文实例
+	* @param path - 页面路径信息
+	*/
+	constructor(ctx, path) {
+		this.ctx = ctx;
+		this.path = path;
+		const ext = extname(path.relativePath);
+		this.uri = normalizePath(ext ? path.relativePath.slice(0, -ext.length) : path.relativePath);
+	}
+	/**
+	* 获取页面配置
+	* 解析 definePage 宏定义的配置并返回用于 pages.json 的配置
+	*
+	* @param forceUpdate - 是否强制更新，忽略缓存
+	* @returns 页面配置对象
+	*/
+	async getPageMeta(forceUpdate = false) {
+		if (forceUpdate || !this.loaded) await this.read();
+		const { path, tabBar: _, ...others } = this.meta || {};
+		return {
+			path: path ?? this.uri,
+			...others
+		};
+	}
+	/**
+	* 获取页面 tabBar 配置
+	* 从 definePage 宏中提取 tabBar 相关配置
+	*
+	* @param forceUpdate - 是否强制更新，忽略缓存
+	* @returns tabBar 配置对象，页面未定义 tabBar 时返回 undefined
+	*/
+	async getTabBar(forceUpdate = false) {
+		if (forceUpdate || !this.loaded) await this.read();
+		if (this.skipped) return void 0;
+		const { tabBar } = this.meta || {};
+		if (tabBar === void 0) return;
+		return {
+			...tabBar,
+			pagePath: tabBar.pagePath || this.uri,
+			index: tabBar.index ?? 0
+		};
+	}
+	/**
+	* 确保页面文件至少被读取过一次，使 `skipped` 与缓存的配置反映
+	* 当前文件内容
+	*/
+	async ensureLoaded() {
+		if (!this.loaded) await this.read();
+	}
+	/**
+	* 检查页面是否发生变化
+	* @returns 页面是否发生变化
+	*/
+	hasChanged() {
+		return this.changed;
+	}
+	/**
+	* 读取页面文件并解析配置
+	* 从 Vue SFC 中提取 definePage 宏定义的配置
+	*/
+	async read() {
+		let meta;
+		let skipped = false;
+		try {
+			const result = await this.readPageMetaFromFile();
+			if (result === null) skipped = true;
+			else meta = result;
+		} catch (err) {
+			debug.error(err);
+			this.ctx.logger?.warn(err?.message ?? String(err), { timestamp: true });
+			return;
+		}
+		let raw = "";
+		try {
+			raw = JSON.stringify(meta) ?? "";
+		} catch {}
+		this.changed = this.raw !== raw || this.skipped !== skipped;
+		this.loaded = true;
+		this.meta = meta;
+		this.raw = raw;
+		this.skipped = skipped;
+	}
+	async readPageMetaFromFile() {
+		try {
+			const meta = await evaluateDefinePage(await fs.promises.readFile(this.path.absolutePath, { encoding: "utf-8" }), this.path.absolutePath, this.ctx.platform);
+			return meta === void 0 ? { type: "page" } : meta;
+		} catch (err) {
+			throw new Error(`Read page meta fail in ${this.path.relativePath}\n${err.message}`);
+		}
+	}
+};
+//#endregion
+//#region src/platform-variants.ts
+/**
+* 把 `||` 分隔的平台列表拆开，去掉当前平台，剩下的排好序（规则 1）
+*
+* 空平台名一律丢掉：残缺的生成标记行（手改时把平台列表删空了）和
+* 手写的尾巴多一个分隔符的指令（如 `#ifdef H5 ||`）都会拆出空串。
+* 若留着它，它会混进平台全集并永久留在标记里，还会让条目包上
+* `#ifdef  || MP-WEIXIN` 这样的非法指令（空平台名不是一个真实平台，
+* 过滤掉永远不会出错）
+*/
+function platformsExcluding(platformList, currentPlatform) {
+	return platformList.split("||").map((p) => p.trim()).filter((p) => p && p !== currentPlatform).sort();
+}
+/**
+* 把本次运行的一个载荷并入变体列表（规则 2）：
+* - 内容相同的手写 #ifndef 变体优先：当前平台没被排除时，那条
+*   #ifndef 已经覆盖了它；当前平台正好被排除时，尊重手写的隐藏规
+*   则。两种情况下再单独写一份都会产生重复路由或覆盖用户的条件
+* - 内容相同的普通变体：当前平台叠进它的平台列表
+* - 没有内容相同的变体：新建只属于当前平台的变体
+*
+* @param variants - 同一个键下已有的变体列表，原地修改
+* @param payload - 本次运行的载荷
+* @param valueStr - 载荷的比较字符串
+* @param currentPlatform - 当前平台标识（大写）
+* @param compatible - 可选的额外相容判断。数组侧用它区分两个平台各自
+* 声明的不同首页：内容相同但首页标记冲突时不合并
+*/
+function upsertCurrentVariant(variants, payload, valueStr, currentPlatform, compatible) {
+	const isSame = (variant) => variant.valueStr === valueStr && (compatible ? compatible(variant.payload, payload) : true);
+	if (variants.some((variant) => variant.platforms === null && isSame(variant))) return;
+	const equal = variants.find((variant) => variant.platforms !== null && isSame(variant));
+	if (equal) {
+		equal.platforms.push(currentPlatform);
+		equal.platforms.sort();
+		equal.platformStr = equal.platforms.join(" || ");
+		return;
+	}
+	variants.push({
+		payload,
+		valueStr,
+		platforms: [currentPlatform],
+		platformStr: currentPlatform
+	});
+}
+/**
+* 输出前按平台列表把变体排好序（规则 4）
+*
+* 当前平台的变体在收集时被排除、并入时又补到列表末尾，两个平台轮流
+* 运行（dev:h5 和 dev:mp-weixin 交替写）时，同一个键的变体顺序就会
+* 来回翻转——条件编译的结果没变，但文件每次都有无意义的变动。
+* platformStr 由排好序的平台列表拼成，手写 #ifndef 变体是空串、排最
+* 前。排序是稳定的：并列时（同键两组平台列表相同，只出现在手写文件
+* 里）保持收集顺序
+*/
+function sortVariants(variants) {
+	variants.sort((a, b) => a.platformStr < b.platformStr ? -1 : a.platformStr > b.platformStr ? 1 : 0);
+}
+/**
+* 收集所有变体记录过的平台（手写 #ifndef 不算，它没有正向列表），
+* 这个集合同时也是「拥有至少一个变体」的平台集合
+*/
+function collectVariantPlatforms(mergedMap) {
+	const platforms = /* @__PURE__ */ new Set();
+	for (const variants of mergedMap.values()) for (const { platforms: variantPlatforms } of variants) if (variantPlatforms) for (const platform of variantPlatforms) platforms.add(platform);
+	return platforms;
+}
+/**
+* 把所有变体记录的平台合在一起，算出「平台全集」
+*
+* 平台全集会写进生成标记，也决定哪些变体可以不加 #ifdef 直接输出：
+* 没被包裹的条目在 uni-app 条件编译下所有平台都看得见，所以只有
+* 覆盖了全部平台的变体才能"裸着"输出（规则 5）。
+*
+* 当前平台一定在全集里，哪怕这次运行一个变体都没贡献——比如页面
+* 只在 H5 存在，而 MP-WEIXIN 运行把每个页面都 definePage(null) 掉了。
+* 如果只从剩下的条目推全集，全集就只有 'H5'，H5 专属条目看起来
+* "覆盖了全集"，会不加包裹地输出，泄漏进微信的构建产物。老版本按
+* "最常用平台组合当默认值"的做法也有同样的问题：可能算出单平台
+* 组合，把那个平台的条目裸着输出，变成其他平台里的重复路由。这个
+* 全集同样管着 tabBar 属性的包裹：没有它，一次没有 tabBar 的运行
+* 会以为"拥有平台 == 全集"，把别的平台的 tabBar 裸着输出出去。
+*
+* 上一次运行记在标记里的平台也进全集（{@link extractLastPlatforms}）。
+* 否则当某平台的条目都被重新扫描替换后，它"来过"这件事只记在标记
+* 里：只看条目推全集，全集会一会儿大一会儿小，条目一会儿包一会儿
+* 裸。把标记也算进来，全集就只增不减；多算的平台最多带来多余的包
+* 裹，不会泄漏。
+*
+* 只增不减的代价：彻底不用的平台会一直留在标记里。这无害，但别
+* 手工去改标记行——想清理就删掉整个生成的 pages.json，下次运行会
+* 从头生成。
+*/
+function resolvePlatformUnion(mergedMap, currentPlatform, lastPlatforms) {
+	return [.../* @__PURE__ */ new Set([
+		currentPlatform,
+		...lastPlatforms,
+		...collectVariantPlatforms(mergedMap)
+	])].sort();
+}
+const GENERATION_MARKER_PREFIX = "GENERATED BY UNI-PAGES, PLATFORM:";
+/** 判断注释令牌是否为 pages.json 的生成标记行 */
+function isGenerationMarker(token) {
+	return token.type !== "BlankLine" && typeof token.value === "string" && token.value.trim().startsWith("GENERATED BY UNI-PAGES, PLATFORM:");
+}
+/** 判断一个 pages 数组是否由插件写入（携带生成标记） */
+function hasGenerationMarker(src) {
+	if (!src) return false;
+	return (src[Symbol.for("before:0")] || []).some(isGenerationMarker);
+}
+/**
+* 从 before:0 的生成标记里读出上一次运行记录了哪些平台，
+* 去掉当前平台后返回
+*/
+function extractLastPlatforms(src, currentPlatform) {
+	let lastPlatforms = [];
+	for (const comment of src[Symbol.for("before:0")] || []) {
+		if (comment.type === "BlankLine") continue;
+		const trimmed = comment.value.trim();
+		if (trimmed.startsWith("GENERATED BY UNI-PAGES, PLATFORM:")) lastPlatforms = platformsExcluding(trimmed.split(":")[1], currentPlatform);
+	}
+	return lastPlatforms;
+}
+//#endregion
+//#region src/jsonc-scan.ts
+/**
+* 跳过空白和注释往前走。遇到行注释或块注释时，注释里的文字（去掉
+* 首尾空白）会收集到 `comments` 里（如果传了）
+*/
+function skipJsoncFiller(content, index, comments) {
+	let i = index;
+	while (i < content.length) {
+		const ch = content[i];
+		if (ch === " " || ch === "	" || ch === "\r" || ch === "\n") {
+			i++;
+			continue;
+		}
+		if (ch === "/" && content[i + 1] === "/") {
+			const end = content.indexOf("\n", i);
+			const stop = end === -1 ? content.length : end;
+			comments?.push(content.slice(i + 2, stop).trim());
+			i = stop;
+			continue;
+		}
+		if (ch === "/" && content[i + 1] === "*") {
+			const end = content.indexOf("*/", i + 2);
+			const stop = end === -1 ? content.length : end + 2;
+			comments?.push(content.slice(i + 2, end === -1 ? content.length : end).trim());
+			i = stop;
+			continue;
+		}
+		return i;
+	}
+	return i;
+}
+/** 从起始引号扫描 JSON 字符串字面量；返回闭合引号之后的下标 */
+function scanJsonString(content, start) {
+	let i = start + 1;
+	while (i < content.length) {
+		if (content[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (content[i] === "\"") return i + 1;
+		i++;
+	}
+	return content.length;
+}
+/** 扫描 `start` 处（定位在值的首字符）的 JSON 值；返回其后的下标 */
+function scanJsonValue(content, start) {
+	const ch = content[start];
+	if (ch === "\"") return scanJsonString(content, start);
+	if (ch === "{" || ch === "[") {
+		let depth = 0;
+		let i = start;
+		while (i < content.length) {
+			const c = content[i];
+			if (c === "\"") {
+				i = scanJsonString(content, i);
+				continue;
+			}
+			if (c === "/" && (content[i + 1] === "/" || content[i + 1] === "*")) {
+				i = skipJsoncFiller(content, i);
+				continue;
+			}
+			if (c === "{" || c === "[") {
+				depth++;
+				i++;
+				continue;
+			}
+			if (c === "}" || c === "]") {
+				depth--;
+				i++;
+				if (depth === 0) return i;
+				continue;
+			}
+			i++;
+		}
+		return content.length;
+	}
+	let i = start;
+	while (i < content.length && !",{}[] 	\r\n\"".includes(content[i])) i++;
+	return i;
+}
+/** 读取 `start` 处（其起始引号）的 JSON 字符串字面量；返回解析文本与其后的下标 */
+function readJsonStringToken(content, start) {
+	const end = scanJsonString(content, start);
+	try {
+		return [JSON.parse(content.slice(start, end)), end];
+	} catch {
+		return null;
+	}
+}
+/**
+* 按文本扫描 pages.json 里的 tabBar 对象，把每个顶层属性连同它的
+* 条件编译包裹一起收集起来。
+*
+* 为什么要按文本扫：comment-json 解析时会按普通 JS 对象的规则，
+* 同一个键出现多次只留最后一个，而"同一个属性按平台写多个值"靠的
+* 就是重复键。
+* 这些信息一旦解析就丢了，所以必须从原始文本里捞回来。
+* tabBar 不是对象、或文件结构看不懂时返回 undefined。
+*/
+function extractTabBarProps(content) {
+	let i = skipJsoncFiller(content, 0);
+	if (content[i] !== "{") return void 0;
+	i = skipJsoncFiller(content, i + 1);
+	while (i < content.length) {
+		if (content[i] === "}" || content[i] !== "\"") return void 0;
+		const token = readJsonStringToken(content, i);
+		if (!token) return void 0;
+		const [key, keyEnd] = token;
+		i = skipJsoncFiller(content, keyEnd);
+		if (content[i] !== ":") return void 0;
+		i = skipJsoncFiller(content, i + 1);
+		if (key === "tabBar") {
+			if (content[i] !== "{") return void 0;
+			return parseTabBarProps(content, i + 1);
+		}
+		i = skipJsoncFiller(content, scanJsonValue(content, i));
+		if (content[i] === ",") i = skipJsoncFiller(content, i + 1);
+		else if (content[i] !== "}") return void 0;
+	}
+}
+/** 从 tabBar 对象起始 `{` 之后开始解析其内部 */
+function parseTabBarProps(content, interiorStart) {
+	const props = /* @__PURE__ */ new Map();
+	let beforeComments = [];
+	let i = skipJsoncFiller(content, interiorStart, beforeComments);
+	const openConditions = [];
+	const applyCommentsToStack = (comments) => {
+		for (const comment of comments) {
+			const trimmed = comment.trim();
+			if (trimmed.startsWith("#endif")) openConditions.pop();
+			else if (trimmed.startsWith("#ifdef") || trimmed.startsWith("#ifndef")) openConditions.push(trimmed);
+		}
+	};
+	applyCommentsToStack(beforeComments);
+	while (true) {
+		if (i >= content.length) return void 0;
+		if (content[i] === "}") return props;
+		if (content[i] === ",") {
+			const postComma = [];
+			i = skipJsoncFiller(content, i + 1, postComma);
+			applyCommentsToStack(postComma);
+			beforeComments = postComma;
+			continue;
+		}
+		if (content[i] !== "\"") return void 0;
+		const token = readJsonStringToken(content, i);
+		if (!token) return void 0;
+		const [key, keyEnd] = token;
+		i = skipJsoncFiller(content, keyEnd);
+		if (content[i] !== ":") return void 0;
+		i = skipJsoncFiller(content, i + 1);
+		const valueEnd = scanJsonValue(content, i);
+		const rawValue = content.slice(i, valueEnd);
+		const afterComments = [];
+		i = skipJsoncFiller(content, valueEnd, afterComments);
+		if (content[i] !== "," && content[i] !== "}") return void 0;
+		const condition = openConditions[openConditions.length - 1] ?? null;
+		applyCommentsToStack(afterComments);
+		try {
+			const value = parse(rawValue);
+			let storedBefore = [...beforeComments];
+			let storedAfter = afterComments;
+			if (condition?.startsWith("#ifndef")) {
+				storedBefore = [condition, ...beforeComments.filter((c) => !/^#(?:ifdef|ifndef|endif)/.test(c.trim()))];
+				storedAfter = ["#endif", ...afterComments.filter((c) => !c.trim().startsWith("#endif"))];
+			}
+			const raw = {
+				key,
+				value,
+				condition,
+				beforeComments: storedBefore,
+				afterComments: storedAfter
+			};
+			const variants = props.get(key) || [];
+			variants.push(raw);
+			props.set(key, variants);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/tab-bar.ts
+/**
+* 跨平台合并 tabBar 的外观属性（`list` 以外的所有属性）。
+* 规则见 platform-variants.ts（和数组侧的 mergePlatformItems 共用）：
+* - 包在 #ifdef 里的属性，属于注释里列出的那些平台
+* - 没包裹的属性，属于除当前平台外的所有平台（当前平台会写自己的）
+* - 一个值最后一个平台都不剩了，就删掉它
+* - 手写的 #ifndef 属性原样保留、永不删除，和数组侧的处理一致
+*/
+function mergeTabBarProps(existingContent, currentProps, contributesProps, currentPlatform, platformUnion) {
+	const rawProps = extractTabBarProps(existingContent);
+	const merged = /* @__PURE__ */ new Map();
+	const variantsOf = (key) => {
+		const list = merged.get(key) || [];
+		merged.set(key, list);
+		return list;
+	};
+	for (const [key, variants] of rawProps || []) {
+		if (key === "list") continue;
+		for (const raw of variants) {
+			const valueStr = JSON.stringify(raw.value);
+			if (valueStr === void 0) continue;
+			if (raw.condition?.startsWith("#ifndef")) {
+				variantsOf(key).push({
+					payload: raw.value,
+					valueStr,
+					platforms: null,
+					platformStr: "",
+					passthrough: {
+						before: raw.beforeComments,
+						after: raw.afterComments
+					}
+				});
+				continue;
+			}
+			let platforms;
+			if (raw.condition?.startsWith("#ifdef")) platforms = platformsExcluding(raw.condition.slice(6).trim(), currentPlatform);
+			else platforms = platformUnion.filter((p) => p !== currentPlatform);
+			if (platforms.length === 0) continue;
+			variantsOf(key).push({
+				payload: raw.value,
+				valueStr,
+				platforms,
+				platformStr: platforms.join(" || "),
+				passthrough: null
+			});
+		}
+	}
+	if (contributesProps) for (const [key, value] of Object.entries(currentProps)) {
+		const valueStr = JSON.stringify(value);
+		if (valueStr === void 0) continue;
+		upsertCurrentVariant(variantsOf(key), value, valueStr, currentPlatform);
+	}
+	for (const variants of merged.values()) sortVariants(variants);
+	return merged;
+}
+/** 一层缩进是多少（空格数或字符串） */
+function indentUnitOf(format) {
+	const indent = format?.indent ?? 2;
+	return typeof indent === "number" ? " ".repeat(indent) : indent;
+}
+/** 给除第一行以外的每一行加缩进（用于多行值拼进属性行的场景） */
+function indentContinuation(text, extra) {
+	return text.split("\n").map((line, index) => index === 0 ? line : extra + line).join("\n");
+}
+/**
+* 把 tabBar 外观属性渲染成带缩进的输出行。所有平台都适用的值直接
+* 输出；其余每个值都写在自己的 `#ifdef` 块里（同一个键出现多次），
+* uni-app 按平台剥掉注释后，每个平台只会看到一个值。
+*/
+function renderTabBarPropLines(merged, platformUnion, format) {
+	const unit = indentUnitOf(format);
+	const unionStr = platformUnion.join(" || ");
+	const lines = [];
+	for (const [key, variants] of merged) for (const variant of variants) {
+		const valueText = indentContinuation(stringify(variant.payload, null, format?.indent ?? 2), unit + unit);
+		const propLine = `${unit}${unit}${JSON.stringify(key)}: ${valueText},`;
+		if (variant.passthrough) {
+			for (const comment of variant.passthrough.before) if (comment) lines.push(`${unit}${unit}// ${comment}`);
+			lines.push(propLine);
+			for (const comment of variant.passthrough.after) if (comment) lines.push(`${unit}${unit}// ${comment}`);
+			continue;
+		}
+		if (variant.platformStr === unionStr) lines.push(propLine);
+		else {
+			lines.push(`${unit}${unit}// #ifdef ${variant.platformStr}`);
+			lines.push(propLine);
+			lines.push(`${unit}${unit}// #endif`);
+		}
+	}
+	return lines;
+}
+/** 把合并后的 tabBar list 渲染成带缩进的输出行（list 总是 tabBar 的最后一个属性） */
+function renderTabBarListLines(list, format) {
+	const unit = indentUnitOf(format);
+	return stringify(list, null, format?.indent ?? 2).split("\n").map((line, index) => {
+		if (index === 0) return `${unit}${unit}"list": ${line}`;
+		return line === "" ? line : unit + unit + line;
+	});
+}
+//#endregion
+//#region src/pages-json.ts
+/**
+* tabBar 主体以文本方式渲染时，先在对象里放这个占位符序列化，最后
+* 再把渲染好的正文拼上去：按平台区分的属性需要同一个键出现多次，
+* comment-json 的对象做不到这一点，只能不用它、自己拼字符串
+* （见 {@link mergePagesJson}）
+*/
+const TAB_BAR_PLACEHOLDER = "@@uni-pages-tab-bar-placeholder@@";
+/**
+* 把路由数据合并进 pages.json 并写回
+*
+* 整个"读取 → 合并 → 写回"都锁在同一把文件锁里：因为新内容要参考
+* 当前文件里其他平台的 `#ifdef` 块，两个终端同时跑（比如
+* dev:mp-weixin + dev:mp-alipay）时才不会互相覆盖或读到写了一半的
+* 内容。写入用临时文件 + rename，中途崩溃也不会留下截断的文件。
+*
+* @param jsonPath - pages.json 文件路径
+* @param data - 由扫描/合并流水线组装的路由数据
+* @param options - 平台、用户配置与序列化格式
+* @returns 写入结果；获取不到文件锁时为 undefined
+*/
+async function writePagesJson(jsonPath, data, options) {
+	return withFileLock(jsonPath, async () => {
+		const existingContent = await fs.promises.readFile(jsonPath, { encoding: "utf-8" }).catch(() => "");
+		const content = mergePagesJson(existingContent, data, options);
+		if (existingContent === content) {
+			debug.pages("PagesJson Not have change");
+			return {
+				updated: false,
+				content
+			};
+		}
+		await writeFileAtomic(jsonPath, content);
+		return {
+			updated: true,
+			content
+		};
+	});
+}
+/**
+* 根据现有文件内容计算合并后的 pages.json 对象
+*
+* @returns pages.json 对象；美化输出模式下附带预渲染的 tabBar 主体
+* 行，用于替换序列化出的占位符（见 {@link mergePagesJson}）；
+* 为 undefined 表示没有 tabBar 或为紧凑输出
+*/
+function mergeIntoPagesJson(existingContent, data, options) {
+	let oldConfig;
+	try {
+		oldConfig = parse(existingContent || "{}");
+	} catch (error) {
+		throw new Error(`[vite-plugin-uni-pages] Failed to parse the existing pages.json, please fix its syntax first: ${error?.message ?? error}`, { cause: error });
+	}
+	const { pages: oldPages, subPackages: oldSubPackages, tabBar: oldTabBar } = oldConfig;
+	for (const [field, value] of Object.entries({
+		pages: oldPages,
+		subPackages: oldSubPackages
+	})) if (value != null && !Array.isArray(value)) throw new Error(`[vite-plugin-uni-pages] The "${field}" in the existing pages.json must be an array, please fix its syntax first`);
+	const { pages: _pages, subPackages: _subPackages, tabBar: _tabBar, ...pageJson } = options.globConfig || {};
+	const currentPlatform = options.platform.toUpperCase();
+	pageJson.pages = mergePlatformItems(oldPages, currentPlatform, data.pages, "path").items;
+	ensureHomePageFirst(pageJson.pages, data.homePath);
+	pageJson.subPackages = oldSubPackages || new CommentArray();
+	const newSubPackages = /* @__PURE__ */ new Map();
+	for (const item of data.subPackages) newSubPackages.set(item.root, item);
+	const subPackagesArray = pageJson.subPackages;
+	const staleRoots = [];
+	for (const existing of subPackagesArray) {
+		const sub = newSubPackages.get(existing.root);
+		if (sub) {
+			const wasGenerated = hasGenerationMarker(existing.pages);
+			existing.pages = mergePlatformItems(existing.pages, currentPlatform, sub.pages, "path").items;
+			if (sub.plugins) existing.plugins = sub.plugins;
+			else if (wasGenerated) Reflect.deleteProperty(existing, "plugins");
+			newSubPackages.delete(existing.root);
+		} else if (hasGenerationMarker(existing.pages)) staleRoots.push(existing.root);
+	}
+	for (let i = subPackagesArray.length - 1; i >= 0; i--) {
+		const existing = subPackagesArray[i];
+		if (!staleRoots.includes(existing.root)) continue;
+		debug.subPages(`Removing converged sub-package root: ${existing.root}`);
+		Reflect.deleteProperty(subPackagesArray, Symbol.for(`before:${i}`));
+		Reflect.deleteProperty(subPackagesArray, Symbol.for(`after:${i}`));
+		Reflect.deleteProperty(subPackagesArray, Symbol.for(`after-value:${i}`));
+		subPackagesArray.splice(i, 1);
+	}
+	for (const [_, newSub] of newSubPackages) {
+		const subPackage = {
+			root: newSub.root,
+			pages: mergePlatformItems(void 0, currentPlatform, newSub.pages, "path").items
+		};
+		if (newSub.plugins) subPackage.plugins = newSub.plugins;
+		pageJson.subPackages.push(subPackage);
+	}
+	const { list, ...tabBarOthers } = data.tabBar || {};
+	const contributesProps = !!(list && list.length);
+	const oldTabBarObj = oldTabBar;
+	const tabBarMerge = mergePlatformItems(oldTabBarObj?.list, currentPlatform, list || [], "pagePath");
+	let tabBarBodyLines;
+	if (tabBarMerge.items.length === 0) pageJson.tabBar = void 0;
+	else {
+		if (isPrettyFormat(options.format)) {
+			tabBarBodyLines = [...renderTabBarPropLines(mergeTabBarProps(existingContent, tabBarOthers, contributesProps, currentPlatform, tabBarMerge.platformUnion), tabBarMerge.platformUnion, options.format), ...renderTabBarListLines(tabBarMerge.items, options.format)];
+			pageJson.tabBar = TAB_BAR_PLACEHOLDER;
+		} else {
+			const { list: _oldList, ...oldTabBarOthers } = oldTabBarObj || {};
+			pageJson.tabBar = {
+				...contributesProps ? tabBarOthers : oldTabBarOthers,
+				list: tabBarMerge.items
+			};
+		}
+		const tabBarPlatformStr = tabBarMerge.owningPlatforms.join(" || ");
+		if (tabBarPlatformStr && tabBarPlatformStr !== tabBarMerge.platformUnion.join(" || ")) {
+			const commentPageJson = pageJson;
+			commentPageJson[Symbol.for("before:tabBar")] = [lineComment(` #ifdef ${tabBarPlatformStr}`)];
+			commentPageJson[Symbol.for("after:tabBar")] = [lineComment(" #endif")];
+		}
+	}
+	return {
+		pageJson,
+		tabBarBodyLines
+	};
+}
+/**
+* 把所有首页条目移到最前面，注释跟着条目一起移动
+*
+* 每个平台可以在自己的 #ifdef 块里声明自己的首页，没被包裹的条目
+* 所有平台都能看到。所以一个平台的首页必须排在它可见的所有条目
+* 之前。解决办法很简单：把所有平台的首页都放到所有非首页条目的
+* 前面（各组内部顺序不变），一次满足所有平台。
+*
+* 只移动当前平台的首页是不够的：就算它已经在第 0 位，另一个平台的
+* 首页可能还排在它自己可见的某个非首页条目后面。
+*
+* 判断哪些条目是首页：先看条目自带的 `type: 'home'` 标记（扫描出来
+* 的条目都带），再看 homePath 路径兜底（手写条目不带标记）。标记在
+* 合并时不会保留下来，所以每次运行都要重新判断一遍。
+*/
+function ensureHomePageFirst(pagesArray, homePath) {
+	if (!pagesArray || pagesArray.length === 0) return;
+	const isHome = pagesArray.map((page) => page.type === "home");
+	if (homePath && !pagesArray.some((page) => page.path === homePath && page.type === "home")) pagesArray.forEach((page, index) => {
+		if (page.path === homePath) isHome[index] = true;
+	});
+	const homeCount = isHome.filter(Boolean).length;
+	if (homeCount === 0) return;
+	if (isHome.slice(0, homeCount).every(Boolean)) return;
+	const commentArray = pagesArray;
+	const length = pagesArray.length;
+	const beforeTokens = [];
+	const afterTokens = [];
+	for (let i = 0; i < length; i++) {
+		beforeTokens.push(commentArray[Symbol.for(`before:${i}`)] || []);
+		afterTokens.push(commentArray[Symbol.for(`after:${i}`)] || []);
+		Reflect.deleteProperty(commentArray, Symbol.for(`before:${i}`));
+		Reflect.deleteProperty(commentArray, Symbol.for(`after:${i}`));
+	}
+	const markerTokens = beforeTokens[0].filter(isGenerationMarker);
+	beforeTokens[0] = beforeTokens[0].filter((token) => !isGenerationMarker(token));
+	const order = [];
+	for (let i = 0; i < length; i++) if (isHome[i]) order.push(i);
+	for (let i = 0; i < length; i++) if (!isHome[i]) order.push(i);
+	pagesArray.splice(0, length, ...order.map((i) => pagesArray[i]));
+	for (let i = 0; i < length; i++) {
+		const sourceIndex = order[i];
+		const before = i === 0 ? [...markerTokens, ...beforeTokens[sourceIndex]] : beforeTokens[sourceIndex];
+		if (before.length > 0) commentArray[Symbol.for(`before:${i}`)] = before;
+		if (afterTokens[sourceIndex].length > 0) commentArray[Symbol.for(`after:${i}`)] = afterTokens[sourceIndex];
+	}
+}
+/**
+* 判断输出是不是带注释的多行格式（只有多行才放得下按平台区分的
+* `#ifdef` 块）。`indent: 0` 或空字符串会让 comment-json 输出成
+* 单行，这里和它的行为保持一致。
+*/
+function isPrettyFormat(format) {
+	return !(format?.minify ?? false) && !!(format?.indent ?? 2);
+}
+/**
+* 不碰文件系统，只做计算：把路由数据合并进现有 pages.json 文本
+* （多平台 `#ifdef` 块、首页重排、生成标记、过期子包清理）并序列化
+* 成字符串。文件锁、变更检测和原子写入都在 {@link writePagesJson}
+* 里；测试直接用字符串检查这个函数。
+*
+* @param existingContent - 当前 pages.json 文本，没有时传空字符串
+* @param data - 由扫描/合并流水线组装的路由数据
+* @param options - 平台、用户配置与序列化格式
+* @returns 序列化后的 pages.json 内容
+*/
+function mergePagesJson(existingContent, data, options) {
+	const { pageJson, tabBarBodyLines } = mergeIntoPagesJson(existingContent, data, options);
+	const minify = options.format?.minify ?? false;
+	const indent = options.format?.indent ?? 2;
+	const eol = options.format?.eol ?? "\n";
+	let content = stringify(pageJson, null, minify ? void 0 : indent);
+	if (tabBarBodyLines) {
+		const unit = typeof indent === "number" ? " ".repeat(indent) : indent;
+		content = content.replace(`"tabBar": ${JSON.stringify(TAB_BAR_PLACEHOLDER)}`, () => `"tabBar": {\n${tabBarBodyLines.join("\n")}\n${unit}}`);
+	}
+	if (eol !== "\n") content = content.replaceAll("\n", eol);
+	if (options.format?.insertFinalNewline) content += eol;
+	return content;
+}
+/** 构建用于序列化 pages.json 输出的行注释令牌 */
+function lineComment(value) {
+	return {
+		type: "LineComment",
+		value,
+		inline: false,
+		loc: {
+			start: {
+				line: 0,
+				column: 0
+			},
+			end: {
+				line: 0,
+				column: 0
+			}
+		}
+	};
+}
+/**
+* 把条目转成字符串用于比较，比较前要先把内部的 `type` 标记
+* （'home' | 'page'）拿掉。
+*
+* 从 pages.json 读回来的条目可能没有这个标记（手写条目从不带它），
+* 直接 JSON.stringify 会把同一个页面当成两个不同的条目，多平台
+* 运行时就会生成重复的路由
+* （见 https://github.com/uni-helper/vite-plugin-uni-pages/issues/283）。
+*
+* 键的顺序也参与比较（JSON.stringify 按写入顺序输出）：同一页面在
+* 两个平台下键序不同时不会被合并，会各占一个 #ifdef 块留在文件
+* 里。代价只是文件里多一份内容相同的变体，构建时每个平台仍然只看
+* 得见自己那一条、不会出现重复路由，不值得为它做键序归一化。
+*/
+function stringifyForCompare(val) {
+	if ("type" in val) {
+		const { type: _type, ...rest } = val;
+		return JSON.stringify(rest);
+	}
+	return JSON.stringify(val);
+}
+/**
+* 两个内容相同的条目，首页状态是否一致？
+*
+* `type` 标记不参与内容比较（见 stringifyForCompare），没有标记的
+* 条目也能和扫描到的条目合并。但如果两边都明确带着标记、而且一个
+* 是 'home' 一个是 'page'，说明这是两个平台各自声明的不同首页，
+* 必须作为两个条目待在各自的 #ifdef 块里，不能合并成一条——之前
+* 的合并正是"切换首页后旧首页标记残留、某个平台的首页声明被悄悄
+* 丢掉"这两个 bug 的根源。
+*/
+function homeStatusCompatible(a, b) {
+	const typeA = a.type;
+	const typeB = b.type;
+	return typeA === void 0 || typeB === void 0 || typeA === typeB;
+}
+/**
+* 合并多平台的配置条目（数组侧适配器）。
+*
+* 处理条件编译注释（#ifdef / #ifndef / #endif），把 pages.json 里
+* 已有的条目和本次扫描的条目合并成一个数组；合并规则（同值叠平台、
+* 排除当前平台、排序、并集）用 platform-variants.ts 的共享核心：
+* - 内容相同的条目自动合并，平台标识叠在一起
+* - 内容不同的条目各写各的 #ifdef 块
+* - 手写的 `#ifndef` 块原样保留：否定条件翻译不成正向平台列表，
+*   所以条目连同原始包裹一起输出，永不修改、也永不清理
+*
+* @param source - 现有条目数组（来自 pages.json）
+* @param currentPlatform - 当前平台标识（如 H5、MP-WEIXIN）
+* @param items - 新配置条目数组
+* @param uniqueKeyName - 用于识别条目唯一性的字段名（如 'path' 或 'pagePath'）
+* @returns 带 #ifdef 块的合并条目，以及平台全集与拥有平台
+*/
+function mergePlatformItems(source, currentPlatform, items, uniqueKeyName) {
+	const src = source || new CommentArray();
+	currentPlatform = currentPlatform.toUpperCase();
+	const lastPlatforms = extractLastPlatforms(src, currentPlatform);
+	const mergedMap = /* @__PURE__ */ new Map();
+	const variantsOf = (uniqueKey) => {
+		const list = mergedMap.get(uniqueKey) || [];
+		mergedMap.set(uniqueKey, list);
+		return list;
+	};
+	for (let i = 0; i < src.length; i++) {
+		const item = src[i];
+		const uniqueKey = item[uniqueKeyName];
+		if (!uniqueKey) continue;
+		const beforeComments = src[Symbol.for(`before:${i}`)];
+		const conditionalComment = beforeComments?.find((c) => c.type !== "BlankLine" && /^#(?:ifdef|ifndef)/.test(c.value.trim()));
+		if (conditionalComment?.value.trim().startsWith("#ifndef")) {
+			variantsOf(uniqueKey).push({
+				payload: item,
+				valueStr: stringifyForCompare(item),
+				platforms: null,
+				platformStr: "",
+				passthrough: {
+					before: [...beforeComments || []].filter((c) => !isGenerationMarker(c)),
+					after: [lineComment(" #endif")]
+				}
+			});
+			continue;
+		}
+		let platforms = [...lastPlatforms];
+		if (conditionalComment) {
+			const match = conditionalComment.value.match(/#ifdef\s+(.+)/);
+			if (match) platforms = platformsExcluding(match[1], currentPlatform);
+		}
+		if (platforms.length === 0) continue;
+		variantsOf(uniqueKey).push({
+			payload: item,
+			valueStr: stringifyForCompare(item),
+			platforms,
+			platformStr: platforms.join(" || ")
+		});
+	}
+	for (const item of items) {
+		const uniqueKey = item[uniqueKeyName];
+		if (!uniqueKey) continue;
+		upsertCurrentVariant(variantsOf(uniqueKey), item, stringifyForCompare(item), currentPlatform, homeStatusCompatible);
+	}
+	const result = new CommentArray();
+	for (const variants of mergedMap.values()) sortVariants(variants);
+	const platformUnion = resolvePlatformUnion(mergedMap, currentPlatform, lastPlatforms);
+	const platformUnionStr = platformUnion.join(" || ");
+	const owningPlatforms = collectVariantPlatforms(mergedMap);
+	result[Symbol.for("before:0")] = [lineComment(` ${GENERATION_MARKER_PREFIX} ${platformUnionStr}`)];
+	for (const [_, list] of mergedMap) for (const { payload: item, platformStr, passthrough } of list) {
+		result.push(item);
+		if (passthrough) {
+			result[Symbol.for(`before:${result.length - 1}`)] = [...result[Symbol.for(`before:${result.length - 1}`)] || [], ...passthrough.before];
+			if (passthrough.after.length > 0) result[Symbol.for(`after:${result.length - 1}`)] = passthrough.after;
+			continue;
+		}
+		if (platformStr !== platformUnionStr) {
+			result[Symbol.for(`before:${result.length - 1}`)] = [...result[Symbol.for(`before:${result.length - 1}`)] || [], lineComment(` #ifdef ${platformStr}`)];
+			result[Symbol.for(`after:${result.length - 1}`)] = [lineComment(" #endif")];
+		}
+	}
+	return {
+		items: result,
+		platformUnion,
+		owningPlatforms: [...owningPlatforms].sort()
+	};
+}
+//#endregion
+//#region src/context.ts
+/**
+* 页面上下文：负责扫描页面、加载配置、合并页面信息、生成 pages.json
+*
+* 做的事情按固定顺序是：加载用户配置 → 扫描页面文件 → 合并页面
+* 信息 → 写入 pages.json。这个顺序由 {@link updatePagesJSON}（完整
+* 流程）或 {@link scanAndMerge}（只算不写）管理，调用方不用关心
+* 内部步骤。
+*/
+var PageContext = class {
+	_server;
+	/** 从用户配置文件（pages.config.ts）解析出的配置对象 */
+	pagesGlobConfig;
+	/** 用户配置文件的来源路径列表 */
+	pagesConfigSourcePaths = [];
+	/** 主包页面映射，键为页面文件的绝对路径 */
 	pages = /* @__PURE__ */ new Map();
-	/** Sub-package page map, key is the sub-package root directory, value is the page map under that sub-package */
+	/** 子包页面映射，键为子包根目录，值为该子包下的页面映射 */
 	subPages = /* @__PURE__ */ new Map();
-	/** Main package page metadata array for generating pages.json pages field */
+	/** 主包页面配置数组，用于生成 pages.json 的 pages 字段 */
 	pageMetaData = [];
-	/** Sub-package page metadata array for generating pages.json subPackages field */
+	/** 子包页面配置数组，用于生成 pages.json 的 subPackages 字段 */
 	subPageMetaData = [];
-	/** Generated pages.json file path */
+	/**
+	* 最近一次合并出的 tabBar（配置文件与 definePage 声明的合体）。
+	* 类型声明生成 tab 页列表时用它，definePage 声明的 tabBar 页才能
+	* 一起从 navigateTo 的 url 类型里排除
+	*/
+	tabBar;
+	/** 生成的 pages.json 文件路径 */
 	resolvedPagesJSONPath = "";
-	resolvedPagesJSONIndent;
-	resolvedPagesJSONNewline;
-	resolvedPagesJSONEofNewline;
-	/** Original options passed by the user */
-	rawOptions;
-	/** Project root directory */
+	/** 项目根目录 */
 	root;
-	/** Resolved configuration options */
+	/** 解析后的配置项 */
 	options;
+	/** 当前平台标识，如 'mp-weixin'；由调用方传入，不依赖模块加载时冻结的环境 */
+	platform;
 	logger;
-	/** Whether to work with vite-plugin-uni-platform plugin */
+	/** 是否与 vite-plugin-uni-platform 插件协同工作 */
 	withUniPlatform = false;
-	/** Cached previous pages.json content to avoid redundant writes */
-	lastPagesJson = "";
+	/** pages.json 中页面路径的解析基准路径 */
+	get basePath() {
+		return resolveBasePath(this.options);
+	}
 	/**
-	* Create a PageContext instance
-	* @param userOptions - User configuration options
-	* @param viteRoot - Vite project root directory, defaults to current working directory
+	* 创建 PageContext 实例
+	* @param userOptions - 用户配置项
+	* @param viteRoot - Vite 项目根目录，默认为当前工作目录
+	* @param platform - 当前平台标识，默认取 uni-env 的平台
 	*/
-	constructor(userOptions, viteRoot = process.cwd()) {
-		this.rawOptions = userOptions;
-		this.root = slash(viteRoot);
+	constructor(userOptions, viteRoot = process.cwd(), platform$1 = platform) {
+		this.root = normalizePath(viteRoot);
+		this.platform = platform$1;
 		debug.options("root", this.root);
 		this.options = resolveOptions(userOptions, this.root);
 		const debugOption = this.options.debug;
@@ -693,19 +1628,19 @@ var PageContext = class {
 			const suffix = typeof debugOption === "boolean" ? "*" : debugOption;
 			Debug.enable(`${prefix}${suffix}`);
 		}
-		this.resolvedPagesJSONPath = path.join(this.root, this.options.outDir, OUTPUT_NAME);
+		this.resolvedPagesJSONPath = resolvePagesJsonPath(this.root, this.options.outDir);
 		debug.options(this.options);
 	}
 	/**
-	* Set the Vite logger
-	* @param logger - Vite logger instance
+	* 设置 Vite logger
+	* @param logger - Vite logger 实例
 	*/
 	setLogger(logger) {
 		this.logger = logger;
 	}
 	/**
-	* Load user page configuration file (e.g. pages.config.ts)
-	* Uses unconfig to load configuration, supporting multiple config file formats
+	* 加载用户页面配置文件（如 pages.config.ts）
+	* 使用 unconfig 加载配置，支持多种配置文件格式
 	*/
 	async loadUserPagesConfig() {
 		const configSource = this.options.configSource;
@@ -715,51 +1650,22 @@ var PageContext = class {
 			defaults: {}
 		});
 		this.pagesGlobConfig = config.default || config;
-		this.pagesConfigSourcePaths = sources;
+		this.pagesConfigSourcePaths = sources.map(normalizePath);
 		debug.options(this.pagesGlobConfig);
 	}
 	/**
-	* Scan main package page directories and collect all page file paths
-	* Scan corresponding directories based on the configured dirs option
-	*/
-	async scanPages() {
-		const paths = this.options.dirs.map((dir) => {
-			return {
-				dir,
-				files: getPagePaths(dir, this.options)
-			};
-		}).map((page) => page.files).flat();
-		debug.pages(paths);
-		const pages = /* @__PURE__ */ new Map();
-		for (const path of paths) {
-			const page = this.pages.get(path.absolutePath) || new Page(this, path);
-			pages.set(path.absolutePath, page);
-		}
-		this.pages = pages;
-	}
-	/**
-	* Scan sub-package page directories and collect all sub-package page file paths
-	* Scan corresponding directories based on the configured subPackages option
+	* 按顺序跑完扫描与合并：先扫描主包和子包的页面，再合并它们的
+	* 信息。步骤顺序只维护在这里，调用方和测试都不用关心。
 	*/
-	async scanSubPages() {
-		const paths = {};
-		const subPages = /* @__PURE__ */ new Map();
-		for (const dir of this.options.subPackages) {
-			const pagePaths = getPagePaths(dir, this.options);
-			paths[dir] = pagePaths;
-			const pages = /* @__PURE__ */ new Map();
-			for (const path of pagePaths) {
-				const page = this.subPages.get(dir)?.get(path.absolutePath) || new Page(this, path);
-				pages.set(path.absolutePath, page);
-			}
-			subPages.set(dir, pages);
-		}
-		debug.subPages(JSON.stringify(paths, null, 2));
-		this.subPages = subPages;
+	async scanAndMerge() {
+		await this.scanPages();
+		await this.scanSubPages();
+		await this.mergePageMetaData();
+		await this.mergeSubPageMetaData();
 	}
 	/**
-	* Set up Vite dev server for HMR and file watching
-	* @param server - Vite dev server instance
+	* 设置 Vite 开发服务器，用于 HMR 与文件监听
+	* @param server - Vite 开发服务器实例
 	*/
 	setupViteServer(server) {
 		if (this._server === server) return;
@@ -767,47 +1673,45 @@ var PageContext = class {
 		this.setupWatcher(server.watcher);
 	}
 	/**
-	* Set up file watcher to monitor page file and config file changes
-	* Automatically update pages.json when page files or config files change
-	* @param watcher - chokidar file watcher instance
+	* 设置文件监听器，监听页面文件与配置文件变更
+	* 页面文件或配置文件变化时自动更新 pages.json
+	* @param watcher - chokidar 文件监听器实例
 	*/
 	async setupWatcher(watcher) {
 		watcher.add(this.pagesConfigSourcePaths);
-		const targetDirs = [...this.options.dirs, ...this.options.subPackages].map((v) => slash(path.resolve(this.root, v)));
-		const isInTargetDirs = (filePath) => targetDirs.some((v) => slash(path.resolve(this.root, filePath)).startsWith(v));
+		const targetDirs = [...this.options.dirs, ...this.options.subPackages].map((v) => normalizePath(path.resolve(this.root, v)));
+		const isWatchedPageFile = (filePath) => {
+			const absolute = normalizePath(path.resolve(this.root, filePath));
+			return isTargetFile(filePath) && targetDirs.some((v) => absolute === v || absolute.startsWith(`${v}/`));
+		};
 		watcher.on("add", async (path) => {
-			path = slash(path);
-			if (!isTargetFile(path)) return;
-			if (!isInTargetDirs(path)) return;
+			path = normalizePath(path);
+			if (!isWatchedPageFile(path)) return;
 			debug.pages(`File added: ${path}`);
 			if (await this.updatePagesJSON()) this.onUpdate();
 		});
 		watcher.on("change", async (path) => {
-			path = slash(path);
-			if (!isTargetFile(path)) return;
-			if (!isInTargetDirs(path)) return;
-			debug.pages(`File changed: ${path}`);
-			debug.pages(targetDirs);
-			debug.pages(isInTargetDirs(path));
-			if (await this.updatePagesJSON(path)) this.onUpdate();
-		});
-		watcher.on("change", async (path) => {
+			path = normalizePath(path);
 			if (this.pagesConfigSourcePaths.includes(path)) {
 				debug.pages(`Config source changed: ${path}`);
 				if (await this.updatePagesJSON()) this.onUpdate();
+				return;
 			}
+			path = normalizePath(path);
+			if (!isWatchedPageFile(path)) return;
+			debug.pages(`File changed: ${path}`);
+			if (await this.updatePagesJSON(path)) this.onUpdate();
 		});
 		watcher.on("unlink", async (path) => {
-			path = slash(path);
-			if (!isTargetFile(path)) return;
-			if (!isInTargetDirs(path)) return;
+			path = normalizePath(path);
+			if (!isWatchedPageFile(path)) return;
 			debug.pages(`File removed: ${path}`);
 			if (await this.updatePagesJSON()) this.onUpdate();
 		});
 	}
 	/**
-	* Page update callback, triggered when page files or configuration changes
-	* Responsible for invalidating virtual modules and notifying the browser to do a full reload
+	* 页面更新回调，页面文件或配置变化时触发
+	* 负责使虚拟模块失效并通知浏览器整页刷新
 	*/
 	onUpdate() {
 		if (!this._server) return;
@@ -816,115 +1720,19 @@ var PageContext = class {
 		this._server.ws.send({ type: "full-reload" });
 	}
 	/**
-	* parse pages rules && set page type
-	* @param pages page path array
-	* @param type  page type
-	* @param overrides custom page config
-	* @returns pages rules
-	*/
-	async parsePages(pages, type, overrides) {
-		const jobs = [];
-		for (const [_, page] of pages) jobs.push(page.getPageMeta());
-		const generatedPageMetaData = await Promise.all(jobs);
-		const customPageMetaData = overrides || [];
-		const result = customPageMetaData.length ? mergePageMetaDataArray(generatedPageMetaData.concat(customPageMetaData)) : generatedPageMetaData;
-		const parseMeta = Array.from(result.reduce((map, page) => {
-			map.set(page.path, page);
-			return map;
-		}, /* @__PURE__ */ new Map()).values());
-		return type === "main" ? this.setHomePage(parseMeta) : parseMeta;
-	}
-	/**
-	* set home page
-	* @param result pages rules array
-	* @returns pages rules
-	*/
-	setHomePage(result) {
-		if (!result.some(({ type }) => type === "home")) {
-			const basePath = slash(path.join(this.options.root, this.options.outDir));
-			const resolvedHomePages = this.options.homePage.map((v) => {
-				return slash(path.relative(basePath, slash(path.resolve(basePath, v))));
-			});
-			const matchHomePage = (itemPath, configPath) => {
-				if (itemPath === configPath) return true;
-				const normalizedItem = itemPath.replace(/\\/g, "/");
-				const normalizedConfig = configPath.replace(/\\/g, "/");
-				return normalizedItem.endsWith(`/${normalizedConfig}`);
-			};
-			if (!result.some((item) => {
-				const isFound = resolvedHomePages.some((expectedPath) => matchHomePage(item.path, expectedPath));
-				if (isFound) item.type = "home";
-				return isFound;
-			})) this.logger?.warn("No home page found, check the configuration of pages.config.ts, or add the `homePage` option to UniPages in vite.config.js, or add `definePage({ type: \"home\" })` in your vue page.", { timestamp: true });
-		}
-		result.sort((page) => page.type === "home" ? -1 : 0);
-		return result;
-	}
-	/**
-	* Merge main package page metadata
-	* Filter out pages belonging to sub-packages, then parse page metadata and merge user configuration
-	*/
-	async mergePageMetaData() {
-		const subPageAbsolutePaths = Array.from(this.subPages.values()).flatMap((v) => Array.from(v.keys()));
-		for (const subPageAbsolutePath of subPageAbsolutePaths) this.pages.delete(subPageAbsolutePath);
-		const pageMetaData = await this.parsePages(this.pages, "main", this.pagesGlobConfig?.pages);
-		this.pageMetaData = pageMetaData;
-		debug.pages(this.pageMetaData);
-	}
-	/**
-	* Merge sub-package page metadata
-	* Parse page metadata for each sub-package and handle sub-package configuration inheritance
-	* Preserves sub-package level properties like plugins from user config
-	*/
-	async mergeSubPageMetaData() {
-		const subPageMaps = {};
-		const subPlugins = {};
-		const subPackages = this.pagesGlobConfig?.subPackages || [];
-		for (const [dir, pages] of this.subPages) {
-			const basePath = slash(path.join(this.options.root, this.options.outDir));
-			const root = this.options.subPackageRootMap.get(dir) ?? slash(path.relative(basePath, path.join(this.options.root, dir)));
-			const globPackage = subPackages?.find((v) => v.root === root);
-			subPageMaps[root] = await this.parsePages(pages, "sub", globPackage?.pages);
-			subPageMaps[root] = subPageMaps[root].map((page) => ({
-				...page,
-				path: slash(path.relative(root, page.path))
-			}));
-			if (globPackage?.plugins) subPlugins[root] = globPackage.plugins;
-		}
-		for (const { root, pages, plugins } of subPackages) if (root && !subPageMaps[root]) {
-			subPageMaps[root] = pages || [];
-			if (plugins) subPlugins[root] = plugins;
-		}
-		const subPageMetaData = Object.keys(subPageMaps).map((root) => ({
-			root,
-			pages: subPageMaps[root],
-			...subPlugins[root] && { plugins: subPlugins[root] }
-		})).filter((meta) => meta.pages.length > 0);
-		this.subPageMetaData = subPageMetaData;
-		debug.subPages(this.subPageMetaData);
-	}
-	/**
-	* Update pages.json file
-	* This is the core method responsible for coordinating the entire page configuration generation flow:
-	* 1. Check file changes (if filepath is specified)
-	* 2. Load user configuration
-	* 3. Scan page files
-	* 4. Merge page metadata
-	* 5. Generate and write pages.json
-	* @param filepath - Changed file path for incremental update judgment
-	* @returns Whether pages.json was successfully updated
+	* 更新 pages.json 文件
+	* 这是负责协调整个页面配置生成流程的核心方法：
+	* 1. 检查文件变更（指定 filepath 时）
+	* 2. 加载用户配置
+	* 3. 扫描页面文件
+	* 4. 合并页面配置
+	* 5. 生成并写入 pages.json
+	* @param filepath - 发生变更的文件路径，用于增量更新判断
+	* @returns pages.json 是否成功更新
 	*/
 	async updatePagesJSON(filepath) {
 		if (filepath) {
-			let page = this.pages.get(filepath);
-			if (!page) {
-				let subPage;
-				for (const [_, pages] of this.subPages) {
-					subPage = pages.get(filepath);
-					if (subPage) break;
-				}
-				page = subPage;
-			}
+			const page = this.findPage(filepath);
 			if (page) {
 				await page.read();
 				if (!page.hasChanged()) {
@@ -934,66 +1742,69 @@ var PageContext = class {
 			}
 		}
 		checkPagesJsonFileSync(this.resolvedPagesJSONPath);
-		this.options.onBeforeLoadUserConfig(this);
+		this.options.onBeforeLoadUserConfig();
 		await this.loadUserPagesConfig();
-		this.options.onAfterLoadUserConfig(this);
+		this.options.onAfterLoadUserConfig(this.pagesGlobConfig);
 		if (this.options.mergePages) {
-			this.options.onBeforeScanPages(this);
+			this.options.onBeforeScanPages();
 			await this.scanPages();
 			await this.scanSubPages();
-			this.options.onAfterScanPages(this);
+			this.options.onAfterScanPages(this.pages, this.subPages);
 		}
-		this.options.onBeforeMergePageMetaData(this);
+		this.options.onBeforeMergePageMetaData(this.pages, this.pagesGlobConfig);
 		await this.mergePageMetaData();
 		await this.mergeSubPageMetaData();
-		this.options.onAfterMergePageMetaData(this);
-		const pagesMap = /* @__PURE__ */ new Map();
-		(this.withUniPlatform ? this.pageMetaData.filter((v) => !/\..*$/.test(v.path) || v.path.includes(platform)).map((v) => {
-			v.path = v.path.replace(/\..*$/, "");
-			return v;
-		}) : this.pageMetaData).forEach((v) => pagesMap.set(v.path, v));
-		this.pageMetaData = [...pagesMap.values()];
-		this.options.onBeforeWriteFile(this);
-		const updated = await withFileLock(this.resolvedPagesJSONPath, async () => {
-			const pagesJson = stringify(await this.genratePagesJSON(), null, this.options.minify ? void 0 : await this.getIndent()) + (await this.getEndOfLine() ? await this.getNewline() : "");
-			if (this.lastPagesJson === pagesJson) {
-				debug.pages("PagesJson Not have change");
-				return false;
+		this.options.onAfterMergePageMetaData(this.pageMetaData, this.subPageMetaData);
+		const pages = this.withUniPlatform ? filterPlatformSuffixPages(this.pageMetaData, this.platform) : this.pageMetaData;
+		this.pageMetaData = dedupeByPath(pages);
+		this.options.onBeforeWriteFile(this.resolvedPagesJSONPath);
+		const homePath = this.pageMetaData.find((meta) => meta.type === "home")?.path;
+		this.tabBar = await this.resolveTabBar();
+		const result = await writePagesJson(this.resolvedPagesJSONPath, {
+			pages: this.pageMetaData,
+			subPackages: this.subPageMetaData,
+			tabBar: this.tabBar,
+			homePath
+		}, {
+			platform: this.platform,
+			globConfig: this.pagesGlobConfig,
+			format: {
+				minify: this.options.minify,
+				indent: this.options.indent,
+				eol: this.options.eol,
+				insertFinalNewline: this.options.insertFinalNewline
 			}
-			await writeFileAtomic(this.resolvedPagesJSONPath, pagesJson);
-			this.lastPagesJson = pagesJson;
-			return true;
 		});
 		this.generateDeclaration();
-		if (updated) this.options.onAfterWriteFile(this);
-		return updated ?? false;
+		if (result?.updated) this.options.onAfterWriteFile(this.resolvedPagesJSONPath, result.content);
+		return result?.updated ?? false;
 	}
 	/**
-	* Generate virtual module content
-	* Returns JavaScript code containing pages and subPackages exports
-	* @returns Virtual module code string
+	* 生成虚拟模块内容
+	* 返回包含 pages 与 subPackages 导出的 JavaScript 代码
+	* @returns 虚拟模块代码字符串
 	*/
 	virtualModule() {
 		return [`export const pages = ${this.resolveRoutes()};`, `export const subPackages = ${this.resolveSubRoutes()};`].join("\n");
 	}
 	/**
-	* Resolve main package route data to JSON string
-	* @returns JSON string of main package page metadata
+	* 将主包路由数据解析为 JSON 字符串
+	* @returns 主包页面配置的 JSON 字符串
 	*/
 	resolveRoutes() {
 		return stringify(this.pageMetaData, null, 2);
 	}
 	/**
-	* Resolve sub-package route data to JSON string
-	* @returns JSON string of sub-package page metadata
+	* 将子包路由数据解析为 JSON 字符串
+	* @returns 子包页面配置的 JSON 字符串
 	*/
 	resolveSubRoutes() {
 		return stringify(this.subPageMetaData, null, 2);
 	}
 	/**
-	* Resolve tabBar configuration
-	* Merges page-defined tabBar items with config-defined tabBar
-	* @returns Merged tabBar configuration object, or undefined if no tabBar exists
+	* 解析 tabBar 配置
+	* 将页面定义的 tabBar 项与配置文件定义的 tabBar 合并
+	* @returns 合并后的 tabBar 配置对象，无 tabBar 时为 undefined
 	*/
 	async resolveTabBar() {
 		const tabBarItems = [];
@@ -1006,8 +1817,7 @@ var PageContext = class {
 			...this.pagesGlobConfig?.tabBar,
 			list: this.pagesGlobConfig?.tabBar?.list || []
 		};
-		const pagePaths = /* @__PURE__ */ new Map();
-		for (const item of tabBar.list) pagePaths.set(item.pagePath, true);
+		const pagePaths = new Set(tabBar.list.map((item) => item.pagePath));
 		tabBarItems.sort((a, b) => a.index - b.index);
 		for (const item of tabBarItems) if (!pagePaths.has(item.pagePath)) {
 			const { index: _, ...tabbar } = item;
@@ -1016,262 +1826,322 @@ var PageContext = class {
 		return tabBar;
 	}
 	/**
-	* Generate TypeScript declaration file
-	* Generate type definitions for page paths to provide type hints during navigation
+	* 生成 TypeScript 声明文件
+	* 为页面路径生成类型定义，导航时提供类型提示
 	*/
 	generateDeclaration() {
 		if (!this.options.dts) return;
 		debug.declaration("generating");
-		return writeDeclaration(this, this.options.dts);
-	}
-	async genratePagesJSON() {
-		const { pages: oldPages, subPackages: oldSubPackages, tabBar: oldTabBar } = parse(await fs.promises.readFile(this.resolvedPagesJSONPath, { encoding: "utf-8" }).catch(() => "") || "{}");
-		const { pages: _pages, subPackages: _subPackages, tabBar: _tabBar, ...pageJson } = this.pagesGlobConfig || {};
-		const currentPlatform = platform.toUpperCase();
-		pageJson.pages = mergePlatformItems(oldPages, currentPlatform, this.pageMetaData, "path");
-		if (pageJson.pages && pageJson.pages.length > 0) {
-			const pagesArray = pageJson.pages;
-			const homeIndex = pagesArray.findIndex((page) => page.type === "home");
-			if (homeIndex > 0) {
-				const [homePage] = pagesArray.splice(homeIndex, 1);
-				pagesArray.unshift(homePage);
-			}
+		return writeDeclaration({
+			pages: this.pageMetaData,
+			subPackages: this.subPageMetaData,
+			tabBar: this.tabBar,
+			globConfig: this.pagesGlobConfig
+		}, this.options.dts);
+	}
+	/**
+	* 扫描主包页面目录并收集所有页面文件路径
+	* 根据配置的 dirs 选项扫描对应目录
+	*/
+	async scanPages() {
+		const paths = this.options.dirs.flatMap((dir) => getPagePaths(dir, this.options));
+		debug.pages(paths);
+		const pages = /* @__PURE__ */ new Map();
+		for (const path of paths) {
+			const page = this.pages.get(path.absolutePath) || new Page(this, path);
+			pages.set(path.absolutePath, page);
 		}
-		pageJson.subPackages = oldSubPackages || new CommentArray();
-		const newSubPackages = /* @__PURE__ */ new Map();
-		for (const item of this.subPageMetaData) newSubPackages.set(item.root, item);
-		for (const existing of pageJson.subPackages) {
-			const sub = newSubPackages.get(existing.root);
-			if (sub) {
-				existing.pages = mergePlatformItems(existing.pages, currentPlatform, sub.pages, "path");
-				if (sub.plugins) existing.plugins = sub.plugins;
-				newSubPackages.delete(existing.root);
-			}
+		this.pages = pages;
+	}
+	/**
+	* 按页面文件绝对路径查找被跟踪的页面（主包或任一子包）
+	* @param filepath - 页面文件的绝对路径
+	* @returns 被跟踪的页面，文件未被跟踪时为 undefined
+	*/
+	findPage(filepath) {
+		const mainPage = this.pages.get(filepath);
+		if (mainPage) return mainPage;
+		for (const pages of this.subPages.values()) {
+			const subPage = pages.get(filepath);
+			if (subPage) return subPage;
 		}
-		for (const [_, newSub] of newSubPackages) {
-			const subPackage = {
-				root: newSub.root,
-				pages: mergePlatformItems(void 0, currentPlatform, newSub.pages, "path")
-			};
-			if (newSub.plugins) subPackage.plugins = newSub.plugins;
-			pageJson.subPackages.push(subPackage);
+	}
+	/**
+	* 扫描子包页面目录并收集所有子包页面文件路径
+	* 根据配置的 subPackages 选项扫描对应目录
+	*/
+	async scanSubPages() {
+		const paths = {};
+		const subPages = /* @__PURE__ */ new Map();
+		for (const dir of this.options.subPackages) {
+			const pagePaths = getPagePaths(dir, this.options);
+			paths[dir] = pagePaths;
+			const pages = /* @__PURE__ */ new Map();
+			for (const path of pagePaths) {
+				const page = this.subPages.get(dir)?.get(path.absolutePath) || new Page(this, path);
+				pages.set(path.absolutePath, page);
+			}
+			subPages.set(dir, pages);
 		}
-		const { list, ...tabBarOthers } = await this.resolveTabBar() || {};
-		if (list) {
-			const { list: oldList } = oldTabBar || {};
-			const newList = mergePlatformItems(oldList, currentPlatform, list, "pagePath");
-			pageJson.tabBar = {
-				...tabBarOthers,
-				list: newList
-			};
-		} else pageJson.tabBar = void 0;
-		return pageJson;
+		debug.subPages(JSON.stringify(paths, null, 2));
+		this.subPages = subPages;
 	}
-	async readInfoFromPagesJSON() {
-		const resolvedPagesJSONContent = await fs.promises.readFile(this.resolvedPagesJSONPath, { encoding: "utf-8" }).catch(() => "");
-		this.resolvedPagesJSONIndent = detectIndent(resolvedPagesJSONContent).indent || "  ";
-		this.resolvedPagesJSONNewline = detectNewline(resolvedPagesJSONContent) || "\n";
-		this.resolvedPagesJSONEofNewline = (resolvedPagesJSONContent.at(-1) ?? "\n") === this.resolvedPagesJSONNewline;
+	/**
+	* 解析 pages 规则并设置页面类型
+	* @param pages 页面路径映射
+	* @param packageType 页面包类型（主包或子包）
+	* @param overrides 自定义页面配置
+	* @returns pages 规则
+	*/
+	async parsePages(pages, packageType, overrides) {
+		const allPages = Array.from(pages.values());
+		await Promise.all(allPages.map((page) => page.ensureLoaded()));
+		const jobs = allPages.filter((page) => !page.skipped).map((page) => page.getPageMeta());
+		const generatedPageMetaData = await Promise.all(jobs);
+		const customPageMetaData = overrides || [];
+		const parseMeta = dedupeByPath(customPageMetaData.length ? mergePageMetaDataArray(generatedPageMetaData.concat(customPageMetaData)) : generatedPageMetaData);
+		return packageType === "main" ? this.setHomePage(parseMeta) : parseMeta;
 	}
-	async getIndent() {
-		if (!this.resolvedPagesJSONIndent) await this.readInfoFromPagesJSON();
-		return this.resolvedPagesJSONIndent;
+	/**
+	* 设置首页
+	* @param result pages 规则数组
+	* @returns pages 规则
+	*/
+	setHomePage(result) {
+		if (!result.some(({ type }) => type === "home")) {
+			const basePath = this.basePath;
+			const resolvedHomePages = this.options.homePage.map((v) => {
+				return normalizePath(path.relative(basePath, normalizePath(path.resolve(basePath, v))));
+			});
+			const matchHomePage = (itemPath, configPath) => {
+				if (itemPath === configPath) return true;
+				const normalizedItem = itemPath.replace(/\\/g, "/");
+				const normalizedConfig = configPath.replace(/\\/g, "/");
+				return normalizedItem.endsWith(`/${normalizedConfig}`);
+			};
+			if (!result.some((item) => {
+				const isFound = resolvedHomePages.some((expectedPath) => matchHomePage(item.path, expectedPath));
+				if (isFound) item.type = "home";
+				return isFound;
+			})) this.logger?.warn("No home page found, check the configuration of pages.config.ts, or add the `homePage` option to UniPages in the Vite config file, or add `definePage({ type: \"home\" })` in your vue page.", { timestamp: true });
+		}
+		result.sort((page) => page.type === "home" ? -1 : 0);
+		return result;
 	}
-	async getNewline() {
-		if (!this.resolvedPagesJSONNewline) await this.readInfoFromPagesJSON();
-		return this.resolvedPagesJSONNewline;
+	/**
+	* 合并主包页面配置
+	* 过滤掉属于子包的页面，再解析页面配置并与用户配置合并
+	*/
+	async mergePageMetaData() {
+		for (const pages of this.subPages.values()) for (const subPageAbsolutePath of pages.keys()) this.pages.delete(subPageAbsolutePath);
+		const pageMetaData = await this.parsePages(this.pages, "main", this.pagesGlobConfig?.pages);
+		this.pageMetaData = pageMetaData;
+		debug.pages(this.pageMetaData);
 	}
-	async getEndOfLine() {
-		if (!this.resolvedPagesJSONEofNewline) await this.readInfoFromPagesJSON();
-		return this.resolvedPagesJSONEofNewline;
+	/**
+	* 合并子包页面配置
+	* 为每个子包解析页面配置并处理子包配置继承
+	* 保留用户配置中子包级别的属性（如 plugins）
+	*/
+	async mergeSubPageMetaData() {
+		const packagesByRoot = /* @__PURE__ */ new Map();
+		const subPackages = this.pagesGlobConfig?.subPackages || [];
+		for (const [dir, pages] of this.subPages) {
+			const root = this.options.subPackageRootMap.get(dir) ?? normalizePath(path.relative(this.basePath, path.join(this.options.root, dir)));
+			const globPackage = subPackages?.find((v) => v.root === root);
+			const overrides = globPackage?.pages?.map((page) => {
+				if (!page.path || page.path.startsWith(`${root}/`)) return page;
+				return {
+					...page,
+					path: `${root}/${page.path}`
+				};
+			});
+			const parsedPages = (await this.parsePages(pages, "sub", overrides)).map((page) => ({
+				...page,
+				path: normalizePath(path.relative(root, page.path))
+			}));
+			packagesByRoot.set(root, {
+				root,
+				pages: parsedPages,
+				...globPackage?.plugins && { plugins: globPackage.plugins }
+			});
+		}
+		for (const { root, pages, plugins } of subPackages) if (root && !packagesByRoot.has(root)) packagesByRoot.set(root, {
+			root,
+			pages: pages || [],
+			...plugins && { plugins }
+		});
+		this.subPageMetaData = [...packagesByRoot.values()].filter((meta) => meta.pages.length > 0);
+		debug.subPages(this.subPageMetaData);
 	}
 };
 /**
-* Get all page paths in the specified directory
-* @param dir - Page directory path
-* @param options - Resolved configuration options
-* @returns Page path array containing relative and absolute paths
+* 解析 pages.json 中页面路径的基准路径
+* @param options - 解析后的配置项
+* @returns 由 root 与 outDir 拼接并斜杠化后的基准路径
+*/
+function resolveBasePath(options) {
+	return normalizePath(path.join(options.root, options.outDir));
+}
+/**
+* 获取指定目录下的全部页面路径
+* @param dir - 页面目录路径
+* @param options - 解析后的配置项
+* @returns 包含相对路径与绝对路径的页面路径数组
 */
 function getPagePaths(dir, options) {
-	const pagesDirPath = slash(path.resolve(options.root, dir));
-	const basePath = slash(path.join(options.root, options.outDir));
+	const pagesDirPath = normalizePath(path.resolve(options.root, dir));
+	const basePath = resolveBasePath(options);
 	const files = getPageFiles(pagesDirPath, options);
 	debug.pages(dir, files);
-	return files.map((file) => slash(file)).map((file) => ({
-		relativePath: path.relative(basePath, slash(path.resolve(pagesDirPath, file))),
-		absolutePath: slash(path.resolve(pagesDirPath, file))
+	return files.map((file) => normalizePath(file)).map((file) => ({
+		relativePath: path.relative(basePath, normalizePath(path.resolve(pagesDirPath, file))),
+		absolutePath: normalizePath(path.resolve(pagesDirPath, file))
 	}));
 }
 /**
-* Merge multi-platform page configuration items
-* Handle conditional compilation comments (#ifdef / #endif), merge configuration items from different platforms into one array
-* Same configuration items will automatically merge platform identifiers, different configuration items will keep conditional compilation comments
+* 按路径去重页面配置，每个路径保留最后一条
+* @param pageMetaData - 页面配置数组
+* @returns 按首次出现顺序去重后的页面配置数组
+*/
+function dedupeByPath(pageMetaData) {
+	const byPath = /* @__PURE__ */ new Map();
+	for (const page of pageMetaData) byPath.set(page.path, page);
+	return [...byPath.values()];
+}
+/**
+* 应用 vite-plugin-uni-platform 的页面文件名后缀规则（如 `index.h5.vue`
+* 对应页面 `index`）：丢弃其他平台的后缀页面，保留当前平台的并把文件名
+* 里的后缀剥掉。
 *
-* @param source - Existing configuration item array (from pages.json)
-* @param currentPlatform - Current platform identifier (e.g. H5, MP-WEIXIN)
-* @param items - New configuration item array
-* @param uniqueKeyName - Field name used to identify configuration item uniqueness (e.g. 'path' or 'pagePath')
-* @returns Merged configuration item array with conditional compilation comments
+* 带点的判断只看路径最后一段（文件名），和 vite-plugin-uni-platform
+* 自己的规则一致（它也只在文件名上判断后缀），目录名里的点（如
+* `pages/v1.2/detail`）不算平台后缀。
+*
+* 注意后缀匹配仍是原始的 `path.includes(platform)`，没有做 definePage
+* 那边 h5/web 的别名换算（见 condition.ts 的 platformMatches）：
+* UNI_PLATFORM=web 时，`.h5` 后缀的页面会被过滤掉。这是一直以来的
+* 行为，为了和 vite-plugin-uni-platform 自己的命名规则保持一致而保留。
+*
+* @param pages - 合并后的主包页面配置
+* @param platform - 当前平台标识
+* @returns 过滤并剥掉后缀的新数组，入参不被修改
 */
-function mergePlatformItems(source, currentPlatform, items, uniqueKeyName) {
-	const src = source || new CommentArray();
-	currentPlatform = currentPlatform.toUpperCase();
-	let lastPlatforms = [];
-	for (const comment of src[Symbol.for("before:0")] || []) {
-		const trimed = comment.value.trim();
-		if (trimed.startsWith("GENERATED BY UNI-PAGES, PLATFORM:")) lastPlatforms = trimed.split(":")[1].split("||").map((s) => s.trim()).filter((s) => s !== currentPlatform).sort();
-	}
-	const stringifyForCompare = (val) => {
-		if (val && typeof val === "object" && "type" in val) {
-			const { type: _type, ...rest } = val;
-			return JSON.stringify(rest);
-		}
-		return JSON.stringify(val);
-	};
-	const tmpMap = /* @__PURE__ */ new Map();
-	for (let i = 0; i < src.length; i++) {
-		const item = src[i];
-		const uniqueKey = item[uniqueKeyName];
-		if (!uniqueKey) continue;
-		const ifdefComment = src[Symbol.for(`before:${i}`)]?.find((c) => c.value.trim().startsWith("#ifdef"));
-		let platforms = [...lastPlatforms];
-		if (ifdefComment) {
-			const match = ifdefComment.value.match(/#ifdef\s+(.+)/);
-			if (match) platforms = match[1].split("||").map((p) => p.trim()).filter((s) => s !== currentPlatform).sort();
-		}
-		if (platforms.length === 0) continue;
-		const existing = tmpMap.get(uniqueKey) || [];
-		existing.push({
-			item,
-			itemStr: stringifyForCompare(item),
-			platforms,
-			platformStr: platforms.join(" || ")
-		});
-		tmpMap.set(uniqueKey, existing);
-	}
-	for (const item of items) {
-		const newItem = item;
-		const uniqueKey = item[uniqueKeyName];
-		if (!uniqueKey) continue;
-		if (!tmpMap.has(uniqueKey)) {
-			tmpMap.set(uniqueKey, [{
-				item: newItem,
-				itemStr: stringifyForCompare(newItem),
-				platforms: [currentPlatform],
-				platformStr: currentPlatform
-			}]);
-			continue;
-		}
-		const existing = tmpMap.get(uniqueKey);
-		const newItemStr = stringifyForCompare(newItem);
-		const equalObj = existing.find((val) => val.itemStr === newItemStr);
-		if (equalObj) {
-			equalObj.platforms.push(currentPlatform);
-			equalObj.platforms.sort();
-			equalObj.platformStr = equalObj.platforms.join(" || ");
-		} else existing.push({
-			item: newItem,
-			itemStr: stringifyForCompare(newItem),
-			platforms: [currentPlatform],
-			platformStr: currentPlatform
-		});
-	}
-	const result = new CommentArray();
-	const platformUsage = {};
-	tmpMap.forEach((val) => {
-		Object.values(val).forEach((v) => {
-			platformUsage[v.platformStr] = (platformUsage[v.platformStr] || 0) + 1;
-		});
+function filterPlatformSuffixPages(pages, platform) {
+	return pages.filter((page) => {
+		return !page.path.slice(page.path.lastIndexOf("/") + 1).includes(".") || page.path.includes(platform);
+	}).map((page) => {
+		const slash = page.path.lastIndexOf("/");
+		const fileName = page.path.slice(slash + 1);
+		const dot = fileName.indexOf(".");
+		return dot === -1 ? page : {
+			...page,
+			path: `${page.path.slice(0, slash + 1)}${fileName.slice(0, dot)}`
+		};
 	});
-	const usageKeys = Object.keys(platformUsage);
-	const defaultPlatformStr = usageKeys.length ? usageKeys.reduce((a, b) => platformUsage[a] > platformUsage[b] ? a : b) : currentPlatform;
-	result[Symbol.for("before:0")] = [{
-		type: "LineComment",
-		value: ` GENERATED BY UNI-PAGES, PLATFORM: ${defaultPlatformStr}`,
-		inline: false,
-		loc: {
-			start: {
-				line: 0,
-				column: 0
-			},
-			end: {
-				line: 0,
-				column: 0
-			}
-		}
-	}];
-	for (const [_, list] of tmpMap) for (const { item, platformStr } of list) {
-		result.push(item);
-		if (platformStr !== defaultPlatformStr) {
-			result[Symbol.for(`before:${result.length - 1}`)] = [{
-				type: "LineComment",
-				value: ` #ifdef ${platformStr}`,
-				inline: false,
-				loc: {
-					start: {
-						line: 0,
-						column: 0
-					},
-					end: {
-						line: 0,
-						column: 0
-					}
-				}
-			}];
-			result[Symbol.for(`after:${result.length - 1}`)] = [{
-				type: "LineComment",
-				value: " #endif",
-				inline: false,
-				loc: {
-					start: {
-						line: 0,
-						column: 0
-					},
-					end: {
-						line: 0,
-						column: 0
-					}
-				}
-			}];
+}
+/**
+* 按路径合并页面信息并赋 style
+* @param pageMetaData 页面信息数组
+* TODO: 支持 middleware 合并
+*/
+function mergePageMetaDataArray(pageMetaData) {
+	const pageMetaDataObj = groupBy(pageMetaData, "path");
+	const result = [];
+	for (const path in pageMetaDataObj) {
+		const group = pageMetaDataObj[path];
+		const mergedPage = { ...group[0] };
+		for (const page of group) {
+			if (!Object.hasOwn(page, "style")) mergedPage.style = Object.assign({ ...mergedPage.style ?? {} }, page.style ?? {});
+			Object.assign(mergedPage, page);
 		}
+		result.push(mergedPage);
 	}
 	return result;
 }
+/**
+* 使虚拟模块失效以触发 HMR 更新
+* 页面配置变化时，需要使虚拟模块失效以重新生成内容
+*
+* @param server - Vite 开发服务器实例
+*/
+function invalidatePagesModule(server) {
+	const { moduleGraph } = server;
+	const mods = moduleGraph.getModulesByFile(RESOLVED_MODULE_ID_VIRTUAL);
+	if (mods) {
+		const seen = /* @__PURE__ */ new Set();
+		mods.forEach((mod) => {
+			moduleGraph.invalidateModule(mod, seen);
+		});
+	}
+}
 //#endregion
-//#region src/config/index.ts
+//#region src/config.ts
 /**
-* Define uni-pages configuration
-* Used in pages.config.ts configuration file to provide type hints and validation
+* 定义 uni-pages 配置
+* 在 pages.config.ts 配置文件中使用，提供类型提示与校验
 *
-* @param config - Page configuration object
-* @returns Configuration object
+* @param config - 页面配置对象
+* @returns 配置对象
 */
 function defineUniPages(config) {
 	return config;
 }
 //#endregion
+//#region src/pipeline.ts
+/**
+* 创建 PageContext，并在内存里跑完「扫描/合并」
+*
+* 不写任何文件；路由数据通过 `resolveRoutes`、`resolveSubRoutes`、
+* `resolveTabBar` 和 `virtualModule` 取。
+*
+* @param userOptions - 用户配置项
+* @param overrides - 从外面传入的 root 与 platform
+* @returns 完成扫描与合并的 PageContext
+*/
+async function createPages(userOptions = {}, overrides = {}) {
+	const ctx = new PageContext(userOptions, overrides.root ?? process.cwd(), overrides.platform);
+	await ctx.scanAndMerge();
+	return ctx;
+}
+/**
+* 运行完整流水线：加载用户配置、扫描、合并并写入 pages.json
+* （以及 TypeScript 声明文件）
+*
+* @param userOptions - 用户配置项
+* @param overrides - 从外面传入的 root 与 platform
+* @returns pages.json 是否有更新，以及产出它的上下文
+*/
+async function generateAll(userOptions = {}, overrides = {}) {
+	const ctx = new PageContext(userOptions, overrides.root ?? process.cwd(), overrides.platform);
+	return {
+		updated: await ctx.updatePagesJSON(),
+		ctx
+	};
+}
+//#endregion
 //#region src/index.ts
 /**
-* vite-plugin-uni-pages plugin main entry
+* vite-plugin-uni-pages 插件主入口
 *
-* Automatically scan page directories and generate pages.json configuration file
-* Support definePage macro for defining page metadata
-* Support multi-platform conditional compilation
-* Support sub-package configuration
-* Support TypeScript declaration file generation
+* 自动扫描页面目录并生成 pages.json 配置文件
+* 支持 definePage 宏定义页面配置
+* 支持多平台条件编译
+* 支持分包配置
+* 支持 TypeScript 声明文件生成
 *
-* @param userOptions - User configuration options
-* @returns Vite plugin instance
+* @param userOptions - 用户配置项
+* @returns Vite 插件实例
 */
 function VitePluginUniPages(userOptions = {}) {
 	let ctx;
-	checkPagesJsonFileSync(path.join(process.env.VITE_ROOT_DIR || process.cwd(), userOptions.outDir ?? "src", OUTPUT_NAME));
+	checkPagesJsonFileSync(resolvePagesJsonPath(process.env.VITE_ROOT_DIR || process.cwd(), userOptions.outDir ?? "src"));
 	return {
 		name: "vite-plugin-uni-pages",
 		enforce: "pre",
 		/**
-		* Vite configResolved hook
-		* Initialize PageContext, set logger, generate initial pages.json
+		* Vite configResolved 钩子
+		* 初始化 PageContext，设置 logger，生成初始 pages.json
 		*/
 		async configResolved(config) {
 			ctx = new PageContext(userOptions, config.root);
@@ -1280,19 +2150,18 @@ function VitePluginUniPages(userOptions = {}) {
 			ctx.setLogger(logger);
 			await ctx.updatePagesJSON();
 			if (config.command === "build") {
-				if (config.build.watch) ctx.setupWatcher(chokidar.watch([...ctx.options.dirs, ...ctx.options.subPackages]));
+				if (config.build.watch) ctx.setupWatcher(chokidar.watch([...ctx.options.dirs, ...ctx.options.subPackages].map((v) => normalizePath(path.resolve(config.root, v)))));
 			}
 		},
 		/**
-		* Code transform hook
-		* Remove definePage macro calls from Vue SFC to avoid runtime errors
+		* 代码转换钩子
+		* 从 Vue SFC 中移除 definePage 宏调用，避免运行时报错
 		*/
 		async transform(code, id) {
 			if (!FILE_EXTENSIONS.some((ext) => id.endsWith(ext))) return null;
-			const sfc = parseSFC(code, { filename: id });
-			let macro;
-			if (sfc.scriptSetup) macro = findMacro(babelParse(sfc.scriptSetup.content, sfc.scriptSetup.lang || "js").body, sfc.filename);
-			if (!macro && sfc.script) macro = findMacro(babelParse(sfc.script.content, sfc.script.lang || "js").body, sfc.filename);
+			const macro = findDefinePageMacro(code, id, { onParseError: (block, error) => {
+				this.warn(`[vite-plugin-uni-pages] Failed to parse ${block} in ${id}, its definePage macro may stay in the output: ${error instanceof Error ? error?.message : error}`);
+			} });
 			if (!macro) return null;
 			const s = new MagicString(code);
 			s.remove(macro.start, macro.end);
@@ -1302,26 +2171,26 @@ function VitePluginUniPages(userOptions = {}) {
 					source: id,
 					includeContent: true,
 					file: `${id}.map`
-				})
+				}).toString()
 			};
 		},
 		/**
-		* Configure server hook
-		* Set up file watching and HMR support
+		* 配置开发服务器钩子
+		* 设置文件监听与 HMR 支持
 		*/
 		configureServer(server) {
 			ctx.setupViteServer(server);
 		},
 		/**
-		* Module resolution hook
-		* Resolve virtual module identifier to internal path
+		* 模块解析钩子
+		* 将虚拟模块标识符解析为内部路径
 		*/
 		resolveId(id) {
 			if (id === "virtual:uni-pages") return RESOLVED_MODULE_ID_VIRTUAL;
 		},
 		/**
-		* Module load hook
-		* Return the code content of the virtual module
+		* 模块加载钩子
+		* 返回虚拟模块的代码内容
 		*/
 		load(id) {
 			if (id === RESOLVED_MODULE_ID_VIRTUAL) return ctx.virtualModule();
@@ -1329,4 +2198,4 @@ function VitePluginUniPages(userOptions = {}) {
 	};
 }
 //#endregion
-export { FILE_EXTENSIONS, MODULE_ID_VIRTUAL, OUTPUT_NAME, Page, PageContext, RESOLVED_MODULE_ID_VIRTUAL, VitePluginUniPages, VitePluginUniPages as default, babelGenerate, checkPagesJsonFileSync, debug, defineUniPages, extsToGlob, findImports, findMacro, getPageFiles, invalidatePagesModule, isTargetFile, mergePageMetaDataArray, parseCode, parseSFC, resolveOptions, resolvePageDirs, sleep, tryPageMetaFromMacro, withFileLock, writeFileWithLock };
+export { DefineConditional, FILE_EXTENSIONS, MODULE_ID_VIRTUAL, OUTPUT_NAME, Page, PageContext, RESOLVED_MODULE_ID_VIRTUAL, VitePluginUniPages, VitePluginUniPages as default, checkPagesJsonFileSync, createPages, debug, defineUniPages, evaluateDefinePage, filterPlatformSuffixPages, findDefinePageMacro, generateAll, getPageFiles, isConditional, isTargetFile, mergePagesJson, parseSFC, resolveConditional, resolveOptions, resolvePageDirs, resolvePagesJsonPath, withFileLock, writePagesJson };