@ubean/build 0.4.3 → 0.4.5

package/dist/prerender.d.ts

@@ -21,6 +21,18 @@ interface PrerendererOptions {
   routeRules?: Record<string, RouteRule$1>;
   /** Content collection URLs merged into `include` (see `extractContentPageRoutes`). */
   contentRoutes?: string[];
+  /**
+   * 静态 SSG 模式：将 404 哨兵路由加入预渲染队列，产物为 `404.html`
+   * （供 GitHub Pages / Netlify 等静态托管平台的自定义 404 页）。
+   * fetcher 需识别 `STATIC_NOT_FOUND_ROUTE` 并渲染 notFoundPage。
+   */
+  notFoundRoute?: boolean;
+  /**
+   * i18n 多语言展开钩子（docs/adr/0011-lightweight-ssg-direct-render.md）：在 `collectPrerenderRoutes`
+   * 之后、入队之前应用，把收集到的路由扩展为全语言 URL 列表
+   * （如 `/about` → `['/about', '/zh/about']`）。
+   */
+  expandRoutes?: (routes: string[]) => string[];
   fetcher?: (url: string) => Promise<{
     html: string;
     statusCode: number;

package/dist/prerender.js

@@ -1,3 +1,4 @@
+import { STATIC_NOT_FOUND_ROUTE } from "./static-render.js";
 import { dirname, join } from "pathe";
 import { resolvePrerenderConfig } from "@ubean/config";
 import { DATA_PAYLOAD_ID } from "@ubean/pages";
@@ -127,6 +128,7 @@ function normalizeHref(href, baseUrl) {
 */
 function routeToFilePath(route, outputDir) {
 	if (route === "/" || route === "") return join(outputDir, "index.html");
+	if (route === "/__ubean_404__") return join(outputDir, "404.html");
 	if (route.endsWith(".html")) return join(outputDir, route);
 	const lastSegment = route.slice(route.lastIndexOf("/") + 1);
 	const dotIdx = lastSegment.lastIndexOf(".");
@@ -213,7 +215,8 @@ async function prerender(options) {
 		routeRules: options.routeRules,
 		contentRoutes: options.contentRoutes
 	});
-	const queue = [...initialRoutes];
+	const queue = [...options.expandRoutes ? options.expandRoutes(initialRoutes) : initialRoutes];
+	if (options.notFoundRoute) queue.unshift(STATIC_NOT_FOUND_ROUTE);
 	const visited = /* @__PURE__ */ new Set();
 	const results = [];
 	const generated = [];
@@ -223,11 +226,12 @@ async function prerender(options) {
 	async function processRoute(route) {
 		if (visited.has(route)) return;
 		visited.add(route);
-		if (config.exclude.some((p) => matchGlob(route, p))) {
+		if (route !== "/__ubean_404__" && config.exclude.some((p) => matchGlob(route, p))) {
 			if (!skipped.includes(route)) skipped.push(route);
 			return;
 		}
-		const result = { route };
+		const displayRoute = route === "/__ubean_404__" ? "/404" : route;
+		const result = { route: displayRoute };
 		try {
 			if (options.fetcher) {
 				const resp = await options.fetcher(route);
@@ -253,7 +257,7 @@ async function prerender(options) {
 					}
 				}
 				await writePrerenderedFile(routeToFilePath(route, outputDir), htmlToWrite);
-				generated.push(route);
+				generated.push(displayRoute);
 				result.html = void 0;
 			} else {
 				const placeholderHtml = `<!DOCTYPE html>
@@ -264,7 +268,7 @@ async function prerender(options) {
 </body>
 </html>`;
 				await writePrerenderedFile(routeToFilePath(route, outputDir), placeholderHtml);
-				generated.push(route);
+				generated.push(displayRoute);
 				result.statusCode = 200;
 			}
 		} catch (err) {

package/dist/production.js

@@ -2,7 +2,7 @@ import { a as useVirtualRegistry } from "./virtual-registry-BWkaQHXN.js";
 import { a as createRoutingVirtualModule, i as createPagesVirtualModule, n as createLocalesVirtualModule, r as createMetaVirtualModule, t as createAppVirtualModule } from "./virtual-modules-vLkLkAfT.js";
 import { a as ssrSingletonProdOptimizeExclude, o as ssrSingletonProdSsr } from "./ssr-singleton-CEQi_H6-.js";
 import { n as localeVueParamFromI18n, r as serializeI18nConfig, t as ubeanPlugin } from "./vite-D2EZl_6P.js";
-import { a as createVueAppEntryVirtualModule, i as createServerEntryVirtualModule, n as ubeanVite, o as createVuePagesVirtualModule, r as createClientEntryVirtualModule, t as VUE_PLUGIN_INCLUDE } from "./vue-I5nC0ldj.js";
+import { a as createVueAppEntryVirtualModule, i as createServerEntryVirtualModule, n as ubeanVite, o as createVuePagesVirtualModule, r as createClientEntryVirtualModule, t as VUE_PLUGIN_INCLUDE } from "./vue-CIj7ErAs.js";
 import { join, relative, resolve } from "pathe";
 import { resolveModules } from "@ubean/config";
 import { build } from "vite";
@@ -14,6 +14,282 @@ import { ubeanIslandsPlugin } from "@ubean/islands/vite";
 import { isEphemeralCachePreset, resolveProductionCacheStore } from "@ubean/preset";
 import { getLogger } from "@ubean/shared/logger";
 import { findUserViteConfig } from "@ubean/shared/node";
+//#region src/ssg-entry.ts
+/**
+* 生成 renderer setup 代码块（`_rendererRoutes` + `_pageRenderer`）。
+*
+* 依赖外层已定义：`_pages` / `_layouts` / `pageLoaders` / `layoutLoaders` /
+* （notFoundCatchAll 时）`_notFoundPage`，以及 `toVueRouterLocalePath` 导入。
+* ssrEnabled=false 时 `_pageRenderer = null`（与 fullstack 现状一致）。
+*/
+function buildRendererSetup(options) {
+	const { ssrEnabled, mode, localeVueParam, notFoundCatchAll } = options;
+	if (!ssrEnabled) return `
+// --- SSR disabled (mode=${mode}) ---
+// pageRenderer is null; page requests fall back to a client-only HTML shell.
+const _pageRenderer = null;`;
+	return `
+// --- SSR renderer setup ---
+const _defaultLayout = _layouts.find(l => l.isDefault)?.name || null;
+
+// Same i18n locale param as the client virtual:ubean-pages route table, so
+// language-prefixed URLs (e.g. /zh/playground) match the real page on SSR too.
+const _localeVueParam = ${JSON.stringify(localeVueParam)};
+
+const _rendererRoutes = _pages.map(p => {
+  // For reuse routes, load the target page's module (the .reuse.ts file
+  // only contains definePage metadata, not a Vue component).
+  const _targetPage = p.isReuse && p.reuseTarget ? _pages.find(tp => tp.name === p.reuseTarget) : undefined;
+  const _loaderKey = _targetPage?.relativePath || p.relativePath;
+  return {
+    path: _localeVueParam
+      ? toVueRouterLocalePath(p.route.replace(/\\*\\*:(\\w[\\w-]*)/g, ':$1(.*)*'), _localeVueParam)
+      : p.route.replace(/\\*\\*:(\\w[\\w-]*)/g, ':$1(.*)*'),
+    name: p.name,
+    component: async () => {
+      const loader = pageLoaders[_loaderKey];
+      if (!loader) throw new Error('Page loader not found: ' + _loaderKey);
+      const mod = await loader();
+      return mod.default || mod;
+    },
+    meta: {
+      layout: p.layout === false ? false : p.layout || _defaultLayout,
+      pageName: p.name,
+      cache: p.cache === true ? true : undefined
+    }
+  };
+});${notFoundCatchAll ? `
+
+// 404 渲染路由：注册为静态路径 /404（而非客户端的 /:pathMatch(.*)* catch-all）。
+// vue-router 中静态段确定性优先于 repeatable 参数 —— 即使应用存在根 catch-all
+// 页面（如 [...slug].vue），/404 也稳定命中本路由，保证 404.html 产物
+// 渲染的是 pages/404.vue 而非被 catch-all 抢占。
+if (_notFoundPage) {
+  const _nfLoaderKey = _notFoundPage.relativePath;
+  _rendererRoutes.push({
+    path: _localeVueParam
+      ? toVueRouterLocalePath('/404', _localeVueParam)
+      : '/404',
+    name: 'NotFound',
+    component: async () => {
+      const loader = pageLoaders[_nfLoaderKey];
+      if (!loader) throw new Error('Page loader not found: ' + _nfLoaderKey);
+      const mod = await loader();
+      return mod.default || mod;
+    },
+    meta: { pageName: 'NotFound' }
+  });
+}` : ""}
+
+const _layoutMap = new Map();
+for (const l of _layouts) {
+  _layoutMap.set(l.name, l.relativePath);
+}
+
+const _pageRenderer = createVueRenderer({
+  routes: _rendererRoutes,
+  async resolveLayoutComponent(name) {
+    if (name === false || name == null) return null;
+    const relPath = _layoutMap.get(name);
+    if (!relPath) return null;
+    const loader = layoutLoaders[relPath];
+    if (!loader) return null;
+    const mod = await loader();
+    return mod.default || mod;
+  },
+  defaultLayout: _defaultLayout,
+  resolveAppConfig: () => _resolveAppConfig('server')
+});
+`;
+}
+/**
+* 生成 client asset tags 代码块（读取 `.vite/manifest.json`）。
+* 依赖外层已定义 `readFileSync` / `join` / `dirname` / `fileURLToPath` 导入。
+*/
+function buildAssetTagsSetup(favicon) {
+	return `
+// --- Client asset tags from Vite manifest ---
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let _assetTags = { css: '', preloads: '', body: '', favicon: ${JSON.stringify(favicon)} };
+try {
+  const manifestPath = join(__dirname, '..', 'public', '.vite', 'manifest.json');
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  const entry = Object.values(manifest).find(m => m.isEntry);
+  if (entry) {
+    _assetTags.body = '<script type="module" src="/' + entry.file + '"><\/script>';
+    if (Array.isArray(entry.css)) {
+      _assetTags.css = entry.css.map(c => '<link rel="stylesheet" href="/' + c + '">').join('\\n');
+    }
+  }
+} catch (e) {
+  console.warn('[ubean] Failed to load client manifest:', e.message || e);
+}
+`;
+}
+/**
+* 生成静态 SSG entry 源码（写入 virtualDir/server-entry.mjs，由 SSR build
+* 产出 dist/server/entry.mjs）。
+*
+* 导出契约：
+* - `renderStaticPage({ pageName, params, url, locale }) → { html, statusCode }`
+* - `pageLoaders`（调试用）
+*/
+function buildStaticSsgEntry(input) {
+	const { pagesGlob, layoutsGlob, srcPrefix, pagesJson, layoutsJson, notFoundPageJson, localeVueParam, contentBootstrap, colorModeScript, favicon } = input;
+	return `// Auto-generated ubean static SSG entry (mode: ssg)
+import { renderPage } from '@ubean/pages';
+import { createVueRenderer } from 'ubean/ssr';
+import { toVueRouterLocalePath } from '@ubean/i18n';
+import { i18nConfig as _i18nConfig, loadLocales as _loadLocales } from 'ubean:locales';
+import { resolveAppConfig as _resolveAppConfig } from 'virtual:ubean-app';
+${contentBootstrap}
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const pageModules = import.meta.glob(${pagesGlob}, { eager: false });
+const layoutModules = import.meta.glob(${layoutsGlob}, { eager: false });
+
+const _srcPrefix = ${srcPrefix};
+function normalizeKey(p) {
+  const prefixes = ['/pages/', '/layouts/'];
+  for (const prefix of prefixes) {
+    const fullPrefix = _srcPrefix + prefix;
+    if (p.includes(fullPrefix)) {
+      const idx = p.indexOf(fullPrefix);
+      return p.slice(idx + fullPrefix.length);
+    }
+  }
+  return p;
+}
+
+export const pageLoaders = {};
+for (const [key, loader] of Object.entries(pageModules)) {
+  pageLoaders[normalizeKey(key)] = loader;
+}
+
+const layoutLoaders = {};
+for (const [key, loader] of Object.entries(layoutModules)) {
+  layoutLoaders[normalizeKey(key)] = loader;
+}
+
+const _pages = ${pagesJson};
+const _layouts = ${layoutsJson};
+const _notFoundPage = ${notFoundPageJson};
+const _hasDefaultLayout = _layouts.some(l => l.isDefault);
+${buildRendererSetup({
+		ssrEnabled: true,
+		mode: "ssg",
+		localeVueParam,
+		notFoundCatchAll: true
+	})}
+${buildAssetTagsSetup(favicon)}
+const _colorModeScript = ${JSON.stringify(colorModeScript)};
+
+// --- i18n ---
+const _i18nEnabled = _i18nConfig && _i18nConfig.enabled !== false;
+const _localeCodes = _i18nEnabled
+  ? (_i18nConfig.locales || []).map(l => (typeof l === 'string' ? l : l.code))
+  : [];
+const _defaultLocale = (_i18nEnabled && _i18nConfig.defaultLocale) || '';
+let _localesReady = false;
+
+async function _ensureLocales() {
+  if (_localesReady) return;
+  _localesReady = true;
+  if (!_i18nEnabled || _localeCodes.length === 0) return;
+  try {
+    await _loadLocales();
+  } catch (e) {
+    console.warn('[ubean-ssg] Failed to load locales:', (e && e.message) || e);
+  }
+}
+
+// 静态模式不执行 loader —— 检测到页面导出 loader 时警告一次（每页）
+const _loaderWarned = new Set();
+
+/**
+ * 渲染单个静态页面（由 createStaticSsgRenderer 调用）。
+ *
+ * @param input.pageName 目标页面名（ScannedPageRoute.name）或 'NotFound'
+ * @param input.params   路由参数（matchRoutePattern 提取）
+ * @param input.url      完整 URL path（含 locale 前缀与 query）
+ * @param input.locale   渲染语言（prefix 策略下已从 URL 提取）
+ */
+export async function renderStaticPage(input) {
+  const pageName = input && input.pageName;
+  const page = pageName === 'NotFound' ? _notFoundPage : _pages.find(p => p.name === pageName);
+  if (!page) return { html: '', statusCode: 404 };
+
+  await _ensureLocales();
+
+  // loader 检测 warn（模块加载有缓存，此处与渲染共用同一实例）
+  const _targetPage =
+    page.isReuse && page.reuseTarget ? _pages.find(tp => tp.name === page.reuseTarget) : undefined;
+  const _loaderKey = (_targetPage && _targetPage.relativePath) || page.relativePath;
+  const _modLoader = pageLoaders[_loaderKey];
+  if (_modLoader && !_loaderWarned.has(page.name)) {
+    try {
+      const mod = await _modLoader();
+      if (mod && typeof mod.loader === 'function') {
+        _loaderWarned.add(page.name);
+        console.warn(
+          '[ubean-ssg] page "' + page.name + '" exports \`loader\`, which is not executed in static SSG mode'
+        );
+      }
+    } catch {}
+  }
+
+  // renderContext 构造与 routes/router.ts 的页面渲染路径保持一致
+  const renderContext = {};
+  const locale = (input && input.locale) || _defaultLocale;
+  if (_i18nEnabled && locale) {
+    renderContext.locale = locale;
+    renderContext.localeDir = 'ltr';
+    renderContext.routing = {
+      defaultLocale: _i18nConfig.defaultLocale || 'en',
+      locales: _localeCodes,
+      strategy: _i18nConfig.strategy || 'prefix_except_default'
+    };
+    const cookieName =
+      _i18nConfig.detectBrowserLanguage && _i18nConfig.detectBrowserLanguage.cookieName;
+    if (cookieName) renderContext.cookieName = cookieName;
+    if (_i18nConfig.baseUrl) renderContext.baseUrl = _i18nConfig.baseUrl;
+    try {
+      const i18nMod = await import('ubean/i18n');
+      renderContext.localeDir = i18nMod.getLocaleDir(locale);
+      renderContext.messages = i18nMod.getLocaleMessages(locale);
+      const fallback = i18nMod.getFallbackLocale();
+      renderContext.fallbackLocale = fallback;
+      if (fallback !== locale) {
+        renderContext.fallbackMessages = i18nMod.getLocaleMessages(fallback);
+      }
+      renderContext.availableLocales = i18nMod.getRegisteredLocalesMeta();
+    } catch {}
+  }
+
+  // pageObj 构造与 routes/router.ts handlePageRequest 保持一致
+  const pageObj = {
+    component: page.reuseTarget || page.name,
+    props: {},
+    params: (input && input.params) || {},
+    url: (input && input.url) || '/',
+    layout: page.layout === false
+      ? false
+      : page.layout || (page.pageMeta && page.pageMeta.layout) || (_hasDefaultLayout ? 'default' : false),
+    errors: null,
+    head: page.pageMeta && page.pageMeta.head
+  };
+
+  let html = await renderPage(pageObj, _assetTags, _pageRenderer, 'app', renderContext);
+  if (_colorModeScript) {
+    html = html.replace('<head>', '<head>\\n    ' + _colorModeScript);
+  }
+  return { html, statusCode: 200 };
+}
+`;
+}
+//#endregion
 //#region src/production.ts
 const logger = getLogger("build");
 function getOutDirs(cwd, outputDir) {
@@ -134,61 +410,12 @@ async function generateVirtualModulesToDisk(cwd, config, scanResult, virtualDir,
 	const colorModeScript = config.colorMode !== false ? getColorModeScript(resolveColorModeConfig(config.colorMode)) : "";
 	const rendererImport = ssrEnabled ? `import { createVueRenderer } from 'ubean/ssr';` : "";
 	const prodLocaleVueParam = localeVueParamFromI18n(config.i18n) || "";
-	const rendererSetup = ssrEnabled ? `
-// --- SSR renderer setup ---
-const _defaultLayout = _layouts.find(l => l.isDefault)?.name || null;
-
-// Same i18n locale param as the client virtual:ubean-pages route table, so
-// language-prefixed URLs (e.g. /zh/playground) match the real page on SSR too.
-const _localeVueParam = ${JSON.stringify(prodLocaleVueParam)};
-
-const _rendererRoutes = _pages.map(p => {
-  // For reuse routes, load the target page's module (the .reuse.ts file
-  // only contains definePage metadata, not a Vue component).
-  const _targetPage = p.isReuse && p.reuseTarget ? _pages.find(tp => tp.name === p.reuseTarget) : undefined;
-  const _loaderKey = _targetPage?.relativePath || p.relativePath;
-  return {
-    path: _localeVueParam
-      ? toVueRouterLocalePath(p.route.replace(/\\*\\*:(\\w[\\w-]*)/g, ':$1(.*)*'), _localeVueParam)
-      : p.route.replace(/\\*\\*:(\\w[\\w-]*)/g, ':$1(.*)*'),
-    name: p.name,
-    component: async () => {
-      const loader = pageLoaders[_loaderKey];
-      if (!loader) throw new Error('Page loader not found: ' + _loaderKey);
-      const mod = await loader();
-      return mod.default || mod;
-    },
-    meta: {
-      layout: p.layout === false ? false : p.layout || _defaultLayout,
-      pageName: p.name,
-      cache: p.cache === true ? true : undefined
-    }
-  };
-});
-
-const _layoutMap = new Map();
-for (const l of _layouts) {
-  _layoutMap.set(l.name, l.relativePath);
-}
-
-const _pageRenderer = createVueRenderer({
-  routes: _rendererRoutes,
-  async resolveLayoutComponent(name) {
-    if (name === false || name == null) return null;
-    const relPath = _layoutMap.get(name);
-    if (!relPath) return null;
-    const loader = layoutLoaders[relPath];
-    if (!loader) return null;
-    const mod = await loader();
-    return mod.default || mod;
-  },
-  defaultLayout: _defaultLayout,
-  resolveAppConfig: () => _resolveAppConfig('server')
-});
-` : `
-// --- SSR disabled (mode=${mode}, ssr=${config.ssr.enabled}) ---
-// pageRenderer is null; page requests fall back to a client-only HTML shell.
-const _pageRenderer = null;`;
+	const rendererSetup = buildRendererSetup({
+		ssrEnabled,
+		mode,
+		localeVueParam: prodLocaleVueParam
+	});
+	const assetTagsSetup = buildAssetTagsSetup(config.favicon);
 	const productionCache = resolveProductionCacheStore(preset.name || "standard", config.cache);
 	const contentEntries = Object.entries(contentSnapshot ?? {}).filter(([, docs]) => Array.isArray(docs));
 	const contentBootstrap = contentEntries.length > 0 ? `
@@ -201,6 +428,22 @@ ${contentEntries.map(([name, docs]) => `registerContent(${JSON.stringify(name)},
 	const cronImport = enableInProcessCron ? `import { startCronScheduler } from '@ubean/server/cron';
 ` : "";
 	if (hasServer) {
+		if (mode === "ssg") {
+			const staticEntry = buildStaticSsgEntry({
+				pagesGlob,
+				layoutsGlob,
+				srcPrefix: JSON.stringify(viteSrcPrefix),
+				pagesJson,
+				layoutsJson,
+				notFoundPageJson,
+				localeVueParam: prodLocaleVueParam,
+				contentBootstrap,
+				colorModeScript,
+				favicon: config.favicon
+			});
+			await writeFile(join(virtualDir, "server-entry.mjs"), staticEntry, "utf-8");
+			return virtualDir;
+		}
 		const serverEntry = `// Auto-generated server entry
 import { createUbeanApp, applyServerConfig } from 'ubean/server';
 import { toVueRouterLocalePath } from '@ubean/i18n';
@@ -260,22 +503,7 @@ const _pages = ${pagesJson};
 const _layouts = ${layoutsJson};
 const _notFoundPage = ${notFoundPageJson};
 ${rendererSetup}
-// --- Client asset tags from Vite manifest ---
-const __dirname = dirname(fileURLToPath(import.meta.url));
-let _assetTags = { css: '', preloads: '', body: '', favicon: ${JSON.stringify(config.favicon)} };
-try {
-  const manifestPath = join(__dirname, '..', 'public', '.vite', 'manifest.json');
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
-  const entry = Object.values(manifest).find(m => m.isEntry);
-  if (entry) {
-    _assetTags.body = '<script type="module" src="/' + entry.file + '"><\/script>';
-    if (Array.isArray(entry.css)) {
-      _assetTags.css = entry.css.map(c => '<link rel="stylesheet" href="/' + c + '">').join('\\n');
-    }
-  }
-} catch (e) {
-  console.warn('[ubean] Failed to load client manifest:', e.message || e);
-}
+${assetTagsSetup}
 
 export async function createApp(options = {}) {
   const app = createUbeanApp({
@@ -625,7 +853,8 @@ async function buildProduction(options) {
 			resolve: commonResolve
 		});
 		serverEntry = "entry.mjs";
-		if (presetBuildConfig.entryType === "node") {
+		if (mode === "ssg") logger.info("SSG mode: skipping preset server wrapper (static output only)");
+		else if (presetBuildConfig.entryType === "node") {
 			await writeFile(join(outDirs.server, "server.mjs"), generateNodeServerEntry(), "utf-8");
 			serverEntry = "server.mjs";
 			await writeFile(join(outDirs.server, "package.json"), JSON.stringify({

package/dist/static-render.d.ts

@@ -0,0 +1,101 @@
+import { ScannedPageRoute } from "@ubean/scan";
+//#region src/static-render.d.ts
+/** 哨兵路由：prerender 队列中的 404 页标记，产物映射为 `404.html` */
+declare const STATIC_NOT_FOUND_ROUTE = "/__ubean_404__";
+interface CompiledPageRoute {
+  page: ScannedPageRoute;
+  regex: RegExp;
+  /** 捕获组顺序对应的参数名 */
+  paramNames: string[];
+  isCatchAll: boolean;
+  /** 静态段数量（特异性排序用） */
+  staticSegments: number;
+}
+/**
+ * 编译页面路由模式为正则。
+ *
+ * 输入 `page.route` 两种形态：
+ * 1. scan 产物默认语法（route-path.ts）：
+ *    - `/about`（静态）
+ *    - `/blog/:slug`（动态）
+ *    - `/docs/**:path`（catch-all，匹配剩余全部段，也匹配模式自身）
+ *    - `/users/:id?`（可选段）
+ * 2. `definePage({ path })` 覆盖的 vue-router 语法：
+ *    - `/blog/:slug(.*)*`（自定义正则 + 可重复 = catch-all）
+ *    - `/users/:id(\\d+)`（自定义正则）
+ */
+declare function compilePageRoute(page: ScannedPageRoute): CompiledPageRoute;
+interface StaticRouteMatch {
+  page: ScannedPageRoute;
+  params: Record<string, string>;
+}
+/**
+ * 将具象 URL path 匹配到页面路由模式，返回命中的页面与提取的参数。
+ *
+ * 匹配顺序（确定性）：静态段多者优先 → catch-all 最后 → 同分保持传入顺序。
+ * 参数值经 `decodeURIComponent` 解码（对齐 Hono `c.req.param()` 行为）。
+ */
+declare function matchRoutePattern(pages: Array<ScannedPageRoute | CompiledPageRoute>, path: string): StaticRouteMatch | null;
+/**
+ * 按路由策略将收集到的路由展开为全语言 URL 列表。
+ *
+ * | strategy | 展开规则 |
+ * | --- | --- |
+ * | `no_prefix` | 不展开（每 route 渲染 1 次） |
+ * | `prefix_except_default` | default 无前缀 + 其余 locale 带前缀 |
+ * | `prefix` | 全部 locale 带前缀（无前缀版本不生成——fetcher 对其 404） |
+ * | `prefix_and_default` | 全部 locale 带前缀 + default 额外无前缀版本 |
+ *
+ * 特殊输入：
+ * - 404 哨兵路由不展开（静态托管平台仅认单份 `404.html`）
+ * - 已带 locale 前缀的 URL（crawlLinks 发现）保持原样，避免 `/zh/zh/about`
+ */
+declare function expandRoutesForLocales(routes: string[], i18n: StaticSsgRendererI18nInit): string[];
+interface StaticSsgRendererI18nInit {
+  enabled?: boolean;
+  strategy?: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
+  defaultLocale?: string;
+  locales?: Array<string | {
+    code: string;
+  }>;
+}
+interface StaticSsgRendererInit {
+  /** 扫描得到的页面（含动态路由模式，供具象 URL 匹配） */
+  pages: ScannedPageRoute[];
+  /** `pages/404.vue` 自动检测的 404 页（可选） */
+  notFoundPage?: ScannedPageRoute | null;
+  /** i18n 配置（用于 locale 前缀剥离与默认语言） */
+  i18n?: StaticSsgRendererI18nInit;
+}
+interface RenderStaticPageInput {
+  pageName: string;
+  params: Record<string, string>;
+  url: string;
+  locale?: string;
+}
+type RenderStaticPageFn = (input: RenderStaticPageInput) => Promise<{
+  html: string;
+  statusCode: number;
+}>;
+interface StaticSsgRenderer {
+  /** 与 `PrerendererOptions.fetcher` 同构的契约 */
+  fetcher: (url: string) => Promise<{
+    html: string;
+    statusCode: number;
+  }>;
+  /** i18n 多语言展开（按 strategy 生成全语言 URL，供 prerender 入队前应用） */
+  expandRoutes: (routes: string[]) => string[];
+  /** 底层渲染函数（等价性测试 / 调试用） */
+  renderStaticPage: RenderStaticPageFn;
+}
+/**
+ * 加载构建产物中的静态 entry（`dist/server/entry.mjs`），返回静态渲染器。
+ *
+ * 失败（entry 缺失 / 无 renderStaticPage 导出 / 加载异常）返回 `undefined`，
+ * 由调用方降级（warn + placeholder prerender）。
+ */
+declare function createStaticSsgRenderer(cwd: string, manifest: {
+  serverDir: string;
+}, init: StaticSsgRendererInit): Promise<StaticSsgRenderer | undefined>;
+//#endregion
+export { CompiledPageRoute, RenderStaticPageFn, RenderStaticPageInput, STATIC_NOT_FOUND_ROUTE, StaticRouteMatch, StaticSsgRenderer, StaticSsgRendererI18nInit, StaticSsgRendererInit, compilePageRoute, createStaticSsgRenderer, expandRoutesForLocales, matchRoutePattern };

package/dist/static-render.js

@@ -0,0 +1,254 @@
+import { resolve } from "pathe";
+import { extractLocaleFromPath } from "@ubean/i18n";
+import { getLogger } from "@ubean/shared/logger";
+import { pathToFileURL } from "node:url";
+//#region src/static-render.ts
+/**
+* 静态 SSG 渲染器（mode: 'ssg' 专用，见 docs/adr/0011-lightweight-ssg-direct-render.md）。
+*
+* 职责：
+* 1. `compilePageRoute` / `matchRoutePattern`：把具象 URL 匹配到页面路由模式
+*    （`[param]` → `:param`、`[...slug]` → `**:slug`、`[[param]]` → `:param?`），
+*    提取路由参数 —— 替代 Hono 的路由匹配层
+* 2. `createStaticSsgRenderer`：加载构建产物中的静态 entry（renderStaticPage），
+*    暴露与 `prerender()` 的 fetcher 同构的契约，绕过 Hono 请求管道
+*/
+const logger = getLogger("build");
+/** 哨兵路由：prerender 队列中的 404 页标记，产物映射为 `404.html` */
+const STATIC_NOT_FOUND_ROUTE = "/__ubean_404__";
+const CATCH_ALL_SEGMENT = /^\*\*:([A-Za-z_][\w-]*)$/;
+/**
+* vue-router 参数段语法（`definePage({ path })` 覆盖时的 route 形态）：
+* - `:param` → 单段
+* - `:param?` → 可选单段
+* - `:param(regex)` → 自定义正则（如 `:id(\\d+)`）
+* - `:param(regex)*` / `:param*` → 可重复（0..n 段，如 `:slug(.*)*` catch-all）
+* - `:param(regex)+` / `:param+` → 可重复（1..n 段）
+*/
+const DYNAMIC_SEGMENT = /^:([A-Za-z_][\w-]*)(\(.+\))?([*+?])?$/;
+function escapeRegExp(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** 归一化 URL path：去尾部斜杠（根路由归一为空串便于匹配） */
+function normalizeUrlPath(path) {
+	if (path === "/" || path === "") return "";
+	let p = path;
+	if (!p.startsWith("/")) p = `/${p}`;
+	while (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+	return p;
+}
+/**
+* 编译页面路由模式为正则。
+*
+* 输入 `page.route` 两种形态：
+* 1. scan 产物默认语法（route-path.ts）：
+*    - `/about`（静态）
+*    - `/blog/:slug`（动态）
+*    - `/docs/**:path`（catch-all，匹配剩余全部段，也匹配模式自身）
+*    - `/users/:id?`（可选段）
+* 2. `definePage({ path })` 覆盖的 vue-router 语法：
+*    - `/blog/:slug(.*)*`（自定义正则 + 可重复 = catch-all）
+*    - `/users/:id(\\d+)`（自定义正则）
+*/
+function compilePageRoute(page) {
+	const segments = normalizeUrlPath(page.route).split("/").filter(Boolean);
+	let source = "^";
+	const paramNames = [];
+	let isCatchAll = false;
+	let staticSegments = 0;
+	for (const seg of segments) {
+		const catchAll = CATCH_ALL_SEGMENT.exec(seg);
+		if (catchAll) {
+			paramNames.push(catchAll[1]);
+			isCatchAll = true;
+			source += "(?:/(.+))?";
+			continue;
+		}
+		const dynamic = DYNAMIC_SEGMENT.exec(seg);
+		if (dynamic) {
+			const [, name, custom, modifier] = dynamic;
+			paramNames.push(name);
+			const inner = custom ? custom.slice(1, -1) : "[^/]+";
+			if (modifier === "*" || modifier === "+") {
+				isCatchAll = true;
+				source += modifier === "*" ? `(?:/(${inner}(?:/${inner})*))?` : `/(${inner}(?:/${inner})*)`;
+			} else if (modifier === "?") source += `(?:/(${inner}))?`;
+			else source += `/(${inner})`;
+			continue;
+		}
+		staticSegments++;
+		source += `/${escapeRegExp(seg)}`;
+	}
+	source += "/?$";
+	return {
+		page,
+		regex: new RegExp(source),
+		paramNames,
+		isCatchAll,
+		staticSegments
+	};
+}
+/**
+* 将具象 URL path 匹配到页面路由模式，返回命中的页面与提取的参数。
+*
+* 匹配顺序（确定性）：静态段多者优先 → catch-all 最后 → 同分保持传入顺序。
+* 参数值经 `decodeURIComponent` 解码（对齐 Hono `c.req.param()` 行为）。
+*/
+function matchRoutePattern(pages, path) {
+	const ordered = pages.map((p) => "regex" in p ? p : compilePageRoute(p)).map((c, i) => ({
+		c,
+		i
+	})).sort((a, b) => Number(a.c.isCatchAll) - Number(b.c.isCatchAll) || b.c.staticSegments - a.c.staticSegments || a.i - b.i).map(({ c }) => c);
+	const target = normalizeUrlPath(path);
+	for (const c of ordered) {
+		const m = c.regex.exec(target);
+		if (!m) continue;
+		const params = {};
+		c.paramNames.forEach((name, idx) => {
+			const raw = m[idx + 1];
+			if (raw === void 0) return;
+			try {
+				params[name] = decodeURIComponent(raw);
+			} catch {
+				params[name] = raw;
+			}
+		});
+		return {
+			page: c.page,
+			params
+		};
+	}
+	return null;
+}
+function dedupeRoutes(routes) {
+	return [...new Set(routes)];
+}
+/**
+* 按路由策略将收集到的路由展开为全语言 URL 列表。
+*
+* | strategy | 展开规则 |
+* | --- | --- |
+* | `no_prefix` | 不展开（每 route 渲染 1 次） |
+* | `prefix_except_default` | default 无前缀 + 其余 locale 带前缀 |
+* | `prefix` | 全部 locale 带前缀（无前缀版本不生成——fetcher 对其 404） |
+* | `prefix_and_default` | 全部 locale 带前缀 + default 额外无前缀版本 |
+*
+* 特殊输入：
+* - 404 哨兵路由不展开（静态托管平台仅认单份 `404.html`）
+* - 已带 locale 前缀的 URL（crawlLinks 发现）保持原样，避免 `/zh/zh/about`
+*/
+function expandRoutesForLocales(routes, i18n) {
+	const i18nEnabled = i18n != null && i18n.enabled !== false;
+	const localeCodes = i18nEnabled ? (i18n.locales || []).map((l) => typeof l === "string" ? l : l.code) : [];
+	if (!i18nEnabled || localeCodes.length === 0) return dedupeRoutes(routes);
+	const strategy = i18n.strategy || "prefix_except_default";
+	if (strategy === "no_prefix") return dedupeRoutes(routes);
+	const defaultLocale = i18n.defaultLocale || localeCodes[0] || "";
+	const expanded = [];
+	for (const route of routes) {
+		if (route === "/__ubean_404__") {
+			expanded.push(route);
+			continue;
+		}
+		const { locale } = extractLocaleFromPath(route, localeCodes);
+		if (locale) {
+			expanded.push(route);
+			continue;
+		}
+		const suffix = route === "/" || route === "" ? "" : route;
+		switch (strategy) {
+			case "prefix":
+				for (const code of localeCodes) expanded.push(`/${code}${suffix}`);
+				break;
+			case "prefix_and_default":
+				expanded.push(route || "/");
+				for (const code of localeCodes) expanded.push(`/${code}${suffix}`);
+				break;
+			default:
+				expanded.push(route || "/");
+				for (const code of localeCodes) {
+					if (code === defaultLocale) continue;
+					expanded.push(`/${code}${suffix}`);
+				}
+		}
+	}
+	return dedupeRoutes(expanded);
+}
+/**
+* 加载构建产物中的静态 entry（`dist/server/entry.mjs`），返回静态渲染器。
+*
+* 失败（entry 缺失 / 无 renderStaticPage 导出 / 加载异常）返回 `undefined`，
+* 由调用方降级（warn + placeholder prerender）。
+*/
+async function createStaticSsgRenderer(cwd, manifest, init) {
+	let mod;
+	try {
+		const entryPath = resolve(cwd, manifest.serverDir, "entry.mjs");
+		mod = await import(pathToFileURL(entryPath).href);
+	} catch (err) {
+		logger.warn(`Failed to load static SSG entry: ${err instanceof Error ? err.message : String(err)}. Falling back.`);
+		return;
+	}
+	if (typeof mod.renderStaticPage !== "function") {
+		logger.warn("Static SSG entry does not export renderStaticPage; falling back.");
+		return;
+	}
+	const renderStaticPage = mod.renderStaticPage;
+	const compiled = init.pages.map(compilePageRoute);
+	const i18nEnabled = init.i18n != null && init.i18n.enabled !== false;
+	const localeCodes = i18nEnabled ? (init.i18n?.locales || []).map((l) => typeof l === "string" ? l : l.code) : [];
+	const strategy = i18nEnabled ? init.i18n?.strategy || "prefix_except_default" : "no_prefix";
+	const defaultLocale = i18nEnabled && init.i18n?.defaultLocale || "";
+	const usePrefix = i18nEnabled && localeCodes.length > 0 && strategy !== "no_prefix";
+	return {
+		renderStaticPage,
+		expandRoutes: (routes) => expandRoutesForLocales(routes, {
+			enabled: i18nEnabled,
+			strategy,
+			defaultLocale,
+			locales: localeCodes
+		}),
+		fetcher: async (url) => {
+			const u = new URL(url, "http://ubean.local");
+			const pathname = u.pathname;
+			const search = u.search;
+			if (pathname === "/__ubean_404__") {
+				if (!init.notFoundPage) return {
+					html: "",
+					statusCode: 404
+				};
+				return renderStaticPage({
+					pageName: "NotFound",
+					params: {},
+					url: `/404${search}`,
+					locale: defaultLocale
+				});
+			}
+			let pathToMatch = pathname;
+			let locale = defaultLocale;
+			if (usePrefix) {
+				const { locale: extracted, pathWithoutLocale } = extractLocaleFromPath(pathname, localeCodes);
+				if (extracted) {
+					locale = extracted;
+					pathToMatch = pathWithoutLocale;
+				} else if (strategy === "prefix") return {
+					html: "",
+					statusCode: 404
+				};
+			}
+			const match = matchRoutePattern(compiled, pathToMatch);
+			if (!match) return {
+				html: "",
+				statusCode: 404
+			};
+			return renderStaticPage({
+				pageName: match.page.name,
+				params: match.params,
+				url: `${pathname}${search}`,
+				locale
+			});
+		}
+	};
+}
+//#endregion
+export { STATIC_NOT_FOUND_ROUTE, compilePageRoute, createStaticSsgRenderer, expandRoutesForLocales, matchRoutePattern };

package/dist/{vue-I5nC0ldj.js → vue-CIj7ErAs.js}

@@ -9,10 +9,10 @@ import { transformWithOxc } from "vite";
 import Components from "unplugin-vue-components/vite";
 import Markdown from "unplugin-vue-markdown/vite";
 import AutoImport from "unplugin-auto-import/vite";
-import VueI18nPlugin from "@intlify/unplugin-vue-i18n/vite";
 import { getColorModeScript, getPartyTownScript, resolveColorModeConfig, resolvePartyTownConfig } from "@ubean/client";
 import { ubeanMdxPlugin } from "@ubean/markdown";
 import { renderFaviconLink } from "@ubean/pages";
+import VueI18nPlugin from "@intlify/unplugin-vue-i18n/vite";
 import { generatePagesModuleSource } from "@ubean/vue/vite";
 //#region src/vue-virtual-modules.ts
 /**
@@ -162,15 +162,17 @@ function _mergeAppConfig(base, ...configs) {
   for (const cfg of [base, ...configs]) {
     if (cfg?.router?.setup) setups.push(cfg.router.setup);
   }
-  if (setups.length === 1) {
-    result.router = { setup: setups[0] };
-  } else if (setups.length > 1) {
-    result.router = {
-      setup: (router) => {
-        for (const s of setups) s(router);
-      }
-    };
+  // scrollBehavior 为函数不可合并,后者覆盖(shared 之后定义的 client/server 生效)。
+  let scrollBehavior;
+  for (const cfg of [base, ...configs]) {
+    if (cfg?.router?.scrollBehavior !== undefined) scrollBehavior = cfg.router.scrollBehavior;
+  }
+  const router = {};
+  if (setups.length > 0) {
+    router.setup = setups.length === 1 ? setups[0] : (r) => { for (const s of setups) s(r); };
   }
+  if (scrollBehavior !== undefined) router.scrollBehavior = scrollBehavior;
+  if (setups.length > 0 || scrollBehavior !== undefined) result.router = router;
   return result;
 }
 
@@ -233,7 +235,7 @@ export async function createApp() {
     viewTransitions: config.viewTransitions,
     initialPage: initialPage || undefined,
     hydrate: !!initialPage,
-    routerSetup: config.router?.setup,
+    router: config.router,
     loadingComponent,
     errorComponent,
     // appRoot 已在 resolveAppConfig 中合并(src/App.vue 默认 + defineApp 显式覆盖)
@@ -318,7 +320,7 @@ export async function createSSRApp(initialPage) {
     resolveLayoutComponent,
     defaultLayout,
     head,
-    routerSetup: config.router?.setup,
+    router: config.router,
     loadingComponent,
     errorComponent,
     // appRoot 已在 resolveAppConfig 中合并(src/App.vue 默认 + defineApp 显式覆盖),

package/dist/vue.js

@@ -1,2 +1,2 @@
-import { a as createVueAppEntryVirtualModule, i as createServerEntryVirtualModule, n as ubeanVite, o as createVuePagesVirtualModule, r as createClientEntryVirtualModule, t as VUE_PLUGIN_INCLUDE } from "./vue-I5nC0ldj.js";
+import { a as createVueAppEntryVirtualModule, i as createServerEntryVirtualModule, n as ubeanVite, o as createVuePagesVirtualModule, r as createClientEntryVirtualModule, t as VUE_PLUGIN_INCLUDE } from "./vue-CIj7ErAs.js";
 export { VUE_PLUGIN_INCLUDE, createClientEntryVirtualModule, createServerEntryVirtualModule, createVueAppEntryVirtualModule, createVuePagesVirtualModule, ubeanVite as default, ubeanVite };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/build",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Vite plugins, production build, SSG prerender, type codegen, and Server Actions plugin for ubean",
   "files": [
     "dist"
@@ -30,6 +30,10 @@
       "types": "./dist/prerender.d.ts",
       "import": "./dist/prerender.js"
     },
+    "./static-render": {
+      "types": "./dist/static-render.d.ts",
+      "import": "./dist/static-render.js"
+    },
     "./codegen": {
       "types": "./dist/codegen/index.d.ts",
       "import": "./dist/codegen/index.js"
@@ -41,17 +45,17 @@
   },
   "dependencies": {
     "@intlify/unplugin-vue-i18n": "11.2.5",
-    "@ubean/client": "0.4.3",
-    "@ubean/config": "0.4.3",
-    "@ubean/i18n": "0.4.3",
-    "@ubean/islands": "0.4.3",
-    "@ubean/markdown": "0.4.3",
-    "@ubean/pages": "0.4.3",
-    "@ubean/preset": "0.4.3",
-    "@ubean/routes": "0.4.3",
-    "@ubean/scan": "0.4.3",
-    "@ubean/shared": "0.4.3",
-    "@ubean/vue": "0.4.3",
+    "@ubean/client": "0.4.5",
+    "@ubean/config": "0.4.5",
+    "@ubean/i18n": "0.4.5",
+    "@ubean/islands": "0.4.5",
+    "@ubean/markdown": "0.4.5",
+    "@ubean/pages": "0.4.5",
+    "@ubean/preset": "0.4.5",
+    "@ubean/routes": "0.4.5",
+    "@ubean/scan": "0.4.5",
+    "@ubean/shared": "0.4.5",
+    "@ubean/vue": "0.4.5",
     "@vitejs/plugin-vue": "^6.0.8",
     "openapi-typescript": "^7.13.0",
     "pathe": "^2.0.3",