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

package/dist/index.mjs

@@ -1,25 +1,458 @@
 import { createRequire } from "node:module";
+import fs, { existsSync, mkdirSync, realpathSync } from "node:fs";
 import path, { dirname, extname, join, resolve } from "node:path";
 import process from "node:process";
 import chokidar from "chokidar";
 import MagicString from "magic-string";
 import { createLogger, normalizePath } from "vite";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { bundleRequire } from "bundle-require";
+import { loadConfig } from "unconfig";
+import { Buffer } from "node:buffer";
+import babelGenerate from "@babel/generator";
+import * as t from "@babel/types";
+import { callExpression, identifier, removePropertiesDeep } from "@babel/types";
+import { babelParse, isCallOf, walkAST } from "ast-kit";
+import { transform } from "esbuild";
+import Debug from "debug";
 import { platform } from "@uni-helper/uni-env";
 import { CommentArray, parse, stringify } from "comment-json";
-import Debug from "debug";
 import groupBy from "lodash.groupby";
-import { loadConfig } from "unconfig";
-import fs, { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
 import lockfile from "proper-lockfile";
-import { globSync } from "tinyglobby";
+import { escapePath, globSync, isDynamicPattern } from "tinyglobby";
+import picomatch from "picomatch";
 import vm from "node:vm";
-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/config-source.ts
+/** 判断导入表达式能否交给 esbuild 收集依赖，未匹配的目标由运行时助手解析 */
+function isBundledSpecifier(node) {
+	if (!node) return false;
+	if (node.type === "StringLiteral") return true;
+	if (node.type === "TemplateLiteral") return node.expressions.length === 0 || /^\.\.?\//.test(node.quasis[0].value.cooked ?? "");
+	if (node.type === "BinaryExpression" && node.operator === "+") {
+		let first = node.left;
+		while (first.type === "BinaryExpression" && first.operator === "+") first = first.left;
+		return first.type === "StringLiteral" && /^\.\.?\//.test(first.value);
+	}
+	return false;
+}
+/**
+* 将脚本转换为绑定原文件位置的 JavaScript
+*
+* @description 注入运行时解析助手；可打包的调用及用户声明的局部 require 保持原语义
+* @param code 当前模块的源码文本
+* @param filename 当前模块的原始绝对路径，作为该模块运行时解析的基准
+* @param runtime 本轮生成的公共辅助模块路径，供转换后的代码导入
+* @returns 转换后的 JavaScript，包含映射到原模块的内联源码映射
+*/
+async function transformConfigSource(code, filename, runtime) {
+	let prefix = "__uni_pages_source";
+	while (code.includes(prefix)) prefix += "_";
+	const requireName = `${prefix}_require`;
+	const metaName = `${prefix}_meta`;
+	const importName = `${prefix}_import`;
+	const extension = path.extname(filename).slice(1);
+	const loader = extension === "jsx" || extension === "tsx" ? extension : /^(?:c|m)?js$/.test(extension) ? "js" : "ts";
+	const result = await transform(code, {
+		loader,
+		sourcefile: filename,
+		sourcemap: "external",
+		target: "node22",
+		define: {
+			"require": requireName,
+			"import.meta": metaName,
+			"__dirname": JSON.stringify(path.dirname(filename)),
+			"__filename": JSON.stringify(filename)
+		}
+	});
+	const ast = babelParse(result.code, "js", { allowReturnOutsideFunction: true });
+	walkAST(ast, { enter(node) {
+		if (node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === requireName && isBundledSpecifier(node.arguments[0])) node.callee.name = "require";
+		if (node.type === "ImportExpression" && !isBundledSpecifier(node.source)) this.replace(callExpression(identifier(importName), [node.source, ...node.options ? [node.options] : []]));
+	} });
+	const url = JSON.stringify(pathToFileURL(filename).href);
+	const helpers = babelParse(`
+import { createRequire as ${prefix}_createRequire, createMeta as ${prefix}_createMeta, importFrom as ${prefix}_importFrom } from ${JSON.stringify(runtime)};
+const ${requireName} = ${prefix}_createRequire(${JSON.stringify(filename)});
+const ${metaName} = ${prefix}_createMeta(${JSON.stringify(filename)}, ${url}, ${JSON.stringify(path.dirname(filename))});
+const ${importName} = (specifier, options) => ${prefix}_importFrom(specifier, ${url}, options);
+`, "js");
+	removePropertiesDeep(helpers);
+	ast.body.unshift(...helpers.body);
+	const output = babelGenerate(ast, {
+		sourceMaps: true,
+		sourceFileName: filename,
+		inputSourceMap: JSON.parse(result.map)
+	}, result.code);
+	return `${output.code}\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(output.map)).toString("base64")}`;
+}
+/**
+* 生成配置执行所需的公共辅助模块源码
+*
+* @description 调用方将返回文本写入本轮 runtime.mjs；各助手按传入的源位置解析，动态目标沿用 Node 缓存
+* @returns 可供配置打包使用的 ESM 源码
+*/
+function configRuntimeSource() {
+	return `
+export { createRequire } from 'node:module';
+import { resolve } from ${JSON.stringify(pathToFileURL(createRequire(import.meta.url).resolve("import-meta-resolve")).href)};
+export function createMeta(filename, url, dirname) {
+  return Object.assign(Object.create(null), { filename, url, dirname, main: false, resolve: specifier => resolve(\`\${specifier}\`, url) });
+}
+export async function importFrom(specifier, url, options) {
+  return import(resolve(\`\${specifier}\`, url), options);
+}
+`;
+}
+//#endregion
+//#region src/logger.ts
+/**
+* 调试日志工具
+* 基于 debug 包做分级日志输出
+* 通过环境变量 DEBUG=vite-plugin-uni-pages:* 开启
+*/
+const debug = {
+	/** HMR 相关日志 */
+	hmr: Debug("vite-plugin-uni-pages:hmr"),
+	/** 配置项相关日志 */
+	options: Debug("vite-plugin-uni-pages:options"),
+	/** 主包页面扫描日志 */
+	pages: Debug("vite-plugin-uni-pages:pages"),
+	/** 分包页面扫描日志 */
+	subPages: Debug("vite-plugin-uni-pages:subPages"),
+	/** 错误日志 */
+	error: Debug("vite-plugin-uni-pages:error"),
+	/** 缓存相关日志 */
+	cache: Debug("vite-plugin-uni-pages:cache"),
+	/** 声明文件生成日志 */
+	declaration: Debug("vite-plugin-uni-pages:declaration"),
+	/** definePage 宏解析日志 */
+	definePage: Debug("vite-plugin-uni-pages:definePage")
+};
+//#endregion
+//#region src/config-loader.ts
+const scriptExtensions = /\.[cm]?[jt]sx?$/;
+/** 目录恢复监听接受的文件类型；已知配置入口与依赖不受此限制 */
+const configFileExtensions = /\.(?:[cm]?[jt]sx?|json)$/;
+/** 省略扩展名时 esbuild 会依次尝试的后缀，用于列举恢复候选文件 */
+const candidateExtensions = [
+	"",
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mts",
+	".cts",
+	".mjs",
+	".cjs",
+	".json"
+];
+/** TS 约定里 `./x.js` 指向的就是 `./x.ts`，恢复候选也得列上 */
+const typescriptAliases = {
+	".cjs": [".cts"],
+	".js": [".ts", ".tsx"],
+	".mjs": [".mts"]
+};
+function isNodeModulesPath(filepath) {
+	return normalizePath(filepath).split("/").includes("node_modules");
+}
+/** JSON 文件可能带 BOM 保存，JSON.parse 不接受它 */
+function stripBom(code) {
+	return code.charCodeAt(0) === 65279 ? code.slice(1) : code;
+}
+/**
+* 由失败的导入说明符推出可能出现的文件
+*
+* @description `./missing/title` 这种缺扩展名的写法，创建 `title.ts`
+* 或 `title/index.ts` 都算恢复，所以两种形态都要列出来
+*/
+function recoveryCandidatesFor(specifier, importerDirectory) {
+	const base = path.resolve(importerDirectory, specifier);
+	const candidates = candidateExtensions.map((extension) => `${base}${extension}`);
+	for (const extension of candidateExtensions.slice(1)) candidates.push(path.join(base, `index${extension}`));
+	for (const [extension, aliases] of Object.entries(typescriptAliases)) if (base.endsWith(extension)) for (const alias of aliases) candidates.push(`${base.slice(0, -extension.length)}${alias}`);
+	return candidates;
+}
+/** 将已存在和暂时缺失的文件统一到同一绝对路径 */
+function normalizeConfigPath(filepath, root) {
+	const absolute = path.resolve(root, normalizePath(filepath));
+	let parent = absolute;
+	while (!existsSync(parent) && path.dirname(parent) !== parent) parent = path.dirname(parent);
+	try {
+		return normalizePath(path.join(realpathSync.native(parent), path.relative(parent, absolute)));
+	} catch {
+		return normalizePath(absolute);
+	}
+}
+/** 返回可用于监听缺失文件恢复的现存祖先目录 */
+function configWatchDirectory(filepath) {
+	let directory = path.dirname(filepath);
+	while (!existsSync(directory) && path.dirname(directory) !== directory) directory = path.dirname(directory);
+	return normalizePath(directory);
+}
+/**
+* 判断路径是否位于加载器专用产物目录内
+*
+* @param filepath 待判断的绝对路径，应已通过 {@link normalizeConfigPath} 归一化
+* @param directory 专用产物目录的绝对路径；目录本身也算产物
+* @returns 位于目录内时返回 true，相邻前缀或父路径返回 false
+*/
+function isConfigLoaderArtifact(filepath, directory) {
+	const relative = path.relative(directory, filepath);
+	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/**
+* 页面配置加载器
+*
+* @description 按配置源顺序发现并加载首个有效配置，返回配置对象及依赖路径；加载失败时记录恢复路径并抛出错误
+*/
+var PagesConfigLoader = class {
+	root;
+	/** 装载失败时仍需监听重建的入口与已尝试路径 */
+	recoveryPaths = /* @__PURE__ */ new Set();
+	/** 这次失败中具体缺哪个文件；优先按它判断，命中时不看目录 */
+	recoveryCandidates = /* @__PURE__ */ new Set();
+	/** 目录导入的恢复范围，覆盖 package.json 和自定义入口 */
+	recoveryDirectories = /* @__PURE__ */ new Set();
+	knownSources = /* @__PURE__ */ new Set();
+	/** 临时工作目录的物理路径，每轮加载创建独占子目录，输入索引与事件过滤排除此目录 */
+	artifactDirectory;
+	/** 最近一次成功加载的入口及其依赖，失败恢复以它为基准 */
+	lastSources = [];
+	lastDependencies = [];
+	/** 最近一次加载尝试的监听输入；失败时也保留可恢复路径 */
+	currentWatchInput = {
+		sources: [],
+		dependencies: [],
+		recoveryCandidates: [],
+		recoveryDirectories: []
+	};
+	constructor(root) {
+		this.root = root;
+		this.artifactDirectory = normalizeConfigPath(path.join(root, "node_modules/.cache/uni-pages"), root);
+	}
+	/** 监听输入是一份只读快照，调用方不需要理解加载器的恢复状态 */
+	get watchInput() {
+		return this.currentWatchInput;
+	}
+	/**
+	* 按来源顺序加载首个有效配置
+	*
+	* @description 内置 parser 使用转换后的文本；自定义 parser 接收原入口路径并自行读取
+	* @returns 配置对象、已加载入口及参与监听的依赖路径；没有有效配置时配置对象为空
+	* @throws 配置读取、转换、解析或执行失败时抛出错误
+	*/
+	async load(sources) {
+		this.recoveryCandidates.clear();
+		this.recoveryDirectories.clear();
+		const dependencies = /* @__PURE__ */ new Set();
+		const attemptedPaths = /* @__PURE__ */ new Set();
+		const normalize = (filepath) => normalizeConfigPath(filepath, this.root);
+		const adapted = sources.map((source) => ({
+			...source,
+			transform: void 0,
+			parser: async (filepath) => {
+				attemptedPaths.add(normalize(filepath));
+				if (typeof source.parser === "function") {
+					if (source.transform) await source.transform(await readFile(filepath, "utf8"), filepath);
+					return source.parser(filepath);
+				}
+				let code = await readFile(filepath, "utf8");
+				if (source.transform) code = await source.transform(code, filepath) || code;
+				const parser = source.parser || "auto";
+				if (parser === "json" || path.extname(filepath) === ".json") return JSON.parse(stripBom(code));
+				if (parser === "auto") try {
+					return JSON.parse(stripBom(code));
+				} catch {}
+				return this.loadScript(filepath, code, dependencies, attemptedPaths);
+			}
+		}));
+		try {
+			const result = await loadConfig({
+				cwd: this.root,
+				sources: adapted,
+				defaults: {}
+			});
+			this.recoveryPaths.clear();
+			this.recoveryCandidates.clear();
+			this.recoveryDirectories.clear();
+			for (const source of result.sources) this.knownSources.add(normalize(source));
+			for (const source of this.knownSources) if (!existsSync(source)) dependencies.add(source);
+			const sources = result.sources.map(normalize);
+			const dependencyPaths = [...dependencies];
+			this.lastSources = sources;
+			this.lastDependencies = dependencyPaths;
+			this.currentWatchInput = {
+				sources,
+				dependencies: dependencyPaths,
+				recoveryCandidates: [],
+				recoveryDirectories: []
+			};
+			return {
+				config: result.config,
+				sources,
+				dependencies: dependencyPaths
+			};
+		} catch (error) {
+			this.recoveryPaths.clear();
+			for (const filepath of attemptedPaths) this.recoveryPaths.add(filepath);
+			this.currentWatchInput = {
+				sources: [...this.lastSources],
+				dependencies: [.../* @__PURE__ */ new Set([...this.lastDependencies, ...this.recoveryPaths])],
+				recoveryCandidates: [...this.recoveryCandidates],
+				recoveryDirectories: [...this.recoveryDirectories]
+			};
+			throw error;
+		}
+	}
+	/**
+	* 打包并执行脚本配置，返回其导出的配置对象
+	*
+	* @param source 原配置入口路径，作为入口导入和运行时相对路径的解析基准
+	* @param code 经过可选 transform 处理的入口文本，依赖模块按各自路径读取
+	* @param dependencies 接收成功打包涉及的本地依赖路径
+	* @param attempted 接收本轮尝试读取的本地源路径，供执行失败后恢复监听
+	*/
+	async loadScript(source, code, dependencies, attempted) {
+		const sourcePath = normalizeConfigPath(source, this.root);
+		const importDirectories = /* @__PURE__ */ new Set();
+		const recoveryCandidates = /* @__PURE__ */ new Set();
+		const root = this.root;
+		const cacheDirectory = this.artifactDirectory;
+		mkdirSync(cacheDirectory, { recursive: true });
+		const bundleDirectory = await mkdtemp(path.join(cacheDirectory, "load-"));
+		const runtime = normalizePath(path.join(bundleDirectory, "runtime.mjs"));
+		const entry = scriptExtensions.test(source) ? source : path.join(bundleDirectory, "entry.ts");
+		try {
+			await writeFile(runtime, configRuntimeSource());
+			const { mod, dependencies: inputs } = await bundleRequire({
+				filepath: entry,
+				cwd: this.root,
+				format: "esm",
+				tsconfig: false,
+				preserveTemporaryFile: true,
+				getOutputFile: () => path.join(bundleDirectory, "config.mjs"),
+				notExternal: [/.*/],
+				esbuildOptions: {
+					logLevel: "silent",
+					target: "node22",
+					conditions: [],
+					mainFields: ["main"],
+					resolveExtensions: [
+						".ts",
+						".tsx",
+						".mts",
+						".cts",
+						".js",
+						".jsx",
+						".mjs",
+						".cjs",
+						".json"
+					],
+					banner: { js: `import { createRequire as __uniPagesCreateRequire } from 'node:module'; const require = __uniPagesCreateRequire(import.meta.url);` },
+					plugins: [{
+						name: "uni-pages-config-inputs",
+						setup(build) {
+							build.onResolve({ filter: /.*/ }, async (args) => {
+								if (args.kind === "entry-point") return { path: path.resolve(sourcePath) };
+								if (args.pluginData?.resolvingPackage) return;
+								if (/^(?:node:|file:|data:)/.test(args.path)) return {
+									path: args.path,
+									external: true
+								};
+								if (args.path.startsWith(".") || path.isAbsolute(args.path)) {
+									const directory = normalizeConfigPath(path.resolve(args.resolveDir, args.path), root);
+									if (!isNodeModulesPath(directory) && !isConfigLoaderArtifact(directory, cacheDirectory)) {
+										importDirectories.add(directory);
+										for (const candidate of recoveryCandidatesFor(args.path, args.resolveDir)) recoveryCandidates.add(normalizeConfigPath(candidate, root));
+									}
+									return;
+								}
+								const result = await build.resolve(args.path, {
+									importer: args.importer,
+									resolveDir: args.resolveDir,
+									kind: args.kind,
+									namespace: args.namespace,
+									pluginData: { resolvingPackage: true }
+								});
+								if (result.errors.length) return {
+									errors: result.errors,
+									warnings: result.warnings
+								};
+								if (path.isAbsolute(result.path) && (!isNodeModulesPath(result.path) || /\.(?:[cm]?tsx?|json)$/.test(result.path))) return { path: result.path };
+								return {
+									path: !(args.kind === "require-call" || args.kind === "require-resolve") && path.isAbsolute(result.path) ? pathToFileURL(result.path).href : result.path,
+									external: true
+								};
+							});
+							build.onLoad({
+								filter: /.*/,
+								namespace: "file"
+							}, async (args) => {
+								const file = normalizeConfigPath(args.path, root);
+								if (file === runtime) return {
+									contents: await readFile(runtime, "utf8"),
+									loader: "js"
+								};
+								if (!isNodeModulesPath(file) && !isConfigLoaderArtifact(file, cacheDirectory)) attempted.add(file);
+								if (file !== sourcePath && !scriptExtensions.test(file)) return;
+								return {
+									contents: await transformConfigSource(file === sourcePath ? code : await readFile(args.path, "utf8"), path.resolve(file), runtime),
+									loader: "js"
+								};
+							});
+						}
+					}]
+				}
+			});
+			for (const input of inputs) {
+				const file = normalizeConfigPath(input, root);
+				if (!isNodeModulesPath(file) && !isConfigLoaderArtifact(file, cacheDirectory)) dependencies.add(file);
+			}
+			for (const directory of importDirectories) {
+				const manifest = normalizeConfigPath(path.join(directory, "package.json"), root);
+				if (existsSync(manifest) && !isNodeModulesPath(manifest) && !isConfigLoaderArtifact(manifest, cacheDirectory)) dependencies.add(manifest);
+			}
+			return unwrapConfig(mod.default ?? mod);
+		} catch (error) {
+			if (Array.isArray(error?.errors)) {
+				for (const candidate of recoveryCandidates) if (!existsSync(candidate)) this.recoveryCandidates.add(candidate);
+				for (const directory of importDirectories) this.recoveryDirectories.add(directory);
+			}
+			throw error;
+		} finally {
+			try {
+				await rm(bundleDirectory, {
+					recursive: true,
+					force: true,
+					maxRetries: 3,
+					retryDelay: 50
+				});
+			} catch (error) {
+				debug.error("Failed to remove config loader directory %s:", bundleDirectory, error);
+			}
+		}
+	}
+};
+function unwrapConfig(value) {
+	if (value === null || typeof value !== "object" || !("default" in value) || value.default === null || typeof value.default !== "object") return value;
+	const result = value.default;
+	for (const [key, item] of Object.entries(value)) {
+		if (key === "default" || key in result || item === result) continue;
+		try {
+			Object.defineProperty(result, key, {
+				configurable: true,
+				enumerable: true,
+				get: () => value[key]
+			});
+		} catch {}
+	}
+	return result;
+}
+//#endregion
 //#region src/constant.ts
 /** Vite 模块解析用的虚拟模块标识 */
 const MODULE_ID_VIRTUAL = "virtual:uni-pages";
@@ -34,6 +467,84 @@ const FILE_EXTENSIONS = [
 	"uvue"
 ];
 //#endregion
+//#region src/config-watch.ts
+function isWithin(directory, file) {
+	const normalized = directory.replace(/\/$/, "");
+	return file === normalized || file.startsWith(`${normalized}/`);
+}
+/** 把一次加载的输入归一化为可注册、可匹配的监听计划 */
+function buildConfigWatchPlan(input) {
+	const files = [...new Set([
+		...input.sourcePaths,
+		...input.dependencyPaths,
+		...input.recoveryCandidates ?? []
+	].map((file) => normalizeConfigPath(file, input.root)).filter((file) => !isConfigLoaderArtifact(file, input.artifactDirectory)))];
+	const directories = [...new Set((input.recoveryDirectories ?? []).map((dir) => normalizeConfigPath(dir, input.root)))];
+	return {
+		files,
+		directories,
+		paths: [.../* @__PURE__ */ new Set([
+			...files,
+			...files.map(configWatchDirectory),
+			...directories.map((dir) => configWatchDirectory(path.join(dir, "_")))
+		])]
+	};
+}
+/**
+* 配置事件判定与监听集合的当前视图。
+*
+* 监听器只新增路径、从不退回（chokidar 对文件 unwatch 会拆掉父目录监听），
+* 所以真正决定事件是否触发的始终是最近一次 `update` 的依赖集合；
+* `expanded` 用来在依赖集合扩大后补跑一轮生成。
+*/
+var ConfigWatchIndex = class {
+	root;
+	artifactDirectory;
+	plan = {
+		files: [],
+		directories: [],
+		paths: []
+	};
+	files = /* @__PURE__ */ new Set();
+	initialized = false;
+	expanded = false;
+	constructor(root, artifactDirectory) {
+		this.root = root;
+		this.artifactDirectory = artifactDirectory;
+	}
+	update(plan) {
+		const nextFiles = new Set(plan.files);
+		if (this.initialized && [...nextFiles].some((file) => !this.files.has(file))) this.expanded = true;
+		this.plan = plan;
+		this.files = nextFiles;
+		this.initialized = true;
+	}
+	/**
+	* 返回事件对应的归一化配置路径；不是当前配置输入时返回 undefined。
+	*
+	* 直接命中已知依赖时保留事件路径，避免为了识别符号链接别名而额外查
+	* 文件系统；未命中时才按真实路径归一化，覆盖别名和冗余路径段。
+	*/
+	match(filepath, excluded) {
+		const eventPath = normalizePath(path.resolve(this.root, normalizePath(filepath)));
+		if (excluded.includes(eventPath) || isConfigLoaderArtifact(eventPath, this.artifactDirectory)) return;
+		const absolute = this.files.has(eventPath) ? eventPath : normalizeConfigPath(filepath, this.root);
+		if (excluded.includes(absolute) || isConfigLoaderArtifact(absolute, this.artifactDirectory)) return;
+		const mightBeConfig = configFileExtensions.test(path.basename(filepath));
+		return this.files.has(absolute) || mightBeConfig && this.plan.directories.some((directory) => isWithin(directory, absolute)) ? absolute : void 0;
+	}
+	/** 共享 watcher 已覆盖的根目录无需重复注册，也不能撤销 */
+	watchPaths(sharedRoot) {
+		return this.plan.paths.filter((file) => !sharedRoot || file !== sharedRoot && !isWithin(sharedRoot, file));
+	}
+	/** 依赖集合在上一次生成期间扩大时，消费一次补跑标记 */
+	consumeExpanded() {
+		const expanded = this.expanded;
+		this.expanded = false;
+		return expanded;
+	}
+};
+//#endregion
 //#region src/declaration.ts
 /**
 * 生成 TypeScript 声明文件内容
@@ -107,43 +618,118 @@ async function writeDeclaration(input, filepath) {
 	if (code !== originalContent) await writeFile$1(filepath, code);
 }
 //#endregion
-//#region src/logger.ts
+//#region src/page-rules.ts
+const ruleCache = /* @__PURE__ */ new WeakMap();
 /**
-* 调试日志工具
-* 基于 debug 包做分级日志输出
-* 通过环境变量 DEBUG=vite-plugin-uni-pages:* 开启
+* 编译以项目根为基准的规则，不查询目录是否存在
+*
+* @description 排除同时作用于路径自身和祖先；空模式忽略，否定排除报错，extglob 保留
 */
-const debug = {
-	/** HMR 相关日志 */
-	hmr: Debug("vite-plugin-uni-pages:hmr"),
-	/** 配置项相关日志 */
-	options: Debug("vite-plugin-uni-pages:options"),
-	/** 主包页面扫描日志 */
-	pages: Debug("vite-plugin-uni-pages:pages"),
-	/** 子包页面扫描日志 */
-	subPages: Debug("vite-plugin-uni-pages:subPages"),
-	/** 错误日志 */
-	error: Debug("vite-plugin-uni-pages:error"),
-	/** 缓存相关日志 */
-	cache: Debug("vite-plugin-uni-pages:cache"),
-	/** 声明文件生成日志 */
-	declaration: Debug("vite-plugin-uni-pages:declaration"),
-	/** definePage 宏解析日志 */
-	definePage: Debug("vite-plugin-uni-pages:definePage")
-};
+function compilePageRules(root, patterns, exclude) {
+	const absoluteRoot = normalizePath(path.resolve(root));
+	const escapedRoot = escapePath(absoluteRoot);
+	const relative = (absolute) => normalizePath(path.relative(absoluteRoot, absolute)) || ".";
+	const matchOptions = {
+		dot: true,
+		posix: true
+	};
+	const compilePattern = (pattern) => {
+		const portable = process.platform === "win32" ? pattern.replace(/\\(?![()[\]{}!+@])/g, "/") : pattern;
+		const absolute = path.isAbsolute(portable);
+		let normalized = absolute ? path.posix.normalize(portable) : path.posix.relative(escapedRoot, path.posix.resolve(escapedRoot, portable)) || ".";
+		if (absolute && normalized !== normalizePath(path.parse(portable).root)) normalized = normalized.replace(/\/$/, "");
+		const matches = picomatch(normalized, matchOptions);
+		return {
+			pattern: normalized,
+			absolute,
+			matches: (candidate) => matches(absolute ? normalizePath(candidate) : relative(candidate))
+		};
+	};
+	const exclusions = exclude.filter((pattern) => pattern !== "").map((pattern) => {
+		if (picomatch.scan(pattern).negated) throw new Error(`[vite-plugin-uni-pages] Negative exclude pattern "${pattern}" cannot re-include pages. Remove it from exclude.`);
+		return compilePattern(pattern);
+	});
+	const directoryPatterns = patterns.filter((pattern) => pattern !== "" && !picomatch.scan(pattern).negated);
+	const directories = directoryPatterns.map(compilePattern);
+	const isExcluded = (absoluteRulePath, cache) => {
+		let current = path.resolve(absoluteRulePath);
+		const visited = cache ? [] : void 0;
+		let excluded = false;
+		while (true) {
+			const cached = cache?.get(current);
+			if (cached !== void 0) {
+				excluded = cached;
+				break;
+			}
+			visited?.push(current);
+			if (exclusions.some((rule) => rule.matches(current))) {
+				excluded = true;
+				break;
+			}
+			const parent = path.dirname(current);
+			if (parent === current) break;
+			current = parent;
+		}
+		if (cache && visited) for (const directory of visited) cache.set(directory, excluded);
+		return excluded;
+	};
+	return {
+		patterns: directoryPatterns,
+		traversalIgnores: exclusions.filter((rule) => !rule.absolute && !/[!()[\]{}\\+@|]/.test(rule.pattern)).map((rule) => rule.pattern),
+		isExcluded,
+		createExcludeFilter: () => {
+			const cache = /* @__PURE__ */ new Map();
+			return (absolute) => isExcluded(absolute, cache);
+		},
+		matchesDirectory: (absolute) => !isExcluded(absolute) && directories.some((rule) => rule.matches(absolute))
+	};
+}
+/** 复用当前声明的编译结果，原地修改路径规则或排除项后重新编译 */
+function getPageRules(options) {
+	const patterns = [options.dir, ...options.subPackagePatterns.map((pattern) => typeof pattern === "string" ? pattern : pattern.dir)];
+	const fingerprint = JSON.stringify([
+		options.root,
+		patterns,
+		options.exclude
+	]);
+	const cached = ruleCache.get(options);
+	if (cached?.fingerprint === fingerprint) return cached.rules;
+	const rules = compilePageRules(options.root, patterns, options.exclude);
+	ruleCache.set(options, {
+		fingerprint,
+		rules
+	});
+	return rules;
+}
 //#endregion
 //#region src/files.ts
 /**
-* 解析给定上下文下可作为有效页面的文件列表。
+* 判断是否为路径缺失或中间路径不是目录的文件系统错误
+*
+* @returns 错误码为 ENOENT 或 ENOTDIR 时返回 true，其他错误及空输入返回 false
+*/
+function isMissingFsError(error) {
+	if (typeof error !== "object" || error === null || !("code" in error)) return false;
+	return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+/**
+* 获取扫描目录中未被排除的页面文件
+*
+* @param directory - 绝对扫描目录，或相对项目根的目录
+* @param options - 已解析的页面选项，排除规则以其中的项目根为基准
+* @returns 相对扫描目录、使用 `/` 分隔的文件路径
 */
-function getPageFiles(path, options) {
-	const { exclude } = options;
+function getPageFiles(directory, options) {
+	const absolute = path.resolve(options.root, directory);
+	const rules = getPageRules(options);
+	if (rules.isExcluded(absolute)) return [];
 	const ext = FILE_EXTENSIONS.length > 1 ? `{${FILE_EXTENSIONS.join(",")}}` : FILE_EXTENSIONS[0] || "";
-	return globSync(`**/*.${ext}`, {
-		ignore: exclude,
+	return globSync(`${escapePath(normalizePath(absolute))}/**/*.${ext}`, {
+		ignore: rules.traversalIgnores,
+		expandDirectories: false,
 		onlyFiles: true,
-		cwd: path
-	});
+		cwd: options.root
+	}).map((file) => path.resolve(options.root, file)).filter((file) => !rules.isExcluded(file)).map((file) => normalizePath(path.relative(absolute, file)));
 }
 /**
 * 检查文件是否为目标页面文件
@@ -183,8 +769,15 @@ function checkPagesJsonFileSync(path) {
 	try {
 		fs.accessSync(path, fs.constants.F_OK);
 	} catch {
-		fs.writeFileSync(path, JSON.stringify({ pages: [{ path: "" }] }, null, 2), { encoding: "utf-8" });
-		return;
+		try {
+			fs.writeFileSync(path, JSON.stringify({ pages: [{ path: "" }] }, null, 2), {
+				encoding: "utf-8",
+				flag: "wx"
+			});
+			return;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
 	}
 	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 {
@@ -216,6 +809,7 @@ const lockQueues = /* @__PURE__ */ new Map();
 * @param task - 在锁内运行的异步任务；返回值原样返回给调用方
 * @param retry - 锁被别人拿着时的重试次数，默认 3
 * @returns `task` 的结果；一直拿不到锁时为 `undefined`
+* @throws 权限不足、路径缺失等非竞争错误原样抛出，不重试
 */
 function withFileLock(path, task, retry = 3) {
 	const current = (lockQueues.get(path) ?? Promise.resolve()).catch(() => {}).then(() => acquireAndRun(path, task, retry));
@@ -228,8 +822,9 @@ async function acquireAndRun(path, task, retry) {
 		let release;
 		try {
 			release = await lockfile.lock(path, { realpath: false });
-		} catch {
-			await sleep(500);
+		} catch (error) {
+			if (error.code !== "ELOCKED") throw error;
+			if (attempt > 1) await sleep(500);
 			continue;
 		}
 		try {
@@ -249,6 +844,348 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 //#endregion
+//#region src/page-sources.ts
+/**
+* 读取本轮页面文件的物理身份
+*
+* @returns 规范化的 native realpath；路径不存在或中间路径不是目录时为 undefined
+* @throws 权限不足等其他文件系统错误原样抛出
+*/
+function resolvePageIdentity(file) {
+	try {
+		return normalizePath(fs.realpathSync.native(file));
+	} catch (error) {
+		if (!isMissingFsError(error)) throw error;
+	}
+}
+/**
+* 比较页面来源的代表优先级
+*
+* @description 显式来源优先，其余按声明和 glob 匹配顺序；相同优先级返回 0
+*/
+function comparePageSources(a, b) {
+	return Number(b.explicitRoot) - Number(a.explicitRoot) || a.ruleIndex - b.ruleIndex || a.matchIndex - b.matchIndex;
+}
+function describeSource(source) {
+	const declaration = source.root === void 0 ? "dir" : `subPackages[${source.ruleIndex}]`;
+	const rule = source.rulePattern === void 0 ? "" : ` rule ${JSON.stringify(source.rulePattern)}`;
+	const owner = source.root === void 0 ? "main package" : `subpackage "${source.root}"`;
+	const rootSource = source.rootSource;
+	const rootOrigin = rootSource ? `, root from subPackages[${rootSource.ruleIndex}] "${rootSource.dir}" (${rootSource.explicitRoot ? "explicit" : "default"})` : "";
+	return `"${source.file}" (${declaration}${rule}, directory "${source.dir}", ${owner}${rootOrigin})`;
+}
+/** 关联记录仅保留来源信息，不携带其他 Page 实例 */
+function toPageSource(candidate) {
+	return {
+		file: candidate.file,
+		identity: candidate.identity,
+		dir: candidate.dir,
+		root: candidate.root,
+		explicitRoot: candidate.explicitRoot,
+		ruleIndex: candidate.ruleIndex,
+		matchIndex: candidate.matchIndex,
+		rootSource: candidate.rootSource
+	};
+}
+function describeRelatedSource(source) {
+	const owner = source.root === void 0 ? "main package" : `subpackage "${source.root}"`;
+	return `"${source.file}" (directory "${source.dir}", ${owner})`;
+}
+function describeRelatedSources(source) {
+	if (source.relatedSources.length === 0) return "";
+	return `; related sources: ${source.relatedSources.map(describeRelatedSource).join(", ")}`;
+}
+/**
+* 为每个物理页面选择一个有效代表来源
+*
+* @description 候选需先通过文件排除，且未被宏结果或平台规则跳过；有效分包优先于主包，
+* 同一归属内按显式来源和声明顺序选择，返回顺序按文件身份首次出现的位置排列，
+* 同身份的其他来源仅保留在代表记录中，用于本轮冲突诊断
+* @param candidates - 本轮有效候选，数组不会被修改
+* @throws 同一物理页面被不同分包 root 认领时抛出来源冲突
+*/
+function selectPageSources(candidates) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const group = groups.get(candidate.identity) ?? [];
+		group.push(candidate);
+		groups.set(candidate.identity, group);
+	}
+	const selected = [];
+	for (const group of groups.values()) {
+		const subPages = group.filter((source) => source.root !== void 0);
+		const first = subPages[0];
+		const conflict = subPages.find((source) => source.root !== first?.root);
+		if (first && conflict) {
+			const explanation = first.ruleIndex >= 0 && first.ruleIndex === conflict.ruleIndex && first.matchIndex !== conflict.matchIndex ? " The same directory rule matched multiple directories containing this page. For one subpackage tree, declare its parent directory once; for multiple entries in the same subpackage, use a common root." : "";
+			throw new Error(`[vite-plugin-uni-pages] Conflicting subpackage ownership: ${describeSource(first)} and ${describeSource(conflict)} refer to the same page "${first.identity}".${explanation}`);
+		}
+		const representative = [...subPages.length ? subPages : group].sort(comparePageSources)[0];
+		const relatedSources = group.filter((source) => source !== representative).map(toPageSource);
+		selected.push({
+			...representative,
+			relatedSources
+		});
+	}
+	return selected;
+}
+/**
+* 获取允许格式或平台变体覆盖的物理文件族
+*
+* @description 格式变体共享去掉扩展名的真实路径；平台后缀只在主包且当前平台适用时处理
+* @returns 支持的真实页面格式对应的文件族，其他格式不参与覆盖例外
+*/
+function fileFamily(source, platform) {
+	const extension = path.extname(source.identity);
+	if (!FILE_EXTENSIONS.includes(extension.slice(1))) return;
+	const stem = source.identity.slice(0, -extension.length);
+	const filename = source.page.uri.slice(source.page.uri.lastIndexOf("/") + 1);
+	if (platform === void 0 || source.root !== void 0 || !filename.includes(".") || !source.page.uri.includes(platform)) return stem;
+	const slash = stem.lastIndexOf("/");
+	const dot = stem.indexOf(".", slash + 1);
+	return dot !== -1 && stem.slice(dot) === filename.slice(filename.indexOf(".")) ? stem.slice(0, dot) : stem;
+}
+/**
+* 校验生成页面是否占用同一完整路由
+*
+* @description 比较时规范化分隔符、点段和末尾斜杠，不改写候选或输出路径
+* @param candidates - 已完成物理身份归属决议的代表来源，需在配置覆盖和输出去重前传入
+* @param platform - 启用主包平台后缀规则时的当前平台，省略时只允许格式变体覆盖
+* @throws 不同生成来源占用同一路由且不属于同一归属的允许文件族时抛出冲突
+*/
+function validateGeneratedRoutes(candidates, platform) {
+	const routes = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const route = path.posix.normalize(candidate.route.replace(/\\/g, "/")).replace(/\/$/, "");
+		const previous = routes.get(route);
+		if (previous && previous.identity !== candidate.identity) {
+			const previousFamily = fileFamily(previous, platform);
+			if (!(previous.root === candidate.root && previousFamily !== void 0 && previousFamily === fileFamily(candidate, platform))) throw new Error(`[vite-plugin-uni-pages] Conflicting generated route "${route}": ${describeSource(previous)}${describeRelatedSources(previous)} and ${describeSource(candidate)}${describeRelatedSources(candidate)}.`);
+		}
+		routes.set(route, candidate);
+	}
+}
+//#endregion
+//#region src/directories.ts
+/**
+* 规范化页面目录选择器中的路径分隔符
+*
+* @description 在 Windows 上将反斜杠路径分隔符转换为 `/`，保留 `\[`、`\(` 等 glob 转义
+*
+* @param pattern 页面目录路径或 glob 表达式
+* @returns Windows 返回规范化后的选择器，其他平台返回原字符串
+*
+* @example
+* ```ts
+* normalizePagePattern('src\\pages') // Windows: 'src/pages'
+* ```
+*/
+function normalizePagePattern(pattern) {
+	return process.platform === "win32" ? pattern.replace(/\\(?![()[\]{}!+@])/g, "/") : pattern;
+}
+/**
+* 将目录选择器中的 glob 转义还原为字面字符
+*
+* @description 用于已经确定的固定路径部分，还原后的字符串可传给 `path.resolve` 等路径 API
+*
+* @param pattern 以 `/` 分隔、可包含 glob 转义的固定目录路径
+* @returns 去除 glob 特殊字符前转义反斜杠的路径字符串
+*
+* @example
+* ```ts
+* unescapePagePattern('src/\\[demo\\]') // 'src/[demo]'
+* ```
+*/
+function unescapePagePattern(pattern) {
+	return pattern.replace(/\\(?=[[\](){}!*+?@|])/g, "");
+}
+function findPageDirs(dir, root, rules) {
+	if (dir === "" || picomatch.scan(dir).negated) return [];
+	const pattern = path.posix.normalize(normalizePagePattern(dir));
+	const scan = picomatch.scan(pattern);
+	if (rules.isExcluded(path.resolve(root, unescapePagePattern(scan.base || ".")))) return [];
+	return globSync(pattern, {
+		ignore: rules.traversalIgnores,
+		onlyDirectories: true,
+		expandDirectories: false,
+		dot: true,
+		cwd: root
+	}).map(normalizePath).filter((directory) => !rules.isExcluded(path.resolve(root, directory))).sort();
+}
+/**
+* 查找当前可扫描的页面目录
+*
+* @description 应用目录排除后，返回相对 root、按路径排序的匹配结果；空规则或否定规则返回空数组
+*
+* @param dir 页面目录 glob，可使用绝对路径
+* @param root 相对目录和相对 exclude 的解析基准
+* @param exclude 目录及页面排除规则
+*/
+function resolvePageDirs(dir, root, exclude) {
+	return findPageDirs(dir, root, compilePageRules(root, [dir], exclude));
+}
+function directoryIdentity(absolute) {
+	try {
+		if (fs.statSync(absolute, { throwIfNoEntry: false })?.isDirectory()) return normalizePath(fs.realpathSync.native(absolute));
+	} catch (error) {
+		if (!isMissingFsError(error)) throw error;
+	}
+}
+function findCallbackDirectory(dir, root, rules) {
+	if (dir === "") return [];
+	const absolute = path.resolve(root, unescapePagePattern(path.posix.normalize(dir)));
+	if (rules.isExcluded(absolute)) return [];
+	try {
+		if (fs.statSync(absolute, { throwIfNoEntry: false })?.isDirectory()) return [normalizePath(path.relative(root, absolute)) || "."];
+	} catch (error) {
+		if (!isMissingFsError(error)) throw error;
+	}
+	return [];
+}
+/** 展开分包声明，返回逐条来源记录和扫描目录投影 */
+function discoverSubPackageDirectories(patterns, root, outDir, exclude) {
+	const rules = compilePageRules(root, [], exclude);
+	const candidates = [];
+	const groups = /* @__PURE__ */ new Map();
+	for (const [ruleIndex, pattern] of patterns.entries()) {
+		const dir = normalizePagePattern(typeof pattern === "string" ? pattern : pattern.dir);
+		if (picomatch.scan(dir).negated) throw new Error("[vite-plugin-uni-pages] Use exclude for negative subpackage patterns.");
+		const customRoot = typeof pattern === "string" ? void 0 : pattern.root;
+		const glob = isDynamicPattern(dir);
+		const dynamic = glob || typeof customRoot === "function";
+		const dirs = glob ? findPageDirs(dir, root, rules) : typeof customRoot === "function" ? findCallbackDirectory(dir, root, rules) : [dir];
+		for (const [matchIndex, matched] of dirs.entries()) {
+			const resolved = dynamic ? matched : unescapePagePattern(matched);
+			const absolute = normalizePath(path.resolve(root, resolved));
+			if (rules.isExcluded(absolute)) continue;
+			const relative = normalizePath(path.relative(root, absolute)) || ".";
+			const resolvedRoot = typeof customRoot === "function" ? customRoot(relative) : customRoot;
+			if (typeof customRoot === "function" && (typeof resolvedRoot !== "string" || !resolvedRoot || resolvedRoot === "." || path.posix.isAbsolute(resolvedRoot) || path.win32.isAbsolute(resolvedRoot) || resolvedRoot.replace(/\\/g, "/").split("/").includes(".."))) throw new Error(`[vite-plugin-uni-pages] Invalid subpackage root returned for "${relative}": expected a non-empty relative path without "..".`);
+			const defaultRoot = normalizePath(path.relative(path.resolve(root, outDir), absolute));
+			const identity = directoryIdentity(absolute);
+			const candidate = {
+				dir: dynamic ? relative : resolved,
+				absolute,
+				identity,
+				root: resolvedRoot === void 0 ? defaultRoot : normalizePath(resolvedRoot),
+				explicitRoot: resolvedRoot !== void 0,
+				ruleIndex,
+				matchIndex,
+				rootSource: {
+					dir: dynamic ? relative : resolved,
+					ruleIndex,
+					explicitRoot: resolvedRoot !== void 0
+				},
+				defaultRoot
+			};
+			candidates.push(candidate);
+			const key = identity ?? absolute;
+			const group = groups.get(key) ?? [];
+			group.push(candidate);
+			groups.set(key, group);
+		}
+	}
+	for (const group of groups.values()) {
+		const explicit = group.filter((candidate) => candidate.explicitRoot);
+		const selected = explicit[0] ?? group[0];
+		for (const candidate of explicit) if (candidate.root !== selected.root) throw new Error(`[vite-plugin-uni-pages] Conflicting subpackage roots: "${selected.dir}" (subPackages[${selected.ruleIndex}]) uses "${selected.root}", but "${candidate.dir}" (subPackages[${candidate.ruleIndex}]) uses "${candidate.root}".`);
+		for (const candidate of group) {
+			candidate.root = selected.root;
+			candidate.rootSource = selected.rootSource;
+		}
+	}
+	const directories = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const previous = directories.get(candidate.absolute);
+		if (!previous || comparePageSources(candidate, previous) < 0) directories.set(candidate.absolute, candidate);
+	}
+	const roots = /* @__PURE__ */ new Map();
+	for (const candidate of directories.values()) if (candidate.explicitRoot || candidate.root !== candidate.defaultRoot) roots.set(candidate.dir, candidate.root);
+	return {
+		sources: candidates.map(({ defaultRoot: _defaultRoot, ...source }) => source),
+		projection: {
+			subPackages: [...directories.values()].map((candidate) => candidate.dir),
+			subPackageRootMap: roots
+		}
+	};
+}
+/**
+* 展开分包目录并确定各目录的最终 root
+*
+* @description 每次调用重新发现目录并求值回调；按声明顺序排列，glob 内按路径排序
+* 同一物理目录的显式 root 优先于默认值，词法别名分别保留，重复目录投影只登记一次
+*
+* @param patterns 原始分包目录声明
+* @param root 相对目录和相对 exclude 的解析基准
+* @param outDir 默认分包 root 的换算基准，相对 root 解析
+* @param exclude 目录及页面排除规则
+* @returns 目录列表及最终 root 映射
+* @throws 目录规则无效、root 回调失败、显式 root 冲突或非缺失类目录访问错误
+*/
+function resolveSubPackageDirs(patterns, root, outDir, exclude) {
+	return discoverSubPackageDirectories(patterns, root, outDir, exclude).projection;
+}
+/**
+* 读取当前分包目录来源
+*
+* @description 每次调用重新发现目录并求值回调；需要与扫描共用同一份结果时，
+* 使用 ScanPlan 而不是在扫描中途再次调用
+*
+* @returns 按声明及匹配顺序排列的来源，调用方应只读使用记录
+* @throws 目录规则、root 决议或目录访问错误
+*/
+function getSubPackageDirectorySources(options) {
+	return discoverSubPackageDirectories(options.subPackagePatterns, options.root, options.outDir, options.exclude).sources;
+}
+/**
+* 刷新扫描目录与分包 root 投影
+*
+* @description 仅用于兼容仍读取 `ResolvedOptions` 的调用方；内部扫描走
+* `createScanPlan()`，每次重新发现目录来源与物理身份，不保留上一轮快照
+*
+* @throws 目录规则、root 决议或目录访问失败时抛出，应中止本轮扫描
+*/
+function refreshPageDirectories(options) {
+	const { projection } = discoverSubPackageDirectories(options.subPackagePatterns, options.root, options.outDir, options.exclude);
+	options.dirs = resolvePageDirs(options.dir, options.root, options.exclude);
+	Object.assign(options, projection);
+}
+function contains$1(directory, entry) {
+	return entry === directory || entry.startsWith(`${directory.replace(/\/$/, "")}/`);
+}
+/**
+* 判断目录事件是否可能改变扫描目录集合
+*
+* @description directory 相对 options.root 解析，允许目录已删除；关闭 mergePages 时返回 false
+*/
+function isPageDirectoryEvent(directory, options) {
+	if (!options.mergePages) return false;
+	const absolute = normalizePath(path.resolve(options.root, directory));
+	const rules = getPageRules(options);
+	if (rules.isExcluded(absolute)) return false;
+	if (rules.matchesDirectory(absolute)) return true;
+	return [...options.dirs, ...options.subPackages].some((dir) => contains$1(absolute, normalizePath(path.resolve(options.root, dir))));
+}
+/**
+* 判断文件路径是否位于当前页面规则内
+*
+* @description file 相对 options.root 解析，按原始规则与 exclude 判断，不要求文件存在或目录已展开
+* 关闭 mergePages 时返回 false，文件扩展名由调用方校验
+*/
+function isPageFileInDirectories(file, options) {
+	if (!options.mergePages) return false;
+	const absolute = normalizePath(path.resolve(options.root, file));
+	const rules = getPageRules(options);
+	if (rules.isExcluded(absolute)) return false;
+	let directory = normalizePath(path.dirname(absolute));
+	while (true) {
+		if (rules.matchesDirectory(directory)) return true;
+		const parent = normalizePath(path.dirname(directory));
+		if (parent === directory) return false;
+		directory = parent;
+	}
+}
+//#endregion
 //#region src/options.ts
 /**
 * 解析用户配置项
@@ -260,30 +1197,24 @@ function sleep(ms) {
 */
 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",
+		"**/node_modules/**",
+		"**/.git/**",
 		"**/__*__/**"
 	], 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 root = normalizePath(resolve(viteRoot || 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(normalizePath(sub));
-	else {
-		const dirPath = normalizePath(sub.dir);
-		resolvedSubDirs.push(dirPath);
-		subPackageRootMap.set(dirPath, sub.root);
-	}
+	const resolvedSubPackages = resolveSubPackageDirs(subPackages, root, outDir, exclude);
 	const resolvedHomePage = typeof homePage === "string" ? [homePage] : homePage;
 	const resolvedConfigSource = typeof configSource === "string" ? [{ files: configSource }] : configSource;
 	return {
-		dts: !dts ? false : typeof dts === "string" ? dts : resolve(viteRoot, "uni-pages.d.ts"),
+		dts: !dts ? false : typeof dts === "string" ? resolve(root, dts) : resolve(root, "uni-pages.d.ts"),
 		configSource: Array.isArray(resolvedConfigSource) ? resolvedConfigSource : [resolvedConfigSource],
 		homePage: resolvedHomePage,
 		mergePages,
+		dir,
 		dirs: resolvedDirs,
-		subPackages: resolvedSubDirs,
-		subPackageRootMap,
+		subPackagePatterns: subPackages,
+		...resolvedSubPackages,
 		outDir,
 		exclude,
 		root,
@@ -302,22 +1233,6 @@ function resolveOptions(userOptions, viteRoot = process.cwd()) {
 		onAfterWriteFile
 	};
 }
-/**
-* 根据给定的 glob 模式解析页面目录
-* @param dir - 页面目录 glob 模式
-* @param root - 项目根目录
-* @param exclude - 需要排除的 glob 模式
-* @returns 匹配到的目录路径
-*/
-function resolvePageDirs(dir, root, exclude) {
-	return globSync(normalizePath(dir), {
-		ignore: exclude,
-		onlyDirectories: true,
-		expandDirectories: false,
-		dot: true,
-		cwd: root
-	});
-}
 //#endregion
 //#region src/condition.ts
 /** 判断一个值是否为普通对象（非 null、非数组） */
@@ -694,97 +1609,84 @@ async function parseCode(options) {
 //#endregion
 //#region src/page.ts
 /**
-* 表示一个 Vue 页面文件的 Page 类
+* 表示一个 Vue 页面文件的读取适配器
 *
-* 职责：
-* 1. 读取页面文件内容
-* 2. 解析 definePage 宏定义的页面配置
-* 3. 提供 tabBar 配置信息
-* 4. 跟踪页面文件变更状态
+* 调用方只需要 `load()`：文件读取、宏求值、跳过状态、tabBar 补全和
+* 变更检测都在快照里返回。`getPageMeta` / `getTabBar` 保留为兼容入口。
 */
 var Page = class {
-	/** 页面上下文实例 */
-	ctx;
+	environment;
 	/** 页面路径信息，包含相对路径与绝对路径 */
 	path;
 	/** 页面 URI，用于 pages.json 的 path 字段 */
 	uri;
-	/** 页面是否发生变化，用于增量更新判断 */
-	changed = true;
-	/**
-	* 页面是否通过 `definePage(null)` 或函数式宏在当前平台返回 null 而
-	* 退出了 pages.json
-	*/
-	skipped = false;
-	/** 页面文件是否至少被读取过一次 */
+	snapshot;
+	/** 当前读取缓存是否有效 */
 	loaded = false;
-	/** 页面配置的原始 JSON 字符串，用于变更检测 */
+	/** 当前缓存是否已尝试读取；失败后等下次失效再重试 */
+	readAttempted = false;
+	/** 上一次成功读取的配置，用于变更检测 */
 	raw = "";
-	/** 解析后的页面配置 */
-	meta;
-	/**
-	* 创建页面实例
-	* @param ctx - 页面上下文实例
-	* @param path - 页面路径信息
-	*/
-	constructor(ctx, path) {
-		this.ctx = ctx;
+	constructor(environment, path) {
+		this.environment = environment;
 		this.path = path;
 		const ext = extname(path.relativePath);
 		this.uri = normalizePath(ext ? path.relativePath.slice(0, -ext.length) : path.relativePath);
 	}
+	/** 页面是否通过 definePage(null) 退出 */
+	get skipped() {
+		return this.snapshot?.skipped ?? false;
+	}
+	/** 页面内容是否相对上次成功读取发生变化 */
+	get changed() {
+		return this.snapshot?.changed ?? true;
+	}
 	/**
-	* 获取页面配置
-	* 解析 definePage 宏定义的配置并返回用于 pages.json 的配置
+	* 读取页面并返回快照
 	*
-	* @param forceUpdate - 是否强制更新，忽略缓存
-	* @returns 页面配置对象
+	* @param forceUpdate - 忽略缓存强制重读
 	*/
-	async getPageMeta(forceUpdate = false) {
-		if (forceUpdate || !this.loaded) await this.read();
-		const { path, tabBar: _, ...others } = this.meta || {};
-		return {
-			path: path ?? this.uri,
-			...others
-		};
+	async load(forceUpdate = false) {
+		if (forceUpdate || !this.loaded && !this.readAttempted) await this.read();
+		return this.snapshot ?? this.fallbackSnapshot();
 	}
 	/**
-	* 获取页面 tabBar 配置
-	* 从 definePage 宏中提取 tabBar 相关配置
+	* 获取页面配置，保留给既有调用方
 	*
-	* @param forceUpdate - 是否强制更新，忽略缓存
-	* @returns tabBar 配置对象，页面未定义 tabBar 时返回 undefined
+	* 返回副本：合并阶段会原地写 `type: 'home'`，不能让首页标记留在
+	* 读取快照里，否则增量更新会继续把旧首页当成首页。
 	*/
+	async getPageMeta(forceUpdate = false) {
+		return { ...(await this.load(forceUpdate)).meta };
+	}
+	/** 获取 tabBar 项，保留给既有调用方 */
 	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
-		};
+		return (await this.load(forceUpdate)).tabBar;
 	}
-	/**
-	* 确保页面文件至少被读取过一次，使 `skipped` 与缓存的配置反映
-	* 当前文件内容
-	*/
+	/** 加载尚未读取的页面配置，缓存失效前不重复尝试失败的读取 */
 	async ensureLoaded() {
-		if (!this.loaded) await this.read();
+		await this.load();
 	}
 	/**
-	* 检查页面是否发生变化
-	* @returns 页面是否发生变化
+	* 使页面读取缓存失效
+	*
+	* @description 下次访问时重新读取，保留上次成功快照作为读取失败时的回退
 	*/
+	invalidate() {
+		this.loaded = false;
+		this.readAttempted = false;
+	}
+	/** 检查页面是否发生变化 */
 	hasChanged() {
 		return this.changed;
 	}
 	/**
 	* 读取页面文件并解析配置
-	* 从 Vue SFC 中提取 definePage 宏定义的配置
+	*
+	* @description 成功后替换快照；失败时保留上次成功快照，只记录警告
 	*/
 	async read() {
+		this.readAttempted = true;
 		let meta;
 		let skipped = false;
 		try {
@@ -793,22 +1695,46 @@ var Page = class {
 			else meta = result;
 		} catch (err) {
 			debug.error(err);
-			this.ctx.logger?.warn(err?.message ?? String(err), { timestamp: true });
+			(this.environment.getLogger?.())?.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;
+		const changed = this.raw !== raw || this.skipped !== skipped;
 		this.raw = raw;
-		this.skipped = skipped;
+		this.loaded = true;
+		this.snapshot = this.createSnapshot(meta, skipped, changed);
+	}
+	createSnapshot(meta, skipped, changed) {
+		const { path, tabBar, ...others } = meta ?? {};
+		return {
+			meta: {
+				path: path ?? this.uri,
+				...others
+			},
+			tabBar: !skipped && tabBar ? {
+				...tabBar,
+				pagePath: tabBar.pagePath || this.uri,
+				index: tabBar.index ?? 0
+			} : void 0,
+			skipped,
+			changed
+		};
+	}
+	/** 读取失败且从未成功时的默认快照，保持页面仍以 uri 参与生成 */
+	fallbackSnapshot() {
+		return {
+			meta: { path: this.uri },
+			tabBar: void 0,
+			skipped: false,
+			changed: true
+		};
 	}
 	async readPageMetaFromFile() {
 		try {
-			const meta = await evaluateDefinePage(await fs.promises.readFile(this.path.absolutePath, { encoding: "utf-8" }), this.path.absolutePath, this.ctx.platform);
+			const meta = await evaluateDefinePage(await fs.promises.readFile(this.path.absolutePath, { encoding: "utf-8" }), this.path.absolutePath, this.environment.platform);
 			return meta === void 0 ? { type: "page" } : meta;
 		} catch (err) {
 			throw new Error(`Read page meta fail in ${this.path.relativePath}\n${err.message}`);
@@ -816,6 +1742,619 @@ var Page = class {
 	}
 };
 //#endregion
+//#region src/page-watch-filter.ts
+/**
+* 编译 Vite 的 ignored 规则，匹配单个页面来源的词法路径
+*
+* @description 返回 true 表示忽略；否定模式优先于其他匹配，目录祖先由调用方检查
+* @param ignored - Vite 的字符串、正则或函数过滤规则
+* @param root - 待检查路径的解析基准
+* @param cwd - watcher 为相对字符串规则指定的基准；未指定时与 chokidar 一致使用 process.cwd()
+*/
+function createPageWatchFilter(ignored, root, cwd = process.cwd()) {
+	const base = cwd || process.cwd();
+	const normalized = (ignored === void 0 ? [] : Array.isArray(ignored) ? ignored : [ignored]).map((matcher) => {
+		if (typeof matcher !== "string") return matcher;
+		const negative = matcher.startsWith("!");
+		const pattern = negative ? matcher.slice(1) : matcher;
+		const resolved = path.isAbsolute(pattern) || pattern.startsWith("**/") || pattern.startsWith("**\\") ? normalizePath(pattern) : normalizePath(path.resolve(path.join(base, pattern)));
+		return negative ? `!${resolved}` : resolved;
+	});
+	const matchers = [...normalized, ...normalized.filter((matcher) => typeof matcher === "string" && !matcher.startsWith("!") && !picomatch.scan(matcher).isGlob).map((matcher) => `${matcher}/**`)];
+	const negative = matchers.filter((matcher) => typeof matcher === "string" && matcher.startsWith("!")).map((matcher) => picomatch(matcher.slice(1), { dot: true }));
+	const positive = matchers.filter((matcher) => typeof matcher !== "string" || !matcher.startsWith("!")).map((matcher) => {
+		if (typeof matcher === "function") return matcher;
+		if (matcher instanceof RegExp) return (file) => matcher.test(file);
+		const matches = picomatch(matcher, { dot: true });
+		return (file) => file === matcher || matches(file);
+	});
+	return (file, stats) => {
+		const absolute = normalizePath(path.resolve(root, file));
+		return !negative.some((matches) => matches(absolute)) && positive.some((matches) => matches(absolute, stats));
+	};
+}
+//#endregion
+//#region src/page-watch-sources.ts
+/** 单轮来源发现最多登记的链接来源数，避免别名层叠造成指数级遍历和订阅膨胀 */
+const PAGE_WATCH_SOURCE_LIMIT = 1024;
+/** 目标不可访问与缺失一样按暂不可用处理，权限恢复后再由后续刷新重新发现 */
+function isUnavailableSourceError(error) {
+	if (typeof error !== "object" || error === null || !("code" in error)) return false;
+	const code = error.code;
+	return code === "EACCES" || code === "EPERM";
+}
+/**
+* 将监听目标统一到真实路径
+*
+* @description 与事件 identity 使用同一基准，避免目标拼写差异（大小写、Unicode
+* 规范化）导致映射失败；尚未创建的部分保留在最近存在祖先的真实路径下
+*/
+function canonicalTargetPath(target) {
+	let current = target;
+	const missing = [];
+	while (true) try {
+		const real = fs.realpathSync.native(current);
+		return normalizePath(missing.length ? path.join(real, ...missing) : real);
+	} catch (error) {
+		if (!isMissingFsError(error)) return normalizePath(target);
+		const parent = path.dirname(current);
+		if (parent === current) return normalizePath(target);
+		missing.unshift(path.basename(current));
+		current = parent;
+	}
+}
+/** 逐段解析链接，保留悬空目标及恢复所需的链接入口 */
+function resolveWatchTarget(source) {
+	let remaining = path.resolve(source);
+	const links = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	while (!visited.has(remaining) && visited.size < 40) {
+		visited.add(remaining);
+		const root = path.parse(remaining).root;
+		const parts = remaining.slice(root.length).split(path.sep).filter(Boolean);
+		let current = root;
+		let redirected = false;
+		let stat;
+		for (const [index, part] of parts.entries()) {
+			current = path.join(current, part);
+			try {
+				stat = fs.lstatSync(current, { bigint: true });
+				if (stat.isSymbolicLink()) {
+					links.add(normalizePath(current));
+					let linkTarget;
+					try {
+						linkTarget = fs.readlinkSync(current);
+					} catch (error) {
+						if (!isMissingFsError(error) && !isUnavailableSourceError(error)) throw error;
+						return {
+							target: canonicalTargetPath(path.join(current, ...parts.slice(index + 1))),
+							exists: false,
+							links: [...links]
+						};
+					}
+					remaining = path.resolve(path.dirname(current), linkTarget, ...parts.slice(index + 1));
+					redirected = true;
+					break;
+				}
+			} catch (error) {
+				if (!isMissingFsError(error) && !isUnavailableSourceError(error)) throw error;
+				return {
+					target: canonicalTargetPath(path.join(current, ...parts.slice(index + 1))),
+					exists: false,
+					links: [...links]
+				};
+			}
+		}
+		if (!redirected) {
+			stat ??= fs.lstatSync(root, { bigint: true });
+			return {
+				target: canonicalTargetPath(current),
+				exists: true,
+				links: [...links],
+				kind: stat.isDirectory() ? "directory" : "file",
+				identity: `${stat.dev}:${stat.ino}`
+			};
+		}
+	}
+	return {
+		target: canonicalTargetPath(remaining),
+		exists: false,
+		links: [...links]
+	};
+}
+/**
+* 发现声明目录及其嵌套链接的监听依赖
+*
+* @description 按词法入口应用过滤；同目标的别名分别保留，只有当前祖先链中的循环停止展开
+* 链接来源超过 {@link PAGE_WATCH_SOURCE_LIMIT} 时停止继续展开，页面扫描与生成不受影响
+*/
+function collectPageWatchSources(roots, excluded) {
+	const directories = /* @__PURE__ */ new Map();
+	const files = /* @__PURE__ */ new Map();
+	const links = /* @__PURE__ */ new Set();
+	const entries = /* @__PURE__ */ new Map();
+	let discovered = 0;
+	let truncated = false;
+	const visit = (source, target, ancestors) => {
+		if (truncated || ancestors.has(target)) return;
+		const branch = new Set(ancestors).add(target);
+		let children = entries.get(target);
+		if (!children) {
+			try {
+				children = fs.readdirSync(target, { withFileTypes: true });
+			} catch (error) {
+				if (!isMissingFsError(error) && !isUnavailableSourceError(error)) throw error;
+				return;
+			}
+			entries.set(target, children);
+		}
+		for (const child of children) {
+			if (truncated) return;
+			if (!child.isDirectory() && !child.isSymbolicLink()) continue;
+			const lexical = normalizePath(path.join(source, child.name));
+			if (excluded(lexical)) continue;
+			if (child.isSymbolicLink()) {
+				if (discovered >= 1024) {
+					truncated = true;
+					return;
+				}
+				const resolved = resolveWatchTarget(lexical);
+				const file = resolved.kind === "file" || !resolved.exists && isTargetFile(lexical);
+				if (file && !isTargetFile(lexical)) continue;
+				discovered++;
+				for (const link of resolved.links) links.add(link);
+				if (file) files.set(lexical, resolved);
+				else {
+					directories.set(lexical, resolved);
+					if (resolved.exists) visit(lexical, resolved.target, branch);
+				}
+			} else visit(lexical, normalizePath(path.join(target, child.name)), branch);
+		}
+	};
+	for (const root of roots) {
+		if (truncated) break;
+		if (excluded(root)) continue;
+		const resolved = resolveWatchTarget(root);
+		directories.set(root, resolved);
+		for (const link of resolved.links) links.add(link);
+		if (resolved.kind === "directory") visit(root, resolved.target, /* @__PURE__ */ new Set());
+	}
+	return {
+		directories,
+		files,
+		links,
+		truncated
+	};
+}
+//#endregion
+//#region src/scan-plan.ts
+/** 发现当前声明对应的扫描计划；目录、身份与回调都在这里刷新 */
+function createScanPlan(options) {
+	const { sources, projection } = discoverSubPackageDirectories(options.subPackagePatterns, options.root, options.outDir, options.exclude);
+	return {
+		root: options.root,
+		basePath: normalizePath(path.join(options.root, options.outDir)),
+		mainDirs: resolvePageDirs(options.dir, options.root, options.exclude).map((dir) => dir.replace(/\/$/, "")),
+		subPackageDirs: projection.subPackages,
+		subPackageSources: sources,
+		subPackageRootMap: new Map(projection.subPackageRootMap),
+		rules: getPageRules(options)
+	};
+}
+/**
+* 把计划同步回 ResolvedOptions。
+*
+* `dirs`、`subPackages` 与 `subPackageRootMap` 是给既有调用方和测试看的
+* 兼容投影；内部扫描与监听应读取 ScanPlan，而不是这些字段。
+*/
+function applyScanPlan(options, plan) {
+	options.dirs = [...plan.mainDirs];
+	options.subPackages = [...plan.subPackageDirs];
+	options.subPackageRootMap = new Map(plan.subPackageRootMap);
+}
+//#endregion
+//#region src/page-watch.ts
+function contains(directory, file) {
+	return file === directory || file.startsWith(`${directory.replace(/\/$/, "")}/`);
+}
+function isDirectory(file) {
+	try {
+		return fs.statSync(file, { throwIfNoEntry: false })?.isDirectory() ?? false;
+	} catch (error) {
+		if (!isMissingFsError(error) && !isUnavailableSourceError(error) && error.code !== "ELOOP") throw error;
+		return false;
+	}
+}
+/**
+* 一轮监听刷新内复用的 Vite ignored 判定
+*
+* 监听检查沿候选路径逐级询问 ignored，同一批页面共享的祖先目录会在
+* 大量候选之间重复出现。每个路径在一轮内只求值一次，stat 次数从
+* “候选数 × 深度”降到“路径数”。来源结构或权限变化由下一次 refresh
+* 的 clear() 重新计算。
+*/
+var SourceIgnoreIndex = class {
+	ignored;
+	verdicts = /* @__PURE__ */ new Map();
+	constructor(ignored) {
+		this.ignored = ignored;
+	}
+	/** 丢弃本轮结论；新的来源结构、忽略规则或权限要重新询问 */
+	clear() {
+		this.verdicts.clear();
+	}
+	/** 判定路径是否被忽略；祖先结论会被后代复用 */
+	matches(file, stats) {
+		const cached = this.verdicts.get(file);
+		if (cached !== void 0) return cached;
+		let entry = stats;
+		if (!entry) try {
+			entry = fs.statSync(file, { throwIfNoEntry: false });
+		} catch (error) {
+			if (isUnavailableSourceError(error)) {
+				this.verdicts.set(file, true);
+				return true;
+			}
+			if (!isMissingFsError(error) && error.code !== "ELOOP") throw error;
+		}
+		if (this.ignored(file, entry)) {
+			this.verdicts.set(file, true);
+			return true;
+		}
+		const parent = normalizePath(path.dirname(file));
+		const inherited = parent === file ? false : this.matches(parent);
+		this.verdicts.set(file, inherited);
+		return inherited;
+	}
+};
+/** 当前词法页面来源、物理内容订阅及非递归入口观察 */
+var PageSourceWatch = class {
+	options;
+	onFile;
+	onStructure;
+	onError;
+	onWarning;
+	rules;
+	roots = /* @__PURE__ */ new Set();
+	links = /* @__PURE__ */ new Set();
+	directories = /* @__PURE__ */ new Map();
+	files = /* @__PURE__ */ new Map();
+	contentKey = "";
+	contentRules;
+	recoveryWatchers = /* @__PURE__ */ new Map();
+	closing = /* @__PURE__ */ new Set();
+	sourceRefreshQueued = false;
+	started = false;
+	warnedSourceLimit = false;
+	usePolling = false;
+	interval = 100;
+	awaitWriteFinish;
+	atomic;
+	ignored;
+	/** 当前 ignored 规则的判定缓存，随刷新清空 */
+	sourceIgnored;
+	watcher;
+	constructor(options, onFile, onStructure, onError, onWarning = () => {}) {
+		this.options = options;
+		this.onFile = onFile;
+		this.onStructure = onStructure;
+		this.onError = onError;
+		this.onWarning = onWarning;
+		this.rules = getPageRules(options);
+	}
+	/** 内容监听是否已建立；启动失败时调用方可用其他事件源重试 */
+	get running() {
+		return this.started;
+	}
+	start(options = {}, ignored, plan) {
+		if (this.started) return;
+		const polling = process.env.CHOKIDAR_USEPOLLING?.toLowerCase();
+		this.usePolling = polling === void 0 ? !!options.usePolling : !!polling && polling !== "false" && polling !== "0";
+		const interval = process.env.CHOKIDAR_INTERVAL ? Number.parseInt(process.env.CHOKIDAR_INTERVAL, 10) : options.interval ?? 100;
+		this.interval = Number.isFinite(interval) && interval > 0 ? interval : 100;
+		this.awaitWriteFinish = options.awaitWriteFinish;
+		this.atomic = options.atomic;
+		this.ignored = ignored === void 0 || Array.isArray(ignored) && ignored.length === 0 ? void 0 : createPageWatchFilter(ignored, this.options.root, options.cwd ?? process.cwd());
+		this.sourceIgnored = this.ignored ? new SourceIgnoreIndex(this.ignored) : void 0;
+		this.started = true;
+		try {
+			this.refresh(plan ?? createScanPlan(this.options));
+		} catch (error) {
+			this.started = false;
+			throw error;
+		}
+	}
+	ignoresSource(source, stats) {
+		return this.sourceIgnored?.matches(source, stats) ?? false;
+	}
+	createContentWatcher() {
+		const watcher = chokidar.watch([], {
+			ignoreInitial: true,
+			followSymlinks: false,
+			usePolling: this.usePolling,
+			interval: this.interval,
+			...this.awaitWriteFinish !== void 0 && { awaitWriteFinish: this.awaitWriteFinish },
+			...this.atomic !== void 0 && { atomic: this.atomic },
+			ignored: (file, stats) => {
+				const absolute = normalizePath(path.resolve(file));
+				if (contains(normalizePath(path.resolve(this.options.root, this.options.outDir, "pages.json.lock")), absolute)) return true;
+				for (const [source, { target }] of this.files) if (contains(absolute, target) && !this.rules.isExcluded(source) && !this.ignoresSource(source)) return false;
+				for (const [source, { target }] of this.directories) {
+					if (contains(absolute, target)) return false;
+					if (contains(target, absolute)) {
+						const lexical = normalizePath(path.join(source, path.relative(target, absolute)));
+						if (!this.rules.isExcluded(lexical) && !this.ignoresSource(lexical, stats)) return false;
+					}
+				}
+				return true;
+			}
+		});
+		for (const event of [
+			"add",
+			"change",
+			"unlink"
+		]) watcher.on(event, (file) => {
+			if (!this.started || this.watcher !== watcher) return;
+			if (this.links.has(normalizePath(path.resolve(file)))) this.queueSourceRefresh();
+			else this.onFile(event, file);
+		});
+		watcher.on("raw", (event, file, raw) => {
+			if (!this.started || this.watcher !== watcher) return;
+			const details = raw ?? {};
+			if (details.curr?.isDirectory()) this.queueSourceRefresh();
+			else if (event === "rename" && details.watchedPath) {
+				if (!file) {
+					this.queueSourceRefresh();
+					return;
+				}
+				const entry = normalizePath(path.resolve(details.watchedPath, file));
+				try {
+					if (this.links.has(entry) || fs.lstatSync(entry, { throwIfNoEntry: false })?.isSymbolicLink()) this.queueSourceRefresh();
+				} catch (error) {
+					if (!isMissingFsError(error)) this.onError(error);
+				}
+			}
+		});
+		const onStructure = () => {
+			if (this.started && this.watcher === watcher) this.onStructure();
+		};
+		watcher.on("addDir", onStructure);
+		watcher.on("unlinkDir", onStructure);
+		watcher.on("ready", onStructure);
+		watcher.on("error", (error) => this.onError(error));
+		return watcher;
+	}
+	/** 来源声明或扫描结果变化后重新解析当前目标 */
+	refresh(plan) {
+		if (!this.started) return;
+		this.sourceIgnored?.clear();
+		const rules = plan.rules;
+		const currentDirectories = /* @__PURE__ */ new Set([
+			...this.roots,
+			...plan.mainDirs.map((dir) => normalizePath(path.resolve(this.options.root, dir))),
+			...plan.subPackageDirs.map((dir) => normalizePath(path.resolve(this.options.root, dir)))
+		]);
+		for (const pattern of rules.patterns) {
+			const portable = normalizePagePattern(pattern);
+			if (!picomatch.scan(portable).isGlob) currentDirectories.add(normalizePath(path.resolve(this.options.root, unescapePagePattern(portable))));
+		}
+		this.roots = new Set([...currentDirectories].filter((source) => this.options.mergePages && rules.matchesDirectory(source)));
+		const isExcluded = rules.createExcludeFilter();
+		const sources = collectPageWatchSources(this.roots, (source) => isExcluded(source) || this.ignoresSource(source));
+		this.rules = rules;
+		this.directories = sources.directories;
+		this.files = sources.files;
+		this.links = sources.links;
+		this.reconcile();
+		if (sources.truncated) {
+			if (!this.warnedSourceLimit) {
+				this.warnedSourceLimit = true;
+				this.onWarning(`Page watch discovery reached the ${PAGE_WATCH_SOURCE_LIMIT} linked-source safety limit and stopped expanding this round. Pages are still generated, but sources beyond the limit are not watched while it is reached. Narrow the page roots or exclude unused links to restore full watch coverage.`);
+			}
+		} else this.warnedSourceLimit = false;
+	}
+	fileForEvent(file, identity) {
+		const absolute = normalizePath(path.resolve(this.options.root, file));
+		if (isTargetFile(absolute) && isPageFileInDirectories(absolute, this.options) && !this.ignoresSource(absolute)) return absolute;
+		for (const [source, { target }] of this.files) if (target === identity && isPageFileInDirectories(source, this.options) && !this.ignoresSource(source) && resolveWatchTarget(source).target === target) return source;
+		for (const [source, { target }] of this.directories) {
+			if (!contains(target, identity) || resolveWatchTarget(source).target !== target) continue;
+			const lexical = normalizePath(path.join(source, path.relative(target, identity)));
+			if (isTargetFile(lexical) && isPageFileInDirectories(lexical, this.options) && !this.ignoresSource(lexical) && resolveWatchTarget(lexical).target === identity) return lexical;
+		}
+	}
+	directoryForEvent(directory) {
+		if (!this.options.mergePages) return false;
+		const absolute = normalizePath(path.resolve(this.options.root, directory));
+		if (!this.ignoresSource(absolute) && (getPageRules(this.options).matchesDirectory(absolute) || [...this.directories.keys()].some((source) => contains(absolute, source)))) return true;
+		return [...this.directories, ...this.files].some(([source, { target }]) => contains(absolute, target) && (isPageDirectoryEvent(source, this.options) || isPageFileInDirectories(source, this.options)) && !this.ignoresSource(source) && resolveWatchTarget(source).target === target);
+	}
+	async close() {
+		this.started = false;
+		for (const { close } of this.recoveryWatchers.values()) close();
+		this.recoveryWatchers.clear();
+		this.contentKey = "";
+		this.contentRules = void 0;
+		this.sourceIgnored = void 0;
+		this.warnedSourceLimit = false;
+		const watcher = this.watcher;
+		this.watcher = void 0;
+		await Promise.all([watcher?.close(), ...this.closing]);
+	}
+	reconcile() {
+		const directories = [...this.directories.values()].filter((source) => source.exists);
+		const covered = (target) => directories.some((directory) => directory.target !== target && contains(directory.target, target));
+		const wanted = /* @__PURE__ */ new Set();
+		for (const target of [...directories, ...this.files.values()].filter((source) => source.exists)) if (!covered(target.target)) wanted.add(target.target);
+		const key = this.sourceSignature();
+		if (key !== this.contentKey || this.contentRules !== this.rules) {
+			if (this.watcher) {
+				const closing = this.watcher.close();
+				this.closing.add(closing);
+				closing.then(() => this.closing.delete(closing), (error) => {
+					this.closing.delete(closing);
+					this.onError(error);
+				});
+				this.watcher = void 0;
+			}
+			if (wanted.size) {
+				this.watcher = this.createContentWatcher();
+				this.watcher.add([...wanted]);
+			}
+			this.contentKey = key;
+			this.contentRules = this.rules;
+		}
+		this.refreshEntrances();
+	}
+	refreshFromEntrance() {
+		try {
+			const previous = this.sourceSignature();
+			this.refresh(createScanPlan(this.options));
+			if (this.sourceSignature() !== previous) this.onStructure();
+		} catch (error) {
+			this.onError(error);
+		}
+	}
+	queueSourceRefresh() {
+		if (this.sourceRefreshQueued) return;
+		this.sourceRefreshQueued = true;
+		queueMicrotask(() => {
+			this.sourceRefreshQueued = false;
+			if (this.started) this.refreshFromEntrance();
+		});
+	}
+	sourceSignature() {
+		return JSON.stringify([...this.directories, ...this.files].map(([source, { target, exists, kind, identity }]) => [
+			source,
+			target,
+			exists,
+			kind,
+			kind === "directory" ? identity : null
+		]).sort(([a], [b]) => String(a).localeCompare(String(b))));
+	}
+	refreshEntrances() {
+		const wanted = /* @__PURE__ */ new Map();
+		const observe = (directory, entry) => {
+			const normalized = normalizePath(directory);
+			if (!entry) {
+				wanted.set(normalized, void 0);
+				return;
+			}
+			if (wanted.has(normalized) && !wanted.get(normalized)) return;
+			const entries = wanted.get(normalized) ?? /* @__PURE__ */ new Set();
+			entries.add(entry);
+			wanted.set(normalized, entries);
+		};
+		const entrance = (file) => {
+			let child = file;
+			let directory = path.dirname(child);
+			while (!isDirectory(directory)) {
+				child = directory;
+				const parent = path.dirname(directory);
+				if (parent === directory) return;
+				directory = parent;
+			}
+			observe(directory, path.basename(child));
+		};
+		for (const [source, resolved] of [...this.directories, ...this.files]) {
+			entrance(source);
+			entrance(resolved.target);
+			for (const link of resolved.links) entrance(link);
+		}
+		if (this.options.mergePages) {
+			const rules = getPageRules(this.options);
+			for (const pattern of rules.patterns) {
+				const portable = normalizePagePattern(pattern);
+				const normalized = path.posix.normalize(portable);
+				const scan = picomatch.scan(normalized, { parts: true });
+				if (!scan.isGlob) continue;
+				const base = normalizePath(path.resolve(this.options.root, unescapePagePattern(scan.base || ".")));
+				if (rules.isExcluded(base) || this.ignoresSource(base)) continue;
+				entrance(base);
+				if (isDirectory(base)) observe(base);
+				const parts = scan.parts ?? [];
+				for (let length = 1; length < parts.length; length++) {
+					const prefix = parts.slice(0, length).join("/") || "/";
+					if (!picomatch.scan(prefix).isGlob) continue;
+					const directories = globSync(prefix, {
+						cwd: this.options.root,
+						onlyDirectories: true,
+						expandDirectories: false,
+						dot: true,
+						ignore: rules.traversalIgnores
+					});
+					for (const directory of directories) {
+						const absolute = normalizePath(path.resolve(this.options.root, directory));
+						if (!rules.isExcluded(absolute) && !this.ignoresSource(absolute)) {
+							entrance(absolute);
+							observe(absolute);
+						}
+					}
+				}
+			}
+		}
+		for (const [directory, entry] of this.recoveryWatchers) if (!wanted.has(directory)) {
+			entry.close();
+			this.recoveryWatchers.delete(directory);
+		}
+		for (const [directory, entries] of wanted) try {
+			const stat = fs.statSync(directory, { bigint: true });
+			const identity = `${stat.dev}:${stat.ino}`;
+			const existing = this.recoveryWatchers.get(directory);
+			if (existing?.identity === identity) {
+				existing.entries = entries;
+				continue;
+			}
+			existing?.close();
+			let entry;
+			let watcher;
+			let stop;
+			if (this.usePolling) {
+				const onChange = () => {
+					if (this.recoveryWatchers.get(directory) === entry) this.queueSourceRefresh();
+				};
+				watcher = fs.watchFile(directory, {
+					persistent: false,
+					interval: this.interval
+				}, onChange);
+				stop = () => fs.unwatchFile(directory, onChange);
+			} else {
+				const nativeWatcher = fs.watch(directory, {
+					recursive: false,
+					persistent: false
+				}, (event, filename) => {
+					const observed = this.recoveryWatchers.get(directory);
+					if (observed !== entry || event !== "rename") return;
+					const name = filename?.toString();
+					if (!name || !observed.entries || observed.entries.has(name) || name === path.basename(directory)) this.refreshFromEntrance();
+				});
+				watcher = nativeWatcher;
+				stop = () => nativeWatcher.close();
+			}
+			const onError = (error) => {
+				if (this.recoveryWatchers.get(directory) !== entry) return;
+				entry.close();
+				this.recoveryWatchers.delete(directory);
+				if (!isMissingFsError(error)) this.onError(error);
+				if (this.started) this.refreshFromEntrance();
+			};
+			watcher.on("error", onError);
+			entry = {
+				watcher,
+				entries,
+				identity,
+				close: () => {
+					watcher.off("error", onError);
+					stop();
+				}
+			};
+			this.recoveryWatchers.set(directory, entry);
+		} catch (error) {
+			if (!isMissingFsError(error) && !isUnavailableSourceError(error)) this.onError(error);
+		}
+	}
+};
+//#endregion
 //#region src/platform-variants.ts
 /**
 * 把 `||` 分隔的平台列表拆开，去掉当前平台，剩下的排好序（规则 1）
@@ -830,7 +2369,7 @@ function platformsExcluding(platformList, currentPlatform) {
 	return platformList.split("||").map((p) => p.trim()).filter((p) => p && p !== currentPlatform).sort();
 }
 /**
-* 把本次运行的一个载荷并入变体列表（规则 2）：
+* 把本轮的一个载荷并入变体列表（规则 2）：
 * - 内容相同的手写 #ifndef 变体优先：当前平台没被排除时，那条
 *   #ifndef 已经覆盖了它；当前平台正好被排除时，尊重手写的隐藏规
 *   则。两种情况下再单独写一份都会产生重复路由或覆盖用户的条件
@@ -838,7 +2377,7 @@ function platformsExcluding(platformList, currentPlatform) {
 * - 没有内容相同的变体：新建只属于当前平台的变体
 *
 * @param variants - 同一个键下已有的变体列表，原地修改
-* @param payload - 本次运行的载荷
+* @param payload - 本轮的载荷
 * @param valueStr - 载荷的比较字符串
 * @param currentPlatform - 当前平台标识（大写）
 * @param compatible - 可选的额外相容判断。数组侧用它区分两个平台各自
@@ -866,7 +2405,7 @@ function upsertCurrentVariant(variants, payload, valueStr, currentPlatform, comp
 *
 * 当前平台的变体在收集时被排除、并入时又补到列表末尾，两个平台轮流
 * 运行（dev:h5 和 dev:mp-weixin 交替写）时，同一个键的变体顺序就会
-* 来回翻转——条件编译的结果没变，但文件每次都有无意义的变动。
+* 来回翻转。条件编译的结果没变，但文件每次都有无意义的变动。
 * platformStr 由排好序的平台列表拼成，手写 #ifndef 变体是空串、排最
 * 前。排序是稳定的：并列时（同键两组平台列表相同，只出现在手写文件
 * 里）保持收集顺序
@@ -875,6 +2414,61 @@ function sortVariants(variants) {
 	variants.sort((a, b) => a.platformStr < b.platformStr ? -1 : a.platformStr > b.platformStr ? 1 : 0);
 }
 /**
+* 决定变体列表的输出顺序（规则 6）
+*
+* 此前条目一律按磁盘上的旧顺序输出、配置里新增的条目追加到末尾：
+* 「哪个平台先构建」决定了文件长什么样，配置里的声明顺序会被丢掉
+* （比如某平台把一个新条目声明在 tabBar 第二位，生成的文件里却垫
+* 着底，该平台编译剥掉注释后实际顺序就是错的）。
+*
+* 排序分两种情况：
+* - 配置声明了全部既有键：这是全量超集，声明顺序是唯一已知的权威
+*   顺序，整个列表按配置顺序输出
+* - 配置没有覆盖全部键（其他平台有本平台不认识的条目，谁也不知道
+*   完整顺序）：既有键保持磁盘序，只把新增的键插到它前面最近
+*   的、已在输出里的声明键之后；没有这样的前驱就放到最前。既有键
+*   之间的相对顺序永不变动，所以两端构建不会来回翻转
+*
+* 两个平台的配置都覆盖全部键但顺序不同时，共享文件跟随最后写入者。
+* 条目内容相同而合并成一条时没有按平台区分的副本，另一个正在运行
+* 的平台在下一次生成前可能读到对方顺序；并发开发时建议各平台保持
+* 一致的完整 tab 顺序。
+*
+* @param mergedMap - 键 → 变体列表的合并结果。迭代顺序一般是磁盘序，
+* 但被跳过的当前平台旧条目会追加到末尾，需要靠 options.diskOrder 修正
+* @param declaredKeys - 配置声明的键，按配置顺序，可含新增键；
+* 传 null 表示不启用配置序摆放，保持磁盘序
+* @param options - 磁盘上已有键的顺序，见 {@link OrderVariantListsOptions}
+* @returns 按输出顺序排列的变体列表（mergedMap 中列表的原引用）
+*/
+function orderVariantLists(mergedMap, declaredKeys, options = {}) {
+	const diskOrder = [...mergedMap.keys()];
+	if (mergedMap.size === 0 || declaredKeys === null) return diskOrder.map((key) => mergedMap.get(key));
+	const declared = [...new Set(declaredKeys)].filter((key) => mergedMap.has(key));
+	const declaredSet = new Set(declared);
+	if (diskOrder.every((key) => declaredSet.has(key))) return declared.map((key) => mergedMap.get(key));
+	const ordered = (options.diskOrder ?? diskOrder).filter((key) => mergedMap.has(key));
+	const placed = new Set(ordered);
+	for (const [index, key] of declared.entries()) {
+		if (placed.has(key)) continue;
+		let anchor = -1;
+		for (let i = index - 1; i >= 0; i--) {
+			const candidate = ordered.indexOf(declared[i]);
+			if (candidate !== -1) {
+				anchor = candidate;
+				break;
+			}
+		}
+		ordered.splice(anchor + 1, 0, key);
+		placed.add(key);
+	}
+	for (const key of diskOrder) if (!placed.has(key)) {
+		ordered.push(key);
+		placed.add(key);
+	}
+	return ordered.map((key) => mergedMap.get(key));
+}
+/**
 * 收集所有变体记录过的平台（手写 #ifndef 不算，它没有正向列表），
 * 这个集合同时也是「拥有至少一个变体」的平台集合
 */
@@ -890,7 +2484,7 @@ function collectVariantPlatforms(mergedMap) {
 * 没被包裹的条目在 uni-app 条件编译下所有平台都看得见，所以只有
 * 覆盖了全部平台的变体才能"裸着"输出（规则 5）。
 *
-* 当前平台一定在全集里，哪怕这次运行一个变体都没贡献——比如页面
+* 当前平台一定在全集里，哪怕这次运行一个变体都没贡献。比如页面
 * 只在 H5 存在，而 MP-WEIXIN 运行把每个页面都 definePage(null) 掉了。
 * 如果只从剩下的条目推全集，全集就只有 'H5'，H5 专属条目看起来
 * "覆盖了全集"，会不加包裹地输出，泄漏进微信的构建产物。老版本按
@@ -906,7 +2500,7 @@ function collectVariantPlatforms(mergedMap) {
 * 裹，不会泄漏。
 *
 * 只增不减的代价：彻底不用的平台会一直留在标记里。这无害，但别
-* 手工去改标记行——想清理就删掉整个生成的 pages.json，下次运行会
+* 手工去改标记行。想清理就删掉整个生成的 pages.json，下次运行会
 * 从头生成。
 */
 function resolvePlatformUnion(mergedMap, currentPlatform, lastPlatforms) {
@@ -940,6 +2534,252 @@ function extractLastPlatforms(src, currentPlatform) {
 	return lastPlatforms;
 }
 //#endregion
+//#region src/pages-json-tokens.ts
+/** 构建用于序列化 pages.json 输出或数组元素包裹的行注释令牌 */
+function lineComment(value) {
+	return {
+		type: "LineComment",
+		value,
+		inline: false,
+		loc: {
+			start: {
+				line: 0,
+				column: 0
+			},
+			end: {
+				line: 0,
+				column: 0
+			}
+		}
+	};
+}
+/**
+* 找到条目前面的条件编译开启指令。
+*
+* comment-json 会把包裹层的 #endif（输出在值的逗号后面）挂到下一个条目
+* 前面，所以只认 #ifdef/#ifndef 开头，绝不能把 #endif 当成开启符。
+*/
+function findConditionalComment(beforeComments) {
+	return beforeComments?.find((comment) => comment.type !== "BlankLine" && /^#(?:ifdef|ifndef)/.test(comment.value.trim()));
+}
+/**
+* 手写 #ifndef 块原样保留时清理包裹注释。
+*
+* 只保留开启这个块的那条指令和用户写的说明文字；前一个块收尾的 #endif
+* 和重复的结构指令都要丢掉，否则每次重跑都会多出游离的 #endif 或嵌套。
+*/
+function sanitizePassthroughComments(beforeComments, opening) {
+	const sanitized = [];
+	let openingKept = false;
+	for (const comment of beforeComments || []) {
+		if (isGenerationMarker(comment)) continue;
+		if (comment.type === "BlankLine") {
+			sanitized.push(comment);
+			continue;
+		}
+		if (/^#(?:ifdef|ifndef|endif)/.test(comment.value.trim())) {
+			if (!openingKept && comment === opening) {
+				sanitized.push(comment);
+				openingKept = true;
+			}
+			continue;
+		}
+		sanitized.push(comment);
+	}
+	return sanitized;
+}
+//#endregion
+//#region src/pages-json-items.ts
+/**
+* 把条目转成字符串用于比较，比较前先拿掉内部的 `type` 标记。
+*
+* 从 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` 标记不参与内容比较，没有标记的条目也能和扫描到的条目合并。
+* 但如果两边都明确带着标记、而且一个是 'home' 一个是 'page'，说明这是
+* 两个平台各自声明的不同首页，必须留在各自的 #ifdef 块里。
+*/
+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 的共享核心。
+*
+* @param source - 现有条目数组（来自 pages.json）
+* @param currentPlatform - 当前平台标识（如 H5、MP-WEIXIN）
+* @param items - 新配置条目数组
+* @param uniqueKeyName - 用于识别条目唯一性的字段名（如 'path' 或 'pagePath'）
+* @param options - 输出顺序选项，见 {@link MergePlatformItemsOptions}
+* @returns 带 #ifdef 块的合并条目，以及平台全集与拥有平台
+*/
+function mergePlatformItems(source, currentPlatform, items, uniqueKeyName, options = {}) {
+	const { orderByConfig = false } = options;
+	const src = source || new CommentArray();
+	currentPlatform = currentPlatform.toUpperCase();
+	const lastPlatforms = extractLastPlatforms(src, currentPlatform);
+	const mergedMap = /* @__PURE__ */ new Map();
+	const sourceOrder = orderByConfig ? {
+		seen: /* @__PURE__ */ new Set(),
+		order: []
+	} : void 0;
+	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;
+		if (sourceOrder && !sourceOrder.seen.has(uniqueKey)) {
+			sourceOrder.seen.add(uniqueKey);
+			sourceOrder.order.push(uniqueKey);
+		}
+		const beforeComments = src[Symbol.for(`before:${i}`)];
+		const conditionalComment = findConditionalComment(beforeComments);
+		if (conditionalComment?.value.trim().startsWith("#ifndef")) {
+			variantsOf(uniqueKey).push({
+				payload: item,
+				valueStr: stringifyForCompare(item),
+				platforms: null,
+				platformStr: "",
+				passthrough: {
+					before: sanitizePassthroughComments(beforeComments, conditionalComment),
+					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(" || ")
+		});
+	}
+	const orderOptions = sourceOrder ? { diskOrder: sourceOrder.order } : void 0;
+	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}`)];
+	const declaredKeys = orderByConfig ? items.map((item) => item[uniqueKeyName]).filter((key) => typeof key === "string" && key.length > 0) : null;
+	for (const list of orderVariantLists(mergedMap, declaredKeys, orderOptions)) 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/pages-json-structure.ts
+/**
+* 把所有首页条目移到最前面，注释跟着条目一起移动。
+*
+* 每个平台可以在自己的 #ifdef 块里声明自己的首页，没被包裹的条目
+* 所有平台都能看到。所以一个平台的首页必须排在它可见的所有条目
+* 之前：把所有首页放到所有非首页条目前面，组内顺序不变，一次满足
+* 所有平台。
+*/
+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];
+	}
+}
+/**
+* 删除本轮扫描不到、但确实由插件生成的分包。
+*
+* 不删的话，这个 root 会以空分包进入本平台构建产物（app.json 里留
+* 一个指向不存在目录的 pages 数组）。手写分包没有生成标记，原样保留。
+*
+* 倒序遍历；删除条目注释符号再 splice，让 comment-json 把 `#ifdef`
+* 块和用户注释一起带走。`after-value:i`（条目的 `}` 和 `,` 之间的
+* 用户注释）也必须删掉：splice 只挪注释、不删注释。
+*/
+function removeStaleSubPackages(subPackagesArray, staleRoots) {
+	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);
+	}
+}
+//#endregion
 //#region src/jsonc-scan.ts
 /**
 * 跳过空白和注释往前走。遇到行注释或块注释时，注释里的文字（去掉
@@ -1040,7 +2880,7 @@ function readJsonStringToken(content, start) {
 * tabBar 不是对象、或文件结构看不懂时返回 undefined。
 */
 function extractTabBarProps(content) {
-	let i = skipJsoncFiller(content, 0);
+	let i = skipJsoncFiller(content, content.charCodeAt(0) === 65279 ? 1 : 0);
 	if (content[i] !== "{") return void 0;
 	i = skipJsoncFiller(content, i + 1);
 	while (i < content.length) {
@@ -1139,11 +2979,12 @@ function mergeTabBarProps(existingContent, currentProps, contributesProps, curre
 	};
 	for (const [key, variants] of rawProps || []) {
 		if (key === "list") continue;
+		const keyVariants = variantsOf(key);
 		for (const raw of variants) {
 			const valueStr = JSON.stringify(raw.value);
 			if (valueStr === void 0) continue;
 			if (raw.condition?.startsWith("#ifndef")) {
-				variantsOf(key).push({
+				keyVariants.push({
 					payload: raw.value,
 					valueStr,
 					platforms: null,
@@ -1159,7 +3000,7 @@ function mergeTabBarProps(existingContent, currentProps, contributesProps, curre
 			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({
+			keyVariants.push({
 				payload: raw.value,
 				valueStr,
 				platforms,
@@ -1173,6 +3014,7 @@ function mergeTabBarProps(existingContent, currentProps, contributesProps, curre
 		if (valueStr === void 0) continue;
 		upsertCurrentVariant(variantsOf(key), value, valueStr, currentPlatform);
 	}
+	for (const [key, variants] of merged) if (variants.length === 0) merged.delete(key);
 	for (const variants of merged.values()) sortVariants(variants);
 	return merged;
 }
@@ -1194,13 +3036,19 @@ function renderTabBarPropLines(merged, platformUnion, format) {
 	const unit = indentUnitOf(format);
 	const unionStr = platformUnion.join(" || ");
 	const lines = [];
+	const pushComments = (comments) => {
+		for (const comment of comments) for (const line of comment.split(/\r?\n/)) {
+			const text = line.trim();
+			if (text) lines.push(`${unit}${unit}// ${text}`);
+		}
+	};
 	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}`);
+			pushComments(variant.passthrough.before);
 			lines.push(propLine);
-			for (const comment of variant.passthrough.after) if (comment) lines.push(`${unit}${unit}// ${comment}`);
+			pushComments(variant.passthrough.after);
 			continue;
 		}
 		if (variant.platformStr === unionStr) lines.push(propLine);
@@ -1253,7 +3101,7 @@ async function writePagesJson(jsonPath, data, options) {
 				content
 			};
 		}
-		await writeFileAtomic(jsonPath, content);
+		await retryOnEperm(() => writeFileAtomic(jsonPath, content));
 		return {
 			updated: true,
 			content
@@ -1261,6 +3109,23 @@ async function writePagesJson(jsonPath, data, options) {
 	});
 }
 /**
+* Retries an async operation up to 3 times on EPERM, waiting 50ms between
+* attempts. Other errors propagate immediately.
+*
+* Windows file rename (used by write-file-atomic) can fail with EPERM when
+* another process holds the destination open with a sharing mode that excludes
+* rename (e.g. chokidar's watcher). The lock clears in under a frame.
+*/
+async function retryOnEperm(operation) {
+	for (let attempt = 3; attempt > 0; attempt--) try {
+		await operation();
+		return;
+	} catch (error) {
+		if (error.code !== "EPERM" || attempt === 1) throw error;
+		await new Promise((resolve) => setTimeout(resolve, 50));
+	}
+}
+/**
 * 根据现有文件内容计算合并后的 pages.json 对象
 *
 * @returns pages.json 对象；美化输出模式下附带预渲染的 tabBar 主体
@@ -1274,6 +3139,7 @@ function mergeIntoPagesJson(existingContent, data, options) {
 	} 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 });
 	}
+	if (Object.prototype.toString.call(oldConfig) !== "[object Object]") throw new Error("[vite-plugin-uni-pages] The existing pages.json must contain a JSON object, please fix its syntax first");
 	const { pages: oldPages, subPackages: oldSubPackages, tabBar: oldTabBar } = oldConfig;
 	for (const [field, value] of Object.entries({
 		pages: oldPages,
@@ -1298,15 +3164,7 @@ function mergeIntoPagesJson(existingContent, data, options) {
 			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);
-	}
+	removeStaleSubPackages(subPackagesArray, staleRoots);
 	for (const [_, newSub] of newSubPackages) {
 		const subPackage = {
 			root: newSub.root,
@@ -1318,7 +3176,7 @@ function mergeIntoPagesJson(existingContent, data, options) {
 	const { list, ...tabBarOthers } = data.tabBar || {};
 	const contributesProps = !!(list && list.length);
 	const oldTabBarObj = oldTabBar;
-	const tabBarMerge = mergePlatformItems(oldTabBarObj?.list, currentPlatform, list || [], "pagePath");
+	const tabBarMerge = mergePlatformItems(oldTabBarObj?.list, currentPlatform, list || [], "pagePath", { orderByConfig: true });
 	let tabBarBodyLines;
 	if (tabBarMerge.items.length === 0) pageJson.tabBar = void 0;
 	else {
@@ -1345,53 +3203,6 @@ function mergeIntoPagesJson(existingContent, data, options) {
 	};
 }
 /**
-* 把所有首页条目移到最前面，注释跟着条目一起移动
-*
-* 每个平台可以在自己的 #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 输出成
 * 单行，这里和它的行为保持一致。
@@ -1401,7 +3212,7 @@ function isPrettyFormat(format) {
 }
 /**
 * 不碰文件系统，只做计算：把路由数据合并进现有 pages.json 文本
-* （多平台 `#ifdef` 块、首页重排、生成标记、过期子包清理）并序列化
+* （多平台 `#ifdef` 块、首页重排、生成标记、过期分包清理）并序列化
 * 成字符串。文件锁、变更检测和原子写入都在 {@link writePagesJson}
 * 里；测试直接用字符串检查这个函数。
 *
@@ -1424,150 +3235,36 @@ function mergePagesJson(existingContent, data, options) {
 	if (options.format?.insertFinalNewline) content += eol;
 	return content;
 }
-/** 构建用于序列化 pages.json 输出的行注释令牌 */
-function lineComment(value) {
+//#endregion
+//#region src/pages-snapshot.ts
+function createPagesSnapshot(input) {
 	return {
-		type: "LineComment",
-		value,
-		inline: false,
-		loc: {
-			start: {
-				line: 0,
-				column: 0
-			},
-			end: {
-				line: 0,
-				column: 0
-			}
-		}
+		pages: [...input.pages],
+		subPackages: [...input.subPackages],
+		tabBar: input.tabBar ? {
+			...input.tabBar,
+			list: input.tabBar.list ? [...input.tabBar.list] : void 0
+		} : void 0,
+		globConfig: input.globConfig,
+		homePath: input.homePath
 	};
 }
+//#endregion
+//#region src/context.ts
 /**
-* 把条目转成字符串用于比较，比较前要先把内部的 `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` 块原样保留：否定条件翻译不成正向平台列表，
-*   所以条目连同原始包裹一起输出，永不修改、也永不清理
+* 在 watcher 回调里查页面规则
 *
-* @param source - 现有条目数组（来自 pages.json）
-* @param currentPlatform - 当前平台标识（如 H5、MP-WEIXIN）
-* @param items - 新配置条目数组
-* @param uniqueKeyName - 用于识别条目唯一性的字段名（如 'path' 或 'pagePath'）
-* @returns 带 #ifdef 块的合并条目，以及平台全集与拥有平台
+* 规则会在声明变化后重新编译，编译失败属于配置错误；此时记日志并按
+* “不是页面事件”处理，异常不能穿过 watcher 回调，否则会崩在事件循环里。
 */
-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")];
-		}
+function queryPageRules(fallback, query) {
+	try {
+		return query();
+	} catch (error) {
+		debug.error("Failed to evaluate page rules, the event is ignored:", error);
+		return fallback;
 	}
-	return {
-		items: result,
-		platformUnion,
-		owningPlatforms: [...owningPlatforms].sort()
-	};
 }
-//#endregion
-//#region src/context.ts
 /**
 * 页面上下文：负责扫描页面、加载配置、合并页面信息、生成 pages.json
 *
@@ -1578,17 +3275,45 @@ function mergePlatformItems(source, currentPlatform, items, uniqueKeyName) {
 */
 var PageContext = class {
 	_server;
+	configLoader;
+	watchers = /* @__PURE__ */ new Map();
+	watchedConfigPaths = /* @__PURE__ */ new Map();
+	/** 当前配置依赖与恢复范围；事件判定和路径展开都从这里取 */
+	configWatch;
+	/** 生成物（pages.json、d.ts）的绝对路径，只在首次事件时算一次 */
+	generatedPathsCache;
+	pendingUpdate = Promise.resolve();
+	disposed = false;
+	disposal;
+	/** 本轮扫描的目录、分包来源与规则；扫描和监听共用 */
+	scanPlan;
+	/** 最近一次生成的完整快照；虚拟模块、路由与声明都读它 */
+	generatedSnapshot;
+	/** 随扫描更新的 Page 来源，用于复用检查和冲突诊断 */
+	pageSources = /* @__PURE__ */ new WeakMap();
+	/** 扫描候选独立于归属裁剪后的输出映射，保留非代表来源的内容缓存 */
+	mainPageCandidates = /* @__PURE__ */ new Map();
+	subPageCandidates = /* @__PURE__ */ new Map();
+	pageWatcher;
+	/** 待处理的页面更新：生成期间到达的事件合并到下一轮 */
+	pendingPageUpdate;
+	/** 当前事件更新循环；dispose 时等待它排空 */
+	pendingPageFlush;
+	/** 页面监听启动参数；初始化失败时保留，后续生成会重试 */
+	pageWatcherStart;
+	/** 当前配置本地依赖及加载失败后仍需监听的恢复路径 */
+	pagesConfigDependencyPaths = [];
 	/** 从用户配置文件（pages.config.ts）解析出的配置对象 */
 	pagesGlobConfig;
 	/** 用户配置文件的来源路径列表 */
 	pagesConfigSourcePaths = [];
-	/** 主包页面映射，键为页面文件的绝对路径 */
+	/** 主包页面映射，键为页面文件的词法绝对路径 */
 	pages = /* @__PURE__ */ new Map();
-	/** 子包页面映射，键为子包根目录，值为该子包下的页面映射 */
+	/** 分包页面映射，外层键为词法扫描目录，内层键为页面文件的词法绝对路径 */
 	subPages = /* @__PURE__ */ new Map();
 	/** 主包页面配置数组，用于生成 pages.json 的 pages 字段 */
 	pageMetaData = [];
-	/** 子包页面配置数组，用于生成 pages.json 的 subPackages 字段 */
+	/** 分包页面配置数组，用于生成 pages.json 的 subPackages 字段 */
 	subPageMetaData = [];
 	/**
 	* 最近一次合并出的 tabBar（配置文件与 definePage 声明的合体）。
@@ -1609,7 +3334,7 @@ var PageContext = class {
 	withUniPlatform = false;
 	/** pages.json 中页面路径的解析基准路径 */
 	get basePath() {
-		return resolveBasePath(this.options);
+		return this.scanPlan?.basePath ?? resolveBasePath(this.options);
 	}
 	/**
 	* 创建 PageContext 实例
@@ -1619,9 +3344,18 @@ var PageContext = class {
 	*/
 	constructor(userOptions, viteRoot = process.cwd(), platform$1 = platform) {
 		this.root = normalizePath(viteRoot);
+		this.configLoader = new PagesConfigLoader(this.root);
+		this.configWatch = new ConfigWatchIndex(this.root, this.configLoader.artifactDirectory);
 		this.platform = platform$1;
 		debug.options("root", this.root);
 		this.options = resolveOptions(userOptions, this.root);
+		this.pageWatcher = new PageSourceWatch(this.options, (event, file) => {
+			const pageFile = queryPageRules(void 0, () => this.pageFileForEvent(file, normalizeConfigPath(file, this.root)));
+			if (pageFile) {
+				debug.pages(`File changed: ${pageFile}`);
+				this.queuePageUpdate(event === "change" ? pageFile : void 0);
+			}
+		}, () => this.queuePageUpdate(), (error) => this.logUpdateFailure(error), (message) => this.logger?.warn(message, { timestamp: true }));
 		const debugOption = this.options.debug;
 		if (debugOption) {
 			const prefix = "vite-plugin-uni-pages:";
@@ -1643,73 +3377,256 @@ var PageContext = class {
 	* 使用 unconfig 加载配置，支持多种配置文件格式
 	*/
 	async loadUserPagesConfig() {
-		const configSource = this.options.configSource;
-		const { config, sources } = await loadConfig({
-			cwd: this.root,
-			sources: configSource,
-			defaults: {}
-		});
-		this.pagesGlobConfig = config.default || config;
-		this.pagesConfigSourcePaths = sources.map(normalizePath);
-		debug.options(this.pagesGlobConfig);
+		try {
+			const { config, sources, dependencies } = await this.configLoader.load(this.options.configSource);
+			this.pagesGlobConfig = config.default || config;
+			this.pagesConfigSourcePaths = sources;
+			this.pagesConfigDependencyPaths = dependencies;
+			debug.options(this.pagesGlobConfig);
+		} catch (error) {
+			this.pagesConfigDependencyPaths = [...this.configLoader.watchInput.dependencies];
+			throw error;
+		} finally {
+			this.refreshConfigWatchers();
+		}
 	}
 	/**
-	* 按顺序跑完扫描与合并：先扫描主包和子包的页面，再合并它们的
+	* 按顺序跑完扫描与合并：先扫描主包和分包的页面，再合并它们的
 	* 信息。步骤顺序只维护在这里，调用方和测试都不用关心。
 	*/
 	async scanAndMerge() {
+		this.generatedSnapshot = void 0;
+		this.refreshScanPlan();
 		await this.scanPages();
 		await this.scanSubPages();
+		this.startPageWatcher();
+		this.pageWatcher.refresh(this.requireScanPlan());
 		await this.mergePageMetaData();
 		await this.mergeSubPageMetaData();
 	}
+	/** 刷新本轮扫描计划，并同步兼容投影供既有调用方读取 */
+	refreshScanPlan() {
+		this.scanPlan = createScanPlan(this.options);
+		applyScanPlan(this.options, this.scanPlan);
+	}
+	/** 扫描与监听阶段读取本轮计划；计划在 refreshScanPlan 之后必定存在 */
+	requireScanPlan() {
+		if (!this.scanPlan) throw new Error("[vite-plugin-uni-pages] Scan plan is not ready");
+		return this.scanPlan;
+	}
 	/**
 	* 设置 Vite 开发服务器，用于 HMR 与文件监听
 	* @param server - Vite 开发服务器实例
 	*/
 	setupViteServer(server) {
-		if (this._server === server) return;
+		if (this.disposed || this._server === server) return;
 		this._server = server;
-		this.setupWatcher(server.watcher);
+		this.setupWatcher(server.watcher).catch((error) => this.logUpdateFailure(error));
+	}
+	/**
+	* 生成物（pages.json 与 d.ts）的绝对路径
+	*
+	* 只依赖构造后不再变化的 `options` 与 `resolvedPagesJSONPath`，
+	* 算一次缓存即可，不必每个事件重新解析
+	*/
+	generatedFilePaths() {
+		if (!this.generatedPathsCache) this.generatedPathsCache = [normalizeConfigPath(this.resolvedPagesJSONPath, this.root), ...this.options.dts ? [normalizeConfigPath(this.options.dts, this.root)] : []];
+		return this.generatedPathsCache;
+	}
+	/** 按当前词法规则识别页面事件，真实路径只用于关联已收录来源 */
+	pageFileForEvent(file, identity) {
+		return this.pageWatcher.fileForEvent(file, identity);
+	}
+	pageDirectoryForEvent(directory) {
+		return this.pageWatcher.directoryForEvent(directory);
 	}
 	/**
-	* 设置文件监听器，监听页面文件与配置文件变更
-	* 页面文件或配置文件变化时自动更新 pages.json
-	* @param watcher - chokidar 文件监听器实例
+	* 注册配置文件与页面目录结构监听，并启动页面内容监听
+	*
+	* @param watcher - 配置文件及目录结构事件使用的 chokidar 监听器
 	*/
 	async setupWatcher(watcher) {
-		watcher.add(this.pagesConfigSourcePaths);
-		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}/`));
+		if (this.disposed || this.watchers.has(watcher)) return;
+		const onConfigFile = (filepath) => {
+			const absolute = this.configWatch.match(filepath, this.generatedFilePaths());
+			if (!absolute) return;
+			debug.pages(`Config changed: ${absolute}`);
+			this.updatePagesAndNotify();
+		};
+		const onDirectory = (directory) => {
+			if (queryPageRules(false, () => this.pageDirectoryForEvent(directory))) this.queuePageUpdate();
+		};
+		const onSharedPageFile = (filepath) => {
+			if (this.disposed || this.pageWatcher.running || !this.pageWatcherStart) return;
+			if (!isTargetFile(normalizePath(filepath))) return;
+			this.startPageWatcher();
+			if (this.pageWatcher.running) this.queuePageUpdate();
 		};
-		watcher.on("add", async (path) => {
-			path = normalizePath(path);
-			if (!isWatchedPageFile(path)) return;
-			debug.pages(`File added: ${path}`);
-			if (await this.updatePagesJSON()) this.onUpdate();
+		const onReady = () => this.queuePageUpdate();
+		watcher.on("add", onConfigFile);
+		watcher.on("change", onConfigFile);
+		watcher.on("unlink", onConfigFile);
+		watcher.on("add", onSharedPageFile);
+		watcher.on("change", onSharedPageFile);
+		watcher.on("unlink", onSharedPageFile);
+		watcher.on("addDir", onDirectory);
+		watcher.on("unlinkDir", onDirectory);
+		watcher.on("ready", onReady);
+		this.watchers.set(watcher, () => {
+			watcher.off("add", onConfigFile);
+			watcher.off("change", onConfigFile);
+			watcher.off("unlink", onConfigFile);
+			watcher.off("add", onSharedPageFile);
+			watcher.off("change", onSharedPageFile);
+			watcher.off("unlink", onSharedPageFile);
+			watcher.off("addDir", onDirectory);
+			watcher.off("unlinkDir", onDirectory);
+			watcher.off("ready", onReady);
 		});
-		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;
+		this.watchedConfigPaths.set(watcher, /* @__PURE__ */ new Set());
+		this.refreshConfigWatchers();
+		if (!(this._server?.watcher === watcher && this._server?.config.server.watch === null)) {
+			this.pageWatcherStart = {
+				options: watcher.options,
+				ignored: this._server?.watcher === watcher ? this._server?.watcher.options.ignored : void 0
+			};
+			this.startPageWatcher();
+		}
+	}
+	/**
+	* 启动页面监听
+	*
+	* @description 初始化失败只记录并保留启动参数，后续生成会重新尝试；监听属于辅助
+	* 能力，不能阻断页面生成，也不能留下未处理的拒绝
+	*/
+	startPageWatcher() {
+		if (this.disposed || !this.pageWatcherStart) return;
+		try {
+			this.pageWatcher.start(this.pageWatcherStart.options, this.pageWatcherStart.ignored, this.scanPlan);
+		} catch (error) {
+			this.logUpdateFailure(error);
+		}
+	}
+	/**
+	* 释放本上下文的监听与待处理更新
+	*
+	* @description 关闭后不再接受监听注册或更新；已开始的生成会完成，重复调用等待同一次释放
+	* 共享 watcher 的关闭仍由 Vite 负责
+	*/
+	async disposeWatchers() {
+		if (this.disposal) return this.disposal;
+		this.disposed = true;
+		this.pendingPageUpdate = void 0;
+		for (const dispose of this.watchers.values()) dispose();
+		this.watchers.clear();
+		this.watchedConfigPaths.clear();
+		this._server = void 0;
+		this.pageWatcherStart = void 0;
+		this.disposal = (async () => {
+			try {
+				await this.pageWatcher.close();
+			} finally {
+				await this.pendingPageFlush;
+				await this.pendingUpdate;
 			}
-			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 = normalizePath(path);
-			if (!isWatchedPageFile(path)) return;
-			debug.pages(`File removed: ${path}`);
-			if (await this.updatePagesJSON()) this.onUpdate();
+		})();
+		return this.disposal;
+	}
+	/** 补充未覆盖的监听路径，注册成功后记账，失败时保留重试机会 */
+	addWatchPaths(watcher, paths, added, description) {
+		const wanted = paths.filter((file) => !added.has(file) && ![...added].some((existing) => file.startsWith(`${existing}/`)));
+		if (!wanted.length) return;
+		try {
+			watcher.add(wanted);
+			for (const file of wanted) added.add(file);
+		} catch (error) {
+			this.logger?.error(`Failed to watch ${description}: ${error instanceof Error ? error.message : error}`, {
+				timestamp: true,
+				error: error instanceof Error ? error : void 0
+			});
+		}
+	}
+	/**
+	* 让监听路径与当前配置依赖保持一致
+	*
+	* 只新增路径，从不 unwatch：chokidar 对文件调用 unwatch 会连带
+	* 拆掉父目录监听，新建文件就再也发现不了。因此监听集合是并集，
+	* 会随着会话累积；每次刷新都按当前依赖重建配置监听计划，
+	* 真正决定是否触发的始终是计划里的依赖集合（恢复目录除外，那是
+	* 故意留的兜底）。
+	*/
+	refreshConfigWatchers() {
+		this.configWatch.update(buildConfigWatchPlan({
+			root: this.root,
+			artifactDirectory: this.configLoader.artifactDirectory,
+			sourcePaths: this.pagesConfigSourcePaths,
+			dependencyPaths: this.pagesConfigDependencyPaths,
+			recoveryCandidates: this.configLoader.watchInput.recoveryCandidates,
+			recoveryDirectories: this.configLoader.watchInput.recoveryDirectories
+		}));
+		for (const watcher of this.watchers.keys()) {
+			const added = this.watchedConfigPaths.get(watcher);
+			const sharedRoot = this._server && watcher === this._server.watcher ? normalizeConfigPath(this._server.config.root, this.root) : void 0;
+			this.addWatchPaths(watcher, this.configWatch.watchPaths(sharedRoot), added, "pages config dependencies");
+		}
+	}
+	/** 配置变化的完整更新：失败只记录，不让 Promise 拒绝 */
+	async updatePagesAndNotify() {
+		try {
+			if (await this.updatePagesJSON() && !this.disposed) this.onUpdate();
+		} catch (error) {
+			this.logUpdateFailure(error);
+		}
+	}
+	/** 记录 watcher 更新失败，避免未处理的拒绝终止进程 */
+	logUpdateFailure(error) {
+		this.logger?.error(`Failed to update pages.json after a file change: ${error instanceof Error ? error.message : error}`, {
+			timestamp: true,
+			error: error instanceof Error ? error : void 0
 		});
 	}
 	/**
+	* 登记页面事件触发的更新：生成期间到达的事件合并到下一轮
+	*
+	* @description 连续删除、重建会一次性派发大量事件，逐个生成会反复
+	* 重读全部页面；内容变更合并待刷新文件，结构变更执行完整刷新
+	* @param filepath - 只读取该页面；省略时执行完整扫描
+	*/
+	queuePageUpdate(filepath) {
+		if (this.disposed) return;
+		if (!this.pendingPageUpdate) this.pendingPageUpdate = {
+			full: false,
+			files: /* @__PURE__ */ new Set()
+		};
+		if (filepath) this.pendingPageUpdate.files.add(filepath);
+		else this.pendingPageUpdate.full = true;
+		if (!this.pendingPageFlush) this.pendingPageFlush = this.flushPageUpdates();
+	}
+	/**
+	* 排空页面事件队列；失败只记录，不让 Promise 拒绝
+	*
+	* 页面事件的回调走这里而不是直接调 {@link updatePagesJSON}：一旦
+	* 它拒绝（拿不到文件锁、声明文件写不进去），就成了未处理的拒绝，
+	* Node 默认直接终止进程。开发时正在编辑文件，一次偶发的锁冲突
+	* 不该把 dev server 打死。用户改一次文件就会再触发一次事件，
+	* 所以这里报错即可。
+	*/
+	async flushPageUpdates() {
+		try {
+			while (this.pendingPageUpdate) {
+				const { full, files } = this.pendingPageUpdate;
+				this.pendingPageUpdate = void 0;
+				try {
+					if ((full ? await this.updatePagesJSON() : files.size === 1 ? await this.updatePagesJSON([...files][0]) : await this.enqueuePagesUpdate([...files])) && !this.disposed) this.onUpdate();
+				} catch (error) {
+					this.logUpdateFailure(error);
+				}
+			}
+		} finally {
+			this.pendingPageFlush = void 0;
+		}
+	}
+	/**
 	* 页面更新回调，页面文件或配置变化时触发
 	* 负责使虚拟模块失效并通知浏览器整页刷新
 	*/
@@ -1720,36 +3637,47 @@ var PageContext = class {
 		this._server.ws.send({ type: "full-reload" });
 	}
 	/**
-	* 更新 pages.json 文件
-	* 这是负责协调整个页面配置生成流程的核心方法：
-	* 1. 检查文件变更（指定 filepath 时）
-	* 2. 加载用户配置
-	* 3. 扫描页面文件
-	* 4. 合并页面配置
-	* 5. 生成并写入 pages.json
-	* @param filepath - 发生变更的文件路径，用于增量更新判断
-	* @returns pages.json 是否成功更新
+	* 刷新页面配置并更新 pages.json
+	*
+	* @description 同一实例的调用按顺序执行；指定页面时尝试增量读取，页面尚未收录或物理身份变化时执行完整刷新
+	*
+	* @param filepath 变更页面的绝对路径或相对 root 的路径；省略时执行完整刷新
+	* @returns pages.json 写入新内容时为 `true`，内容未变、上下文已关闭或跳过生成时为 `false`
+	* @throws 生成、写入或声明输出失败时拒绝；声明输出失败前 pages.json 可能已更新
 	*/
 	async updatePagesJSON(filepath) {
-		if (filepath) {
-			const page = this.findPage(filepath);
-			if (page) {
-				await page.read();
-				if (!page.hasChanged()) {
-					debug.cache(`The page meta on page ${filepath} did not send any changes, skipping`);
-					return false;
-				}
+		return this.enqueuePagesUpdate(filepath ? [filepath] : void 0);
+	}
+	enqueuePagesUpdate(files) {
+		if (this.disposed) return Promise.resolve(false);
+		const update = this.pendingUpdate.then(() => this.disposed ? false : this.generatePagesJSON(files));
+		this.pendingUpdate = update.then(() => {}, () => {});
+		return update;
+	}
+	async generatePagesJSON(files) {
+		const candidates = files?.map((file) => this.findPages(file));
+		const incremental = !!candidates?.length && candidates.every((pages) => pages.length > 0);
+		if (incremental) {
+			const pages = [...new Set(candidates.flat())];
+			await Promise.all(pages.map((page) => page.read()));
+			if (!pages.some((page) => page.hasChanged())) {
+				debug.cache("Page metadata is unchanged, skipping generation");
+				return false;
 			}
 		}
+		this.generatedSnapshot = void 0;
 		checkPagesJsonFileSync(this.resolvedPagesJSONPath);
 		this.options.onBeforeLoadUserConfig();
 		await this.loadUserPagesConfig();
 		this.options.onAfterLoadUserConfig(this.pagesGlobConfig);
 		if (this.options.mergePages) {
 			this.options.onBeforeScanPages();
-			await this.scanPages();
-			await this.scanSubPages();
+			this.refreshScanPlan();
+			await this.scanPages(!incremental);
+			await this.scanSubPages(!incremental);
 			this.options.onAfterScanPages(this.pages, this.subPages);
+			this.startPageWatcher();
+			this.pageWatcher.refresh(this.requireScanPlan());
 		}
 		this.options.onBeforeMergePageMetaData(this.pages, this.pagesGlobConfig);
 		await this.mergePageMetaData();
@@ -1760,6 +3688,13 @@ var PageContext = class {
 		this.options.onBeforeWriteFile(this.resolvedPagesJSONPath);
 		const homePath = this.pageMetaData.find((meta) => meta.type === "home")?.path;
 		this.tabBar = await this.resolveTabBar();
+		this.generatedSnapshot = createPagesSnapshot({
+			pages: this.pageMetaData,
+			subPackages: this.subPageMetaData,
+			tabBar: this.tabBar,
+			globConfig: this.pagesGlobConfig,
+			homePath
+		});
 		const result = await writePagesJson(this.resolvedPagesJSONPath, {
 			pages: this.pageMetaData,
 			subPackages: this.subPageMetaData,
@@ -1775,9 +3710,29 @@ var PageContext = class {
 				insertFinalNewline: this.options.insertFinalNewline
 			}
 		});
-		this.generateDeclaration();
-		if (result?.updated) this.options.onAfterWriteFile(this.resolvedPagesJSONPath, result.content);
-		return result?.updated ?? false;
+		if (!result) throw new Error(`[vite-plugin-uni-pages] Failed to acquire the pages.json file lock: ${this.resolvedPagesJSONPath}`);
+		try {
+			await this.generateDeclaration();
+		} catch (error) {
+			if (result.updated) {
+				this.options.onAfterWriteFile(this.resolvedPagesJSONPath, result.content);
+				this.onUpdate();
+			}
+			throw error;
+		}
+		if (result.updated) this.options.onAfterWriteFile(this.resolvedPagesJSONPath, result.content);
+		if (this.configWatch.consumeExpanded() && !this.disposed) this.queuePageUpdate();
+		return result.updated;
+	}
+	/** 最近一次生成的路由快照；未写入文件时由当前工作字段合成 */
+	get snapshot() {
+		return this.generatedSnapshot ?? createPagesSnapshot({
+			pages: this.pageMetaData,
+			subPackages: this.subPageMetaData,
+			tabBar: this.tabBar,
+			globConfig: this.pagesGlobConfig,
+			homePath: this.pageMetaData.find((meta) => meta.type === "home")?.path
+		});
 	}
 	/**
 	* 生成虚拟模块内容
@@ -1785,21 +3740,22 @@ var PageContext = class {
 	* @returns 虚拟模块代码字符串
 	*/
 	virtualModule() {
-		return [`export const pages = ${this.resolveRoutes()};`, `export const subPackages = ${this.resolveSubRoutes()};`].join("\n");
+		const { pages, subPackages } = this.snapshot;
+		return [`export const pages = ${stringify(pages, null, 2)};`, `export const subPackages = ${stringify(subPackages, null, 2)};`].join("\n");
 	}
 	/**
 	* 将主包路由数据解析为 JSON 字符串
 	* @returns 主包页面配置的 JSON 字符串
 	*/
 	resolveRoutes() {
-		return stringify(this.pageMetaData, null, 2);
+		return stringify(this.snapshot.pages, null, 2);
 	}
 	/**
-	* 将子包路由数据解析为 JSON 字符串
-	* @returns 子包页面配置的 JSON 字符串
+	* 将分包路由数据解析为 JSON 字符串
+	* @returns 分包页面配置的 JSON 字符串
 	*/
 	resolveSubRoutes() {
-		return stringify(this.subPageMetaData, null, 2);
+		return stringify(this.snapshot.subPackages, null, 2);
 	}
 	/**
 	* 解析 tabBar 配置
@@ -1832,64 +3788,183 @@ var PageContext = class {
 	generateDeclaration() {
 		if (!this.options.dts) return;
 		debug.declaration("generating");
-		return writeDeclaration({
-			pages: this.pageMetaData,
-			subPackages: this.subPageMetaData,
-			tabBar: this.tabBar,
-			globConfig: this.pagesGlobConfig
-		}, this.options.dts);
+		return writeDeclaration(this.snapshot, this.options.dts);
 	}
 	/**
-	* 扫描主包页面目录并收集所有页面文件路径
-	* 根据配置的 dirs 选项扫描对应目录
+	* 按词法目录扫描主包页面
+	*
+	* @description 各目录分别执行文件排除，物理别名保留到页面有效性与归属决议阶段
 	*/
-	async scanPages() {
-		const paths = this.options.dirs.flatMap((dir) => getPagePaths(dir, this.options));
-		debug.pages(paths);
+	async scanPages(refreshContent = true) {
+		const plan = this.requireScanPlan();
 		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);
+		for (const [matchIndex, dir] of plan.mainDirs.entries()) for (const pagePath of getPagePaths(dir, this.options, plan.basePath)) {
+			if (pages.has(pagePath.absolutePath)) continue;
+			const page = this.trackPage(pagePath, this.pages.get(pagePath.absolutePath) ?? this.mainPageCandidates.get(pagePath.absolutePath), {
+				dir,
+				explicitRoot: false,
+				ruleIndex: 0,
+				matchIndex
+			}, refreshContent);
+			if (page) pages.set(pagePath.absolutePath, page);
 		}
-		this.pages = pages;
+		debug.pages([...pages.keys()]);
+		this.mainPageCandidates = pages;
+		this.pages = new Map(pages);
+	}
+	/**
+	* 登记本轮来源并复用身份与输出基准均未变化的 Page
+	*
+	* @description 整轮更新使读取缓存失效，增量更新复用目标页的预读结果与其他页面缓存
+	* @returns 路径仍存在时返回页面实例，扫描期间已消失时为 undefined
+	*/
+	trackPage(pagePath, previous, source, refreshContent) {
+		const identity = resolvePageIdentity(pagePath.absolutePath);
+		if (!identity) return;
+		const page = previous && this.pageSources.get(previous)?.identity === identity && previous.path.relativePath === pagePath.relativePath ? previous : new Page(this.pageEnvironment(), pagePath);
+		if (refreshContent) page.invalidate();
+		this.pageSources.set(page, {
+			file: pagePath.absolutePath,
+			identity,
+			dir: source.dir,
+			root: source.root,
+			explicitRoot: source.explicitRoot,
+			ruleIndex: source.ruleIndex,
+			matchIndex: source.matchIndex,
+			rootSource: source.rootSource,
+			rulePattern: this.configuredRule(source)
+		});
+		return page;
+	}
+	pageEnvironment() {
+		return {
+			platform: this.platform,
+			getLogger: () => this.logger
+		};
+	}
+	/** 页面来源的原始声明规则，用于冲突诊断；hook 页面可能没有 */
+	configuredRule(source) {
+		if (source.root === void 0) return this.options.dir;
+		const pattern = this.options.subPackagePatterns[source.ruleIndex];
+		return typeof pattern === "string" ? pattern : pattern?.dir;
 	}
 	/**
-	* 按页面文件绝对路径查找被跟踪的页面（主包或任一子包）
+	* 按词法路径或物理身份查找全部缓存候选
 	* @param filepath - 页面文件的绝对路径
-	* @returns 被跟踪的页面，文件未被跟踪时为 undefined
+	* @returns 主包和分包中属于同一文件的页面实例，每个实例只返回一次
 	*/
-	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;
-		}
+	findPages(filepath) {
+		const absolute = normalizePath(path.resolve(this.root, filepath));
+		const groups = [
+			this.mainPageCandidates,
+			...this.subPageCandidates.values(),
+			this.pages,
+			...this.subPages.values()
+		];
+		const identity = resolvePageIdentity(absolute);
+		if (!identity) return [];
+		const matched = groups.flatMap((pages) => [...pages.entries()].flatMap(([file, page]) => {
+			const source = this.pageSources.get(page);
+			return file === absolute || source?.identity === identity ? [page] : [];
+		}));
+		if (matched.some((page) => this.pageSources.get(page)?.identity !== identity || resolvePageIdentity(page.path.absolutePath) !== identity)) return [];
+		return [...new Set(matched)];
 	}
 	/**
-	* 扫描子包页面目录并收集所有子包页面文件路径
-	* 根据配置的 subPackages 选项扫描对应目录
+	* 按词法来源扫描分包页面
+	*
+	* @description 同一物理目录的不同别名仍分别执行文件排除，避免某个别名被排除后漏页
 	*/
-	async scanSubPages() {
+	async scanSubPages(refreshContent = true) {
+		const plan = this.requireScanPlan();
 		const paths = {};
 		const subPages = /* @__PURE__ */ new Map();
-		for (const dir of this.options.subPackages) {
-			const pagePaths = getPagePaths(dir, this.options);
+		const sources = this.subPackageSourcesByDir();
+		for (const [dir, source] of sources) {
+			const pagePaths = getPagePaths(dir, this.options, plan.basePath);
 			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);
+			for (const pagePath of pagePaths) {
+				const page = this.trackPage(pagePath, this.subPages.get(dir)?.get(pagePath.absolutePath) ?? this.subPageCandidates.get(dir)?.get(pagePath.absolutePath), source, refreshContent);
+				if (page) pages.set(pagePath.absolutePath, page);
 			}
 			subPages.set(dir, pages);
 		}
 		debug.subPages(JSON.stringify(paths, null, 2));
-		this.subPages = subPages;
+		this.subPageCandidates = subPages;
+		this.subPages = new Map([...subPages].map(([dir, pages]) => [dir, new Map(pages)]));
+	}
+	/**
+	* 为每个物理扫描目录选取声明来源
+	*
+	* @description 同一路径的不同写法只扫描一次，定位信息按显式优先选择；
+	* 符号链接别名是不同的 absolute，仍分别保留各自的词法路径
+	*/
+	subPackageSourcesByDir() {
+		const selected = /* @__PURE__ */ new Map();
+		const sources = this.scanPlan?.subPackageSources ?? [];
+		for (const source of sources) {
+			const previous = selected.get(source.absolute);
+			if (!previous || comparePageSources(source, previous) < 0) selected.set(source.absolute, source);
+		}
+		return new Map([...selected.values()].map((source) => [source.dir, source]));
+	}
+	/** 获取目录的最终分包 root，未登记时相对 outDir 计算默认值 */
+	subPackageRoot(dir) {
+		return this.scanPlan?.subPackageRootMap.get(dir) ?? this.options.subPackageRootMap.get(dir) ?? normalizePath(path.relative(this.basePath, path.resolve(this.options.root, dir)));
+	}
+	/**
+	* 决议有效页面的归属并校验生成路由
+	*
+	* @description 先读取宏并应用既有平台规则，再选择代表；冲突校验通过后才裁剪页面映射，
+	* 配置覆盖与输出去重在此之后执行
+	*/
+	async resolveScanSources() {
+		const candidates = [];
+		const subSources = this.options.mergePages ? this.subPackageSourcesByDir() : /* @__PURE__ */ new Map();
+		const groups = [[void 0, this.pages], ...this.subPages];
+		await Promise.all(groups.flatMap(([, pages]) => [...pages.values()].map((page) => page.ensureLoaded())));
+		for (const [dir, pages] of groups) {
+			const root = dir === void 0 ? void 0 : this.subPackageRoot(dir);
+			for (const [file, page] of pages) {
+				if (page.skipped) continue;
+				const meta = await page.getPageMeta();
+				const effective = dir === void 0 && this.withUniPlatform ? filterPlatformSuffixPages([meta], this.platform)[0] : meta;
+				if (!effective) continue;
+				const original = this.pageSources.get(page);
+				const identity = original?.identity ?? resolvePageIdentity(file);
+				if (!identity) continue;
+				const source = dir === void 0 ? void 0 : subSources.get(dir);
+				const ruleIndex = source?.ruleIndex ?? original?.ruleIndex ?? this.options.subPackages.indexOf(dir);
+				candidates.push({
+					...original,
+					...source,
+					page,
+					file,
+					identity,
+					dir: dir ?? original?.dir ?? this.options.dir,
+					root,
+					explicitRoot: source?.explicitRoot ?? original?.explicitRoot ?? false,
+					ruleIndex,
+					matchIndex: source?.matchIndex ?? original?.matchIndex ?? 0,
+					rulePattern: original?.rulePattern ?? this.configuredRule({
+						root,
+						ruleIndex
+					}),
+					route: root === void 0 ? effective.path : path.posix.join(root, normalizePath(path.relative(root, effective.path)))
+				});
+			}
+		}
+		const selected = selectPageSources(candidates);
+		validateGeneratedRoutes(selected, this.withUniPlatform ? this.platform : void 0);
+		const active = new Set(candidates.map((source) => source.page));
+		const representatives = new Set(selected.map((source) => source.page));
+		for (const pages of [this.pages, ...this.subPages.values()]) for (const [file, page] of pages) if (active.has(page) && !representatives.has(page)) pages.delete(file);
 	}
 	/**
 	* 解析 pages 规则并设置页面类型
 	* @param pages 页面路径映射
-	* @param packageType 页面包类型（主包或子包）
+	* @param packageType 页面包类型（主包或分包）
 	* @param overrides 自定义页面配置
 	* @returns pages 规则
 	*/
@@ -1929,25 +4004,33 @@ var PageContext = class {
 		return result;
 	}
 	/**
-	* 合并主包页面配置
-	* 过滤掉属于子包的页面，再解析页面配置并与用户配置合并
+	* 决议扫描来源后合并主包页面配置
+	*
+	* @description 有效分包优先认领物理页面，生成来源冲突在用户配置覆盖前检查
 	*/
 	async mergePageMetaData() {
-		for (const pages of this.subPages.values()) for (const subPageAbsolutePath of pages.keys()) this.pages.delete(subPageAbsolutePath);
+		await this.resolveScanSources();
 		const pageMetaData = await this.parsePages(this.pages, "main", this.pagesGlobConfig?.pages);
 		this.pageMetaData = pageMetaData;
 		debug.pages(this.pageMetaData);
 	}
 	/**
-	* 合并子包页面配置
-	* 为每个子包解析页面配置并处理子包配置继承
-	* 保留用户配置中子包级别的属性（如 plugins）
+	* 合并分包页面配置
+	*
+	* @description 静态、glob 和回调来源先按最终 root 汇集，再对整组应用一次配置覆盖，
+	* 保留手工页面和分包 plugins 配置
 	*/
 	async mergeSubPageMetaData() {
 		const packagesByRoot = /* @__PURE__ */ new Map();
 		const subPackages = this.pagesGlobConfig?.subPackages || [];
+		const pagesByRoot = /* @__PURE__ */ new Map();
 		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 root = this.subPackageRoot(dir);
+			const collected = pagesByRoot.get(root) ?? /* @__PURE__ */ new Map();
+			for (const [file, page] of pages) collected.set(file, page);
+			pagesByRoot.set(root, collected);
+		}
+		for (const [root, pages] of pagesByRoot) {
 			const globPackage = subPackages?.find((v) => v.root === root);
 			const overrides = globPackage?.pages?.map((page) => {
 				if (!page.path || page.path.startsWith(`${root}/`)) return page;
@@ -1989,9 +4072,8 @@ function resolveBasePath(options) {
 * @param options - 解析后的配置项
 * @returns 包含相对路径与绝对路径的页面路径数组
 */
-function getPagePaths(dir, options) {
+function getPagePaths(dir, options, basePath) {
 	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) => normalizePath(file)).map((file) => ({
@@ -2134,25 +4216,75 @@ async function generateAll(userOptions = {}, overrides = {}) {
 * @returns Vite 插件实例
 */
 function VitePluginUniPages(userOptions = {}) {
-	let ctx;
-	checkPagesJsonFileSync(resolvePagesJsonPath(process.env.VITE_ROOT_DIR || process.cwd(), userOptions.outDir ?? "src"));
-	return {
+	let initialization;
+	let preparedParams;
+	const resolvedPagesJSONPath = resolvePagesJsonPath(process.env.VITE_ROOT_DIR || process.cwd(), userOptions.outDir ?? "src");
+	if (existsSync(path.dirname(resolvedPagesJSONPath))) checkPagesJsonFileSync(resolvedPagesJSONPath);
+	const plugin = {
 		name: "vite-plugin-uni-pages",
 		enforce: "pre",
+		prepare(options) {
+			if (typeof options?.platformSuffix !== "boolean") return Promise.reject(/* @__PURE__ */ new TypeError("[vite-plugin-uni-pages] prepare() requires an explicit boolean platformSuffix option."));
+			try {
+				return initialize(options.root ?? process.env.VITE_ROOT_DIR ?? process.cwd(), options.platformSuffix, "prepare").promise;
+			} catch (error) {
+				return Promise.reject(error);
+			}
+		},
 		/**
 		* Vite configResolved 钩子
 		* 初始化 PageContext，设置 logger，生成初始 pages.json
 		*/
 		async configResolved(config) {
-			ctx = new PageContext(userOptions, config.root);
-			if (config.plugins.some((v) => v.name === "vite-plugin-uni-platform")) ctx.withUniPlatform = true;
-			const logger = createLogger(void 0, { prefix: "[vite-plugin-uni-pages]" });
-			ctx.setLogger(logger);
-			await ctx.updatePagesJSON();
-			if (config.command === "build") {
-				if (config.build.watch) ctx.setupWatcher(chokidar.watch([...ctx.options.dirs, ...ctx.options.subPackages].map((v) => normalizePath(path.resolve(config.root, v)))));
+			const state = initialize(config.root, config.plugins.some((v) => v.name === "vite-plugin-uni-platform"), config.command);
+			state.watching = config.command === "build" && !!config.build.watch;
+			try {
+				await state.promise;
+				if (state.closing) throw new Error("[vite-plugin-uni-pages] The pages context was closed during initialization.");
+				if (state.watching) {
+					const lockDirectory = normalizeConfigPath(`${state.context.resolvedPagesJSONPath}.lock`, config.root);
+					state.buildWatcher = chokidar.watch([], {
+						ignoreInitial: true,
+						followSymlinks: false,
+						ignored: (file) => {
+							const absolute = normalizeConfigPath(file, config.root);
+							return absolute.split("/").some((part) => part === "node_modules" || part === ".git") || absolute === lockDirectory || absolute.startsWith(`${lockDirectory}/`);
+						}
+					});
+					await state.context.setupWatcher(state.buildWatcher);
+				}
+			} catch (error) {
+				await release(state);
+				throw error;
 			}
 		},
+		options(options) {
+			const state = initialization;
+			if (state?.command !== "build") return;
+			const hooks = {
+				options: void 0,
+				load: (id) => loadVirtualModule(state, id),
+				closeWatcher: () => release(state),
+				closeBundle: () => state.watching ? void 0 : release(state)
+			};
+			const plugins = Array.isArray(options.plugins) ? options.plugins : [options.plugins];
+			plugins.forEach((candidate, index) => {
+				if (candidate && typeof candidate === "object" && "options" in candidate && candidate.options === plugin.options) plugins[index] = {
+					...candidate,
+					...hooks
+				};
+			});
+			return {
+				...options,
+				plugins
+			};
+		},
+		async closeWatcher() {
+			if (initialization) await release(initialization);
+		},
+		async closeBundle() {
+			if (initialization && !initialization.watching) await release(initialization);
+		},
 		/**
 		* 代码转换钩子
 		* 从 Vue SFC 中移除 definePage 宏调用，避免运行时报错
@@ -2179,7 +4311,7 @@ function VitePluginUniPages(userOptions = {}) {
 		* 设置文件监听与 HMR 支持
 		*/
 		configureServer(server) {
-			ctx.setupViteServer(server);
+			initialization?.context.setupViteServer(server);
 		},
 		/**
 		* 模块解析钩子
@@ -2193,9 +4325,99 @@ function VitePluginUniPages(userOptions = {}) {
 		* 返回虚拟模块的代码内容
 		*/
 		load(id) {
-			if (id === RESOLVED_MODULE_ID_VIRTUAL) return ctx.virtualModule();
+			return loadVirtualModule(initialization, id);
 		}
 	};
+	function initialize(root, platformSuffix, source) {
+		const resolvedRoot = normalizePath(path.resolve(root));
+		const platform = process.env.UNI_PLATFORM;
+		if (!platform) throw new Error("[vite-plugin-uni-pages] UNI_PLATFORM must be set before initializing pages. Run through the uni-app CLI or set the compilation platform before calling the plugin.");
+		const params = {
+			root: resolvedRoot,
+			platform,
+			platformSuffix
+		};
+		if (initialization?.closing || source !== "prepare" && initialization?.command) throw new Error("[vite-plugin-uni-pages] This plugin instance already has an active Vite session. Wait for it to close, or create a separate UniPages() instance for overlapping builds and servers. If Vite exited before starting Rollup or the dev server, this instance cannot be released either.");
+		const expected = preparedParams ?? initialization?.params;
+		const mismatched = expected && Object.keys(params).find((key) => expected[key] !== params[key]);
+		if (mismatched) throw new Error(`[vite-plugin-uni-pages] ${mismatched} does not match the initialized pages context. Use the same root, UNI_PLATFORM and UniPlatform setting for prepare() and Vite.`);
+		if (initialization) {
+			if (source === "prepare") {
+				initialization.prepared = true;
+				if (initialization.ready) preparedParams = params;
+			} else initialization.command = source;
+			return initialization;
+		}
+		const context = new PageContext(userOptions, resolvedRoot, platform);
+		context.withUniPlatform = platformSuffix;
+		context.setLogger(createLogger(void 0, { prefix: "[vite-plugin-uni-pages]" }));
+		const state = {
+			params,
+			context,
+			prepared: source === "prepare",
+			ready: false,
+			command: source === "prepare" ? void 0 : source,
+			watching: false,
+			promise: Promise.resolve().then(async () => {
+				await context.updatePagesJSON();
+				if (state.closing) throw new Error("[vite-plugin-uni-pages] The pages context was closed during initialization.");
+				state.ready = true;
+				if (state.prepared) preparedParams = params;
+				return plugin;
+			}).catch(async (error) => {
+				try {
+					await context.disposeWatchers();
+				} catch (cleanupError) {
+					reportReleaseFailure(state, cleanupError);
+				} finally {
+					if (initialization === state && !state.closing) initialization = void 0;
+				}
+				throw error;
+			})
+		};
+		initialization = state;
+		return state;
+	}
+	function loadVirtualModule(state, id) {
+		if (id !== "\0virtual:uni-pages") return;
+		if (!state || state.closing) throw new Error("[vite-plugin-uni-pages] The pages context is closed.");
+		return state.context.virtualModule();
+	}
+	/** 记录释放失败；关闭流程不因清理错误失败 */
+	function reportReleaseFailure(state, error) {
+		state.context.logger?.error(`Failed to release the pages context: ${error instanceof Error ? error.message : error}`, {
+			timestamp: true,
+			error: error instanceof Error ? error : void 0
+		});
+	}
+	/**
+	* 释放当前会话
+	*
+	* @description 解绑监听、等待已开始的生成并关闭构建 watcher；清理错误只记录，完成后释放实例占用
+	*/
+	function release(state) {
+		if (!state.closing) {
+			const disposing = state.context.disposeWatchers();
+			state.closing = (async () => {
+				try {
+					await disposing;
+				} catch (error) {
+					reportReleaseFailure(state, error);
+				} finally {
+					await state.promise.catch(() => {});
+					try {
+						await state.buildWatcher?.close();
+					} catch (error) {
+						reportReleaseFailure(state, error);
+					} finally {
+						if (initialization === state) initialization = void 0;
+					}
+				}
+			})();
+		}
+		return state.closing;
+	}
+	return plugin;
 }
 //#endregion
-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 };
+export { DefineConditional, FILE_EXTENSIONS, MODULE_ID_VIRTUAL, OUTPUT_NAME, Page, PageContext, RESOLVED_MODULE_ID_VIRTUAL, VitePluginUniPages, VitePluginUniPages as default, checkPagesJsonFileSync, createPages, debug, defineUniPages, discoverSubPackageDirectories, evaluateDefinePage, filterPlatformSuffixPages, findDefinePageMacro, generateAll, getPageFiles, getSubPackageDirectorySources, isConditional, isMissingFsError, isPageDirectoryEvent, isPageFileInDirectories, isTargetFile, mergePagesJson, normalizePagePattern, parseSFC, refreshPageDirectories, resolveConditional, resolveOptions, resolvePageDirs, resolvePagesJsonPath, resolveSubPackageDirs, retryOnEperm, unescapePagePattern, withFileLock, writePagesJson };