@4399ywkf/core 5.1.5 → 5.3.0

package/dist/index.js

@@ -876,7 +876,7 @@ function createMockMiddleware(mockPath, options) {
   scanMockFiles(mockPath);
   return async (_req, _res, next) => {
     if (delay > 0) {
-      await new Promise((resolve5) => setTimeout(resolve5, delay));
+      await new Promise((resolve6) => setTimeout(resolve6, delay));
     }
     next();
   };
@@ -1830,11 +1830,11 @@ var zustandPlugin = createPlugin((options = {}) => ({
     const hooks = {
       modifyRspackConfig(rspackConfig) {
         logger.info("Zustand \u5DF2\u542F\u7528");
-        const resolve5 = rspackConfig.resolve || {};
-        const alias = resolve5.alias || {};
+        const resolve6 = rspackConfig.resolve || {};
+        const alias = resolve6.alias || {};
         alias["@store"] = storePath;
-        resolve5.alias = alias;
-        rspackConfig.resolve = resolve5;
+        resolve6.alias = alias;
+        rspackConfig.resolve = resolve6;
         return rspackConfig;
       },
       generateFiles(_ctx) {
@@ -2175,7 +2175,9 @@ var defaultConfig = {
   tools: {},
   env: {
     publicEnvFile: "config/env/.env.public",
-    envDir: "config/env"
+    envDir: "config/env",
+    expose: [],
+    exposePrefixes: ["YWKF_PUBLIC_", "NEXT_PUBLIC_"]
   },
   alias: {},
   plugins: []
@@ -2743,12 +2745,13 @@ function LazyRoute({
 
 import React, { lazy, Suspense } from "react";
 import { createBrowserRouter, type RouteObject } from "react-router";
+import { RouteErrorBoundary } from "@4399ywkf/core/runtime";
+${errorImports.length > 0 ? `
+// \u540C\u6B65\u9519\u8BEF\u8FB9\u754C\u7EC4\u4EF6
+${errorImports.join("\n")}` : ""}
 
 // \u61D2\u52A0\u8F7D\u9875\u9762\u7EC4\u4EF6
 ${lazyImports.join("\n")}
-${errorImports.length > 0 ? `
-// \u9519\u8BEF\u8FB9\u754C\u7EC4\u4EF6
-${errorImports.join("\n")}` : ""}
 ${loadingImports.length > 0 ? `
 // \u52A0\u8F7D\u72B6\u6001\u7EC4\u4EF6
 ${loadingImports.join("\n")}` : ""}
@@ -2783,7 +2786,7 @@ export default routes;
       }
       if (route.errorFile) {
         errorImports.push(
-          `const ${name}Error = lazy(() => import("@/pages/${toImportPath(route.errorFile)}"));`
+          `import ${name}Error from "@/pages/${toImportPath(route.errorFile)}";`
         );
       }
       if (route.loadingFile) {
@@ -2798,13 +2801,13 @@ export default routes;
       }
     }
   }
-  emitRouteArray(routes, parentPath) {
-    const items = routes.map((r) => this.emitRouteObject(r, parentPath));
+  emitRouteArray(routes, parentPath, depth = 0) {
+    const items = routes.map((r) => this.emitRouteObject(r, parentPath, depth));
     return `[
   ${items.join(",\n  ")}
 ]`;
   }
-  emitRouteObject(route, parentPath) {
+  emitRouteObject(route, parentPath, depth) {
     const parts = [];
     const name = route.name;
     if (route.index) {
@@ -2825,11 +2828,13 @@ export default routes;
       parts.push(`element: <LazyRoute Component={${name}Page} />`);
     }
     if (route.errorFile) {
-      parts.push(`errorElement: <LazyRoute Component={${name}Error} />`);
+      parts.push(`errorElement: <RouteErrorBoundary fallback={<${name}Error />} />`);
+    } else if (depth === 0) {
+      parts.push(`errorElement: <RouteErrorBoundary />`);
     }
     if (route.children && route.children.length > 0) {
       const childParent = route.pathless ? parentPath : route.path;
-      parts.push(`children: ${this.emitRouteArray(route.children, childParent)}`);
+      parts.push(`children: ${this.emitRouteArray(route.children, childParent, depth + 1)}`);
     }
     return `{
     ${parts.join(",\n    ")}
@@ -3437,14 +3442,93 @@ var YwkfGeneratorPlugin = class {
   }
 };
 
+// src/rspack/client-env.ts
+import { existsSync as existsSync12, readFileSync as readFileSync4 } from "fs";
+import { resolve as resolve3 } from "path";
+import dotenv from "dotenv";
+var FRAMEWORK_ENV_KEYS = [
+  "APP_CNAME",
+  "APP_HOST",
+  "APP_MODE",
+  "APP_NAME",
+  "APP_PORT",
+  "DEBUG",
+  "NODE_ENV",
+  "OUTPUT_PATH",
+  "PUBLIC_PATH",
+  "YWKF_BUILD_ID",
+  "YWKF_PREFIX_CLS"
+];
+var DEFAULT_EXPOSE_PREFIXES = ["YWKF_PUBLIC_", "NEXT_PUBLIC_"];
+var SECRET_KEY_PATTERN = /TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|AUTH|ACCESS_KEY|API_KEY|SIGNING_KEY/i;
+var SECRET_VALUE_PATTERN = /^(sntry[su]_|sk-|ghp_|gho_|ghu_|ghs_|github_pat_|glpat-|xox[abprs]-|AKIA|ya29\.)/;
+function readEnvFileKeys(filePath) {
+  if (!existsSync12(filePath)) return [];
+  try {
+    return Object.keys(dotenv.parse(readFileSync4(filePath, "utf-8")));
+  } catch {
+    return [];
+  }
+}
+function collectClientEnvKeys(options) {
+  const { cwd, env = {}, mode = process.env.APP_MODE || "development" } = options;
+  const keys = new Set(FRAMEWORK_ENV_KEYS);
+  const files = [
+    env.publicEnvFile ?? "config/env/.env.public",
+    ".env.public",
+    ".env",
+    `${env.envDir ?? "config/env"}/.env.${mode}`,
+    `.env.${mode}`
+  ];
+  for (const file of files) {
+    for (const key of readEnvFileKeys(resolve3(cwd, file))) keys.add(key);
+  }
+  for (const key of env.expose ?? []) keys.add(key);
+  return keys;
+}
+function buildClientEnv(options) {
+  const { cwd, env = {}, mode, processEnv = process.env } = options;
+  const prefixes = env.exposePrefixes ?? DEFAULT_EXPOSE_PREFIXES;
+  const allowed = collectClientEnvKeys({ cwd, env, mode });
+  const result = {};
+  const dropped = [];
+  for (const [key, value] of Object.entries(processEnv)) {
+    if (value === void 0) continue;
+    const isAllowed = allowed.has(key) || prefixes.some((prefix) => key.startsWith(prefix));
+    if (!isAllowed) continue;
+    if (SECRET_KEY_PATTERN.test(key) || SECRET_VALUE_PATTERN.test(value)) {
+      dropped.push(key);
+      continue;
+    }
+    result[key] = value;
+  }
+  return { env: result, dropped };
+}
+
 // src/rspack/base.ts
 var require2 = createRequire(import.meta.url);
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var coreNodeModules = join12(__dirname, "../../node_modules");
+function resolveYwkfBuildId(appName) {
+  const releaseId = [
+    process.env.YWKF_BUILD_ID,
+    process.env.CI_COMMIT_SHA,
+    process.env.GITHUB_SHA,
+    process.env.GIT_COMMIT
+  ].find((value) => value?.trim())?.trim();
+  return `${appName}:${releaseId || Date.now().toString(36)}`;
+}
 function createBaseConfig(config, cwd, options = {}) {
   const isDev = options.isDev ?? process.env.NODE_ENV !== "production";
   const { resolveApp } = createPathResolver(cwd);
   const { appName, appCName, output, html, alias: userAlias, microFrontend, router, reactCompiler } = config;
+  const buildId = resolveYwkfBuildId(appName);
+  const { env: clientEnv, dropped: droppedEnvKeys } = buildClientEnv({ cwd, env: config.env });
+  if (droppedEnvKeys.length > 0) {
+    console.warn(
+      `[ywkf] \u4EE5\u4E0B\u73AF\u5883\u53D8\u91CF\u7591\u4F3C\u5BC6\u94A5,\u5DF2\u4ECE\u5BA2\u6237\u7AEF\u4EA7\u7269\u4E2D\u5254\u9664:${droppedEnvKeys.join(", ")}\u3002\u5982\u786E\u4E3A\u516C\u5F00\u914D\u7F6E,\u8BF7\u91CD\u547D\u540D\u6216\u8C03\u6574 env.expose\u3002`
+    );
+  }
   const ywkfOutputDir = resolveApp(".ywkf");
   const defaultAlias = {
     "@": resolveApp("src"),
@@ -3568,7 +3652,11 @@ function createBaseConfig(config, cwd, options = {}) {
         Buffer: ["buffer", "Buffer"]
       }),
       new rspack2.DefinePlugin({
-        "process.env": JSON.stringify(process.env)
+        "globalThis.__YWKF_BUILD_ID__": JSON.stringify(buildId),
+        // 只内联白名单内的公开配置。整包 process.env 会把构建机环境(CI 凭据、内网地址)
+        // 写进公网可下载的产物,见 client-env.ts。外层括号不可省:该值以 `{` 开头,
+        // `() => process.env.X` 会被替换成 `() => {…}` 而当成函数块体,导致整条 chunk 语法失败。
+        "process.env": `(${JSON.stringify(clientEnv)})`
       }),
       new rspack2.HtmlRspackPlugin({
         template: resolveApp(html.template ?? "public/index.html"),
@@ -4086,28 +4174,28 @@ function createRspackConfig(config, cwd, options = {}) {
 }
 
 // src/cli/env.ts
-import { existsSync as existsSync12, readFileSync as readFileSync4 } from "fs";
-import { resolve as resolve3 } from "path";
-import dotenv from "dotenv";
+import { existsSync as existsSync13, readFileSync as readFileSync5 } from "fs";
+import { resolve as resolve4 } from "path";
+import dotenv2 from "dotenv";
 function preloadEnv(cwd, mode, nodeEnv) {
   process.env.NODE_ENV = nodeEnv;
   process.env.APP_MODE = mode;
   const defaultPaths = [
-    resolve3(cwd, "config/env/.env.public"),
-    resolve3(cwd, ".env.public"),
-    resolve3(cwd, ".env")
+    resolve4(cwd, "config/env/.env.public"),
+    resolve4(cwd, ".env.public"),
+    resolve4(cwd, ".env")
   ];
   for (const envPath of defaultPaths) {
-    if (existsSync12(envPath)) {
-      dotenv.config({ path: envPath });
+    if (existsSync13(envPath)) {
+      dotenv2.config({ path: envPath });
       break;
     }
   }
-  const modeEnvPaths = [resolve3(cwd, `config/env/.env.${mode}`), resolve3(cwd, `.env.${mode}`)];
+  const modeEnvPaths = [resolve4(cwd, `config/env/.env.${mode}`), resolve4(cwd, `.env.${mode}`)];
   for (const envPath of modeEnvPaths) {
-    if (existsSync12(envPath)) {
-      const envContent = readFileSync4(envPath, "utf-8");
-      const parsed = dotenv.parse(envContent);
+    if (existsSync13(envPath)) {
+      const envContent = readFileSync5(envPath, "utf-8");
+      const parsed = dotenv2.parse(envContent);
       for (const key in parsed) {
         process.env[key] = parsed[key];
       }
@@ -4119,14 +4207,14 @@ function preloadEnv(cwd, mode, nodeEnv) {
 }
 function loadEnv(config, cwd, mode, nodeEnv) {
   const { env } = config;
-  const publicEnvPath = resolve3(cwd, env.publicEnvFile ?? "config/env/.env.public");
-  if (existsSync12(publicEnvPath)) {
-    dotenv.config({ path: publicEnvPath });
-  }
-  const modeEnvPath = resolve3(cwd, env.envDir ?? "config/env", `.env.${mode}`);
-  if (existsSync12(modeEnvPath)) {
-    const envContent = readFileSync4(modeEnvPath, "utf-8");
-    const parsed = dotenv.parse(envContent);
+  const publicEnvPath = resolve4(cwd, env.publicEnvFile ?? "config/env/.env.public");
+  if (existsSync13(publicEnvPath)) {
+    dotenv2.config({ path: publicEnvPath });
+  }
+  const modeEnvPath = resolve4(cwd, env.envDir ?? "config/env", `.env.${mode}`);
+  if (existsSync13(modeEnvPath)) {
+    const envContent = readFileSync5(modeEnvPath, "utf-8");
+    const parsed = dotenv2.parse(envContent);
     for (const key in parsed) {
       process.env[key] = parsed[key];
     }
@@ -4404,7 +4492,7 @@ async function build(options = {}) {
     rspackConfig.stats = "none";
     rspackConfig.infrastructureLogging = { level: "none" };
     const compiler = rspack4(rspackConfig);
-    const stats = await new Promise((resolve5, reject) => {
+    const stats = await new Promise((resolve6, reject) => {
       compiler.run((err, stats2) => {
         if (err) {
           reject(err);
@@ -4414,13 +4502,13 @@ async function build(options = {}) {
           reject(new Error("Build failed: no stats available"));
           return;
         }
-        resolve5(stats2);
+        resolve6(stats2);
       });
     });
-    await new Promise((resolve5, reject) => {
+    await new Promise((resolve6, reject) => {
       compiler.close((err) => {
         if (err) reject(err);
-        else resolve5();
+        else resolve6();
       });
     });
     const hasErrors = stats.hasErrors();
@@ -4462,7 +4550,7 @@ var PortInUseError = class extends Error {
   }
 };
 function ensurePortAvailable(port, host) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     const server = net.createServer();
     server.once("error", (err) => {
       if (err.code === "EADDRINUSE") {
@@ -4472,7 +4560,7 @@ function ensurePortAvailable(port, host) {
       }
     });
     server.once("listening", () => {
-      server.close(() => resolve5());
+      server.close(() => resolve6());
     });
     server.listen(port, host);
   });
@@ -4520,8 +4608,8 @@ function parseWindowsNetstatPid(stdout, port) {
 }
 
 // src/cli/restart-watcher.ts
-import { existsSync as existsSync13, watch as watch2 } from "fs";
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync14, watch as watch2 } from "fs";
+import { resolve as resolve5 } from "path";
 function isTriggerFile(filename, mode) {
   if (!filename) return false;
   if (CONFIG_FILES.includes(filename)) return true;
@@ -4551,8 +4639,8 @@ function watchForRestart(opts) {
     }, debounceMs);
   };
   watchers.push(watch2(cwd, { recursive: false }, (_event, filename) => trigger(filename)));
-  const envDir = resolve4(cwd, "config/env");
-  if (existsSync13(envDir)) {
+  const envDir = resolve5(cwd, "config/env");
+  if (existsSync14(envDir)) {
     watchers.push(watch2(envDir, { recursive: false }, (_event, filename) => trigger(filename)));
   }
   return {
@@ -4659,10 +4747,10 @@ async function startDevServer(cwd, config) {
     if (closed) return;
     closed = true;
     await server.stop();
-    await new Promise((resolve5, reject) => {
+    await new Promise((resolve6, reject) => {
       compiler.close((err) => {
         if (err) reject(err);
-        else resolve5();
+        else resolve6();
       });
     });
   };
@@ -4757,7 +4845,7 @@ async function dev(options = {}) {
 }
 
 // src/router/plugin.ts
-import { existsSync as existsSync14, watch as watch3 } from "fs";
+import { existsSync as existsSync15, watch as watch3 } from "fs";
 import { join as join14 } from "path";
 var ConventionalRoutePlugin = class {
   options;
@@ -4813,7 +4901,7 @@ var ConventionalRoutePlugin = class {
    * 监听页面目录变化
    */
   watchPages(compiler) {
-    if (!existsSync14(this.options.pagesDir)) {
+    if (!existsSync15(this.options.pagesDir)) {
       return;
     }
     this.isWatching = true;
@@ -4840,6 +4928,370 @@ var ConventionalRoutePlugin = class {
   }
 };
 
+// src/runtime/chunk-recovery.ts
+var DEFAULT_CHUNK_RECOVERY_COOLDOWN_MS = 3e4;
+var CHUNK_RECOVERY_STORAGE_KEY = "@4399ywkf/core:chunk-recovery-attempt";
+var CHUNK_RECOVERY_CACHE_BUST_PARAM = "__ywkf_chunk_retry";
+var CHUNK_RECOVERY_ACTIVE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "@4399ywkf/core/chunk-recovery-active"
+);
+var CHUNK_RECOVERY_REGISTRY_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "@4399ywkf/core/chunk-recovery-registry"
+);
+var CHUNK_LOAD_ERROR_PATTERNS = [
+  /\bChunkLoadError\b/i,
+  /\bLoading (?:CSS )?chunk\s+\S+\s+failed\b/i,
+  /\bFailed to fetch dynamically imported module\b/i,
+  /\bImporting a module script failed\b/i,
+  /\berror loading dynamically imported module\b/i,
+  /\bUnable to preload CSS for\b/i,
+  /\bFailed to load module script\b/i
+];
+function getErrorLikeValue(error, key) {
+  if ((typeof error !== "object" || error === null) && typeof error !== "function") {
+    return void 0;
+  }
+  try {
+    return error[key];
+  } catch {
+    return void 0;
+  }
+}
+function matchesChunkLoadError(error, depth) {
+  if (depth > 3) {
+    return false;
+  }
+  if (typeof error === "string") {
+    return CHUNK_LOAD_ERROR_PATTERNS.some((pattern) => pattern.test(error));
+  }
+  const name = getErrorLikeValue(error, "name");
+  const message = getErrorLikeValue(error, "message");
+  const code = getErrorLikeValue(error, "code");
+  const signature = [name, message].filter((value) => typeof value === "string").join(": ");
+  if (code === "CSS_CHUNK_LOAD_FAILED" || CHUNK_LOAD_ERROR_PATTERNS.some((pattern) => pattern.test(signature))) {
+    return true;
+  }
+  const cause = getErrorLikeValue(error, "cause");
+  return cause !== void 0 && cause !== error && matchesChunkLoadError(cause, depth + 1);
+}
+function isChunkLoadError(error) {
+  return matchesChunkLoadError(error, 0);
+}
+function hashRecoveryIdentity(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+function getFrameworkBuildId() {
+  const buildId = globalThis.__YWKF_BUILD_ID__;
+  return typeof buildId === "string" ? buildId.trim() : "";
+}
+function resolveRecoveryId(error, config) {
+  const configuredBuildId = typeof config === "object" && typeof config.buildId === "string" ? config.buildId.trim() : "";
+  const buildId = configuredBuildId || getFrameworkBuildId();
+  if (buildId) {
+    return `build-${hashRecoveryIdentity(buildId)}`;
+  }
+  const request = getErrorLikeValue(error, "request");
+  const name = getErrorLikeValue(error, "name");
+  const message = getErrorLikeValue(error, "message");
+  const signature = [request, name, message].filter((value) => typeof value === "string").join(": ");
+  return `error-${hashRecoveryIdentity(signature || String(error))}`;
+}
+function toError(error, fallbackMessage = "Chunk loading failed") {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+  const message = getErrorLikeValue(error, "message");
+  const name = getErrorLikeValue(error, "name");
+  const normalizedError = new Error(typeof message === "string" ? message : fallbackMessage);
+  if (typeof name === "string") {
+    normalizedError.name = name;
+  }
+  return normalizedError;
+}
+function normalizeCooldownMs(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1e3) {
+    return DEFAULT_CHUNK_RECOVERY_COOLDOWN_MS;
+  }
+  return value;
+}
+function resolveChunkRecoveryPolicy(config, context) {
+  const options = typeof config === "object" ? config : void 0;
+  const configuredEnabled = typeof config === "boolean" ? config : options?.enabled;
+  const enabledForEnvironment = configuredEnabled ?? context.isProduction;
+  if (!enabledForEnvironment) {
+    return {
+      enabled: false,
+      disabledReason: configuredEnabled === false ? "configuration" : "environment",
+      cooldownMs: normalizeCooldownMs(options?.cooldownMs),
+      globalHandlers: options?.globalHandlers === true
+    };
+  }
+  if (context.isMicroApp && options?.allowInMicroApp !== true) {
+    return {
+      enabled: false,
+      disabledReason: "micro-app",
+      cooldownMs: normalizeCooldownMs(options?.cooldownMs),
+      globalHandlers: options?.globalHandlers === true
+    };
+  }
+  return {
+    enabled: true,
+    cooldownMs: normalizeCooldownMs(options?.cooldownMs),
+    globalHandlers: options?.globalHandlers === true
+  };
+}
+function parseStoredChunkRecoveryState(value) {
+  if (value === null) {
+    return { attempts: [] };
+  }
+  const parsed = JSON.parse(value);
+  if (!Array.isArray(parsed.attempts)) {
+    throw new Error("Invalid chunk recovery state");
+  }
+  const attempts = parsed.attempts.map((attempt) => {
+    if (typeof attempt !== "object" || attempt === null || typeof attempt.recoveryId !== "string" || typeof attempt.attemptedAt !== "number" || !Number.isFinite(attempt.attemptedAt)) {
+      throw new Error("Invalid chunk recovery attempt");
+    }
+    return attempt;
+  });
+  if (parsed.lastAttemptAt !== void 0 && (typeof parsed.lastAttemptAt !== "number" || !Number.isFinite(parsed.lastAttemptAt))) {
+    throw new Error("Invalid chunk recovery timestamp");
+  }
+  return { attempts, lastAttemptAt: parsed.lastAttemptAt };
+}
+function claimChunkRecoveryAttempt(storage, options) {
+  const {
+    cooldownMs = DEFAULT_CHUNK_RECOVERY_COOLDOWN_MS,
+    now,
+    recoveryId,
+    storageKey = CHUNK_RECOVERY_STORAGE_KEY
+  } = options;
+  let state;
+  try {
+    state = parseStoredChunkRecoveryState(storage.getItem(storageKey));
+  } catch {
+    return { claimed: false, reason: "storage-unavailable" };
+  }
+  const existingAttempt = state.attempts.find((attempt) => attempt.recoveryId === recoveryId);
+  if (existingAttempt) {
+    return {
+      claimed: false,
+      reason: "already-attempted",
+      attemptedAt: existingAttempt.attemptedAt
+    };
+  }
+  const inCooldown = state.lastAttemptAt !== void 0 && (state.lastAttemptAt > now || now - state.lastAttemptAt < cooldownMs);
+  if (inCooldown) {
+    return { claimed: false, reason: "cooldown", attemptedAt: state.lastAttemptAt };
+  }
+  try {
+    storage.setItem(
+      storageKey,
+      JSON.stringify({
+        attempts: [...state.attempts, { attemptedAt: now, recoveryId }],
+        lastAttemptAt: now
+      })
+    );
+  } catch {
+    return { claimed: false, reason: "storage-unavailable" };
+  }
+  return { claimed: true, attemptedAt: now };
+}
+function isMicroAppRuntime() {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  const runtimeWindow = window;
+  return Boolean(runtimeWindow.__POWERED_BY_QIANKUN__ || runtimeWindow.__GARFISH__);
+}
+function getSessionStorage() {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function invokeSafely(callback, label) {
+  if (!callback) {
+    return;
+  }
+  try {
+    callback();
+  } catch (error) {
+    console.error(`[ywkf] ${label} \u6267\u884C\u5931\u8D25:`, error);
+  }
+}
+function schedulePageReplace(timestamp) {
+  setTimeout(() => {
+    try {
+      const reloadUrl = new URL(window.location.href);
+      reloadUrl.searchParams.set(CHUNK_RECOVERY_CACHE_BUST_PARAM, String(timestamp));
+      window.location.replace(reloadUrl.toString());
+    } catch (error) {
+      console.error("[ywkf] chunk \u6062\u590D\u5237\u65B0\u5931\u8D25:", error);
+    }
+  }, 0);
+}
+function clearChunkRecoveryCacheBustParam() {
+  if (typeof window === "undefined") {
+    return;
+  }
+  try {
+    const currentUrl = new URL(window.location.href);
+    if (!currentUrl.searchParams.has(CHUNK_RECOVERY_CACHE_BUST_PARAM)) {
+      return;
+    }
+    currentUrl.searchParams.delete(CHUNK_RECOVERY_CACHE_BUST_PARAM);
+    window.history.replaceState(window.history.state, "", currentUrl.toString());
+  } catch (error) {
+    console.error("[ywkf] \u6E05\u7406 chunk \u6062\u590D\u53C2\u6570\u5931\u8D25:", error);
+  }
+}
+function handleChunkLoadErrorInternal(reason, options, trustedChunkEvent) {
+  if (!trustedChunkEvent && !isChunkLoadError(reason)) {
+    return null;
+  }
+  const error = toError(reason);
+  const timestamp = Date.now();
+  const recoveryId = resolveRecoveryId(reason, options.config);
+  const isMicroApp = options.isMicroApp ?? isMicroAppRuntime();
+  const policy = resolveChunkRecoveryPolicy(options.config, {
+    isProduction: process.env.NODE_ENV === "production",
+    isMicroApp
+  });
+  let outcome;
+  if (!policy.enabled) {
+    outcome = policy.disabledReason === "micro-app" ? "reload-skipped-micro-app" : "reload-skipped-disabled";
+  } else {
+    const storage = getSessionStorage();
+    const claim = storage ? claimChunkRecoveryAttempt(storage, {
+      cooldownMs: policy.cooldownMs,
+      now: timestamp,
+      recoveryId
+    }) : { claimed: false, reason: "storage-unavailable" };
+    if (claim.claimed) {
+      outcome = "reload-scheduled";
+    } else if (claim.reason === "already-attempted") {
+      outcome = "reload-skipped-already-attempted";
+    } else if (claim.reason === "cooldown") {
+      outcome = "reload-skipped-cooldown";
+    } else {
+      outcome = "reload-skipped-storage-unavailable";
+    }
+  }
+  const event = {
+    error,
+    source: options.source,
+    outcome,
+    timestamp,
+    cooldownMs: policy.cooldownMs,
+    recoveryId
+  };
+  invokeSafely(() => options.onError?.(error), "onError");
+  invokeSafely(() => options.onRecoveryEvent?.(event), "onRecoveryEvent");
+  if (outcome === "reload-scheduled") {
+    schedulePageReplace(timestamp);
+  }
+  return event;
+}
+function handleChunkLoadError(reason, options) {
+  return handleChunkLoadErrorInternal(reason, options, false);
+}
+function getLatestSubscriber(registry) {
+  let latest;
+  for (const subscriber of registry.subscribers.values()) {
+    latest = subscriber;
+  }
+  return latest;
+}
+function createGlobalChunkRecoveryRegistry() {
+  const registry = {
+    subscribers: /* @__PURE__ */ new Map()
+  };
+  registry.handleUnhandledRejection = (event) => {
+    const subscriber = getLatestSubscriber(registry);
+    if (!subscriber) return;
+    const recoveryEvent = handleChunkLoadError(event.reason, {
+      ...subscriber,
+      source: "unhandled-rejection"
+    });
+    if (recoveryEvent?.outcome === "reload-scheduled") {
+      event.preventDefault();
+    }
+  };
+  registry.handleVitePreloadError = (event) => {
+    const subscriber = getLatestSubscriber(registry);
+    if (!subscriber) return;
+    const payload = event.payload;
+    const recoveryEvent = handleChunkLoadErrorInternal(
+      payload,
+      {
+        ...subscriber,
+        source: "vite-preload-error"
+      },
+      true
+    );
+    if (recoveryEvent?.outcome === "reload-scheduled") {
+      event.preventDefault();
+    }
+  };
+  return registry;
+}
+function installGlobalChunkRecoveryHandlers(options) {
+  if (typeof window === "undefined") {
+    return () => {
+    };
+  }
+  const isMicroApp = options.isMicroApp ?? isMicroAppRuntime();
+  const policy = resolveChunkRecoveryPolicy(options.config, {
+    isProduction: process.env.NODE_ENV === "production",
+    isMicroApp
+  });
+  if (!policy.enabled || !policy.globalHandlers) {
+    return () => {
+    };
+  }
+  const runtimeWindow = window;
+  let registry = runtimeWindow[CHUNK_RECOVERY_REGISTRY_SYMBOL];
+  if (!registry && runtimeWindow[CHUNK_RECOVERY_ACTIVE_SYMBOL] === true) {
+    return () => {
+    };
+  }
+  if (!registry) {
+    registry = createGlobalChunkRecoveryRegistry();
+    runtimeWindow[CHUNK_RECOVERY_REGISTRY_SYMBOL] = registry;
+    runtimeWindow[CHUNK_RECOVERY_ACTIVE_SYMBOL] = true;
+    window.addEventListener("unhandledrejection", registry.handleUnhandledRejection);
+    window.addEventListener("vite:preloadError", registry.handleVitePreloadError);
+  }
+  const subscriberId = /* @__PURE__ */ Symbol("chunk-recovery-subscriber");
+  registry.subscribers.set(subscriberId, { ...options, isMicroApp });
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    registry.subscribers.delete(subscriberId);
+    if (registry.subscribers.size > 0) return;
+    window.removeEventListener("unhandledrejection", registry.handleUnhandledRejection);
+    window.removeEventListener("vite:preloadError", registry.handleVitePreloadError);
+    if (runtimeWindow[CHUNK_RECOVERY_REGISTRY_SYMBOL] === registry) {
+      delete runtimeWindow[CHUNK_RECOVERY_REGISTRY_SYMBOL];
+      delete runtimeWindow[CHUNK_RECOVERY_ACTIVE_SYMBOL];
+    }
+  };
+}
+
 // src/runtime/bootstrap.tsx
 import { createRoot } from "react-dom/client";
 
@@ -4891,8 +5343,23 @@ function useIsDev() {
 }
 
 // src/runtime/error-boundary.tsx
-import { Component } from "react";
+import {
+  Component,
+  createContext as createContext2,
+  useContext as useContext2,
+  useEffect,
+  useMemo,
+  useRef
+} from "react";
+import { isRouteErrorResponse, useRouteError } from "react-router";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+var ChunkRecoveryRuntimeContext = createContext2(null);
+function ChunkRecoveryRuntimeProvider({
+  children,
+  ...value
+}) {
+  return /* @__PURE__ */ jsx2(ChunkRecoveryRuntimeContext.Provider, { value, children });
+}
 var ErrorBoundary = class extends Component {
   constructor(props) {
     super(props);
@@ -4902,15 +5369,31 @@ var ErrorBoundary = class extends Component {
     return { hasError: true, error };
   }
   componentDidCatch(error, errorInfo) {
-    console.error("[ErrorBoundary] Caught error:", error, errorInfo);
-    this.props.onError?.(error, errorInfo);
+    const reportError = () => {
+      console.error("[ErrorBoundary] Caught error:", error, errorInfo);
+      this.props.onError?.(error, errorInfo);
+    };
+    if (this.props.chunkRecovery === void 0) {
+      reportError();
+      return;
+    }
+    const recoveryEvent = handleChunkLoadError(error, {
+      source: "error-boundary",
+      config: this.props.chunkRecovery,
+      isMicroApp: this.props.isMicroApp,
+      onError: reportError,
+      onRecoveryEvent: this.props.onRecoveryEvent
+    });
+    if (!recoveryEvent) {
+      reportError();
+    }
   }
   reset = () => {
     this.setState({ hasError: false, error: null });
   };
   render() {
     const { hasError, error } = this.state;
-    const { children, fallback } = this.props;
+    const { children, chunkRecovery, fallback, isMicroApp } = this.props;
     if (hasError && error) {
       if (typeof fallback === "function") {
         return fallback(error, this.reset);
@@ -4918,12 +5401,86 @@ var ErrorBoundary = class extends Component {
       if (fallback) {
         return fallback;
       }
-      return /* @__PURE__ */ jsx2(DefaultErrorFallback, { error, onReset: this.reset });
+      const resolvedIsMicroApp = isMicroApp ?? isMicroAppRuntime();
+      const chunkRecoveryEnabled = chunkRecovery !== void 0 && resolveChunkRecoveryPolicy(chunkRecovery, {
+        isProduction: process.env.NODE_ENV === "production",
+        isMicroApp: resolvedIsMicroApp
+      }).enabled;
+      const canReloadPage = !resolvedIsMicroApp || typeof chunkRecovery === "object" && chunkRecovery.allowInMicroApp === true;
+      return /* @__PURE__ */ jsx2(
+        DefaultErrorFallback,
+        {
+          canReloadPage,
+          error,
+          isChunkError: chunkRecoveryEnabled && isChunkLoadError(error),
+          onReset: this.reset
+        }
+      );
     }
     return children;
   }
 };
-function DefaultErrorFallback({ error, onReset }) {
+var UNHANDLED_ROUTE_ERROR = /* @__PURE__ */ Symbol("unhandled-route-error");
+function normalizeRouteError(reason) {
+  if (reason instanceof Error) return reason;
+  if (typeof reason === "string") return new Error(reason);
+  if (isRouteErrorResponse(reason)) {
+    const message = [reason.status, reason.statusText].filter(Boolean).join(" ");
+    const error = new Error(message || "Route request failed");
+    error.name = "RouteErrorResponse";
+    return error;
+  }
+  return new Error("Route rendering failed");
+}
+function RouteErrorBoundary({ fallback }) {
+  const reason = useRouteError();
+  const error = useMemo(() => normalizeRouteError(reason), [reason]);
+  const recoveryRuntime = useContext2(ChunkRecoveryRuntimeContext);
+  const handledReasonRef = useRef(UNHANDLED_ROUTE_ERROR);
+  useEffect(() => {
+    if (Object.is(handledReasonRef.current, reason)) return;
+    handledReasonRef.current = reason;
+    const reportError = () => {
+      console.error("[RouteErrorBoundary] Caught error:", error);
+      recoveryRuntime?.onError?.(error);
+    };
+    if (!recoveryRuntime) {
+      reportError();
+      return;
+    }
+    const recoveryEvent = handleChunkLoadError(reason, {
+      source: "route-error-boundary",
+      config: recoveryRuntime.chunkRecovery,
+      isMicroApp: recoveryRuntime.isMicroApp,
+      onError: reportError,
+      onRecoveryEvent: recoveryRuntime.onRecoveryEvent
+    });
+    if (!recoveryEvent) reportError();
+  }, [error, reason, recoveryRuntime]);
+  if (typeof fallback === "function") return fallback(error);
+  if (fallback) return fallback;
+  const chunkRecovery = recoveryRuntime?.chunkRecovery;
+  const resolvedIsMicroApp = recoveryRuntime?.isMicroApp ?? isMicroAppRuntime();
+  const chunkRecoveryEnabled = chunkRecovery !== void 0 && resolveChunkRecoveryPolicy(chunkRecovery, {
+    isProduction: process.env.NODE_ENV === "production",
+    isMicroApp: resolvedIsMicroApp
+  }).enabled;
+  const canReloadPage = !resolvedIsMicroApp || typeof chunkRecovery === "object" && chunkRecovery.allowInMicroApp === true;
+  return /* @__PURE__ */ jsx2(
+    DefaultErrorFallback,
+    {
+      canReloadPage,
+      error,
+      isChunkError: chunkRecoveryEnabled && isChunkLoadError(reason)
+    }
+  );
+}
+function DefaultErrorFallback({
+  canReloadPage,
+  error,
+  isChunkError,
+  onReset
+}) {
   const isDev = process.env.NODE_ENV === "development";
   return /* @__PURE__ */ jsx2(
     "div",
@@ -4949,7 +5506,7 @@ function DefaultErrorFallback({ error, onReset }) {
           },
           children: [
             /* @__PURE__ */ jsx2("h1", { style: { color: "#ff4d4f", marginBottom: 16 }, children: "\u9875\u9762\u51FA\u9519\u4E86" }),
-            /* @__PURE__ */ jsx2("p", { style: { color: "#666", marginBottom: 16 }, children: "\u62B1\u6B49\uFF0C\u9875\u9762\u9047\u5230\u4E86\u4E00\u4E9B\u95EE\u9898\u3002\u8BF7\u5C1D\u8BD5\u5237\u65B0\u9875\u9762\u6216\u8054\u7CFB\u7BA1\u7406\u5458\u3002" }),
+            /* @__PURE__ */ jsx2("p", { style: { color: "#666", marginBottom: 16 }, children: canReloadPage ? "\u62B1\u6B49\uFF0C\u9875\u9762\u9047\u5230\u4E86\u4E00\u4E9B\u95EE\u9898\u3002\u8BF7\u5C1D\u8BD5\u5237\u65B0\u9875\u9762\u6216\u8054\u7CFB\u7BA1\u7406\u5458\u3002" : "\u62B1\u6B49\uFF0C\u9875\u9762\u9047\u5230\u4E86\u4E00\u4E9B\u95EE\u9898\u3002\u8BF7\u5173\u95ED\u5F53\u524D\u9875\u9762\u540E\u91CD\u65B0\u6253\u5F00\uFF0C\u6216\u8054\u7CFB\u7BA1\u7406\u5458\u3002" }),
             isDev && /* @__PURE__ */ jsxs(
               "details",
               {
@@ -4983,8 +5540,8 @@ function DefaultErrorFallback({ error, onReset }) {
                 ]
               }
             ),
-            /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: 8 }, children: [
-              /* @__PURE__ */ jsx2(
+            (canReloadPage || !isChunkError && onReset) && /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: 8 }, children: [
+              !isChunkError && onReset && /* @__PURE__ */ jsx2(
                 "button",
                 {
                   onClick: onReset,
@@ -4999,7 +5556,7 @@ function DefaultErrorFallback({ error, onReset }) {
                   children: "\u91CD\u8BD5"
                 }
               ),
-              /* @__PURE__ */ jsx2(
+              canReloadPage && /* @__PURE__ */ jsx2(
                 "button",
                 {
                   onClick: () => window.location.reload(),
@@ -5048,7 +5605,7 @@ function composeProviders(providers) {
     }, children);
   };
 }
-function RootProvider({ config, children }) {
+function RootProvider({ config, children, isMicroApp }) {
   const {
     appName = "app",
     router,
@@ -5056,7 +5613,8 @@ function RootProvider({ config, children }) {
     strictMode = true,
     antd = { enabled: true },
     providers = [],
-    lifecycle
+    lifecycle,
+    chunkRecovery
   } = config;
   const appContextValue = {
     appName,
@@ -5087,8 +5645,30 @@ function RootProvider({ config, children }) {
     ...providers.map((p) => ({ ...p, order: p.order ?? 50 }))
   ];
   const ComposedProviders = composeProviders(allProviders);
+  const rootChunkRecovery = chunkRecovery ?? {
+    enabled: process.env.NODE_ENV === "production"
+  };
+  const resolvedIsMicroApp = isMicroApp ?? isMicroAppRuntime();
   const content = router ? /* @__PURE__ */ jsx3(Suspense, { fallback: /* @__PURE__ */ jsx3(DefaultLoading, {}), children: /* @__PURE__ */ jsx3(RouterProvider, { router }) }) : children;
-  const app = /* @__PURE__ */ jsx3(ErrorBoundary, { onError: lifecycle?.onError, children: /* @__PURE__ */ jsx3(ComposedProviders, { children: content }) });
+  const app = /* @__PURE__ */ jsx3(
+    ErrorBoundary,
+    {
+      chunkRecovery: rootChunkRecovery,
+      isMicroApp: resolvedIsMicroApp,
+      onError: lifecycle?.onError,
+      onRecoveryEvent: lifecycle?.onRecoveryEvent,
+      children: /* @__PURE__ */ jsx3(
+        ChunkRecoveryRuntimeProvider,
+        {
+          chunkRecovery: rootChunkRecovery,
+          isMicroApp: resolvedIsMicroApp,
+          onError: lifecycle?.onError,
+          onRecoveryEvent: lifecycle?.onRecoveryEvent,
+          children: /* @__PURE__ */ jsx3(ComposedProviders, { children: content })
+        }
+      )
+    }
+  );
   if (strictMode) {
     return /* @__PURE__ */ jsx3(StrictMode, { children: app });
   }
@@ -5105,6 +5685,7 @@ function createProvider(component, props, order) {
 // src/runtime/bootstrap.tsx
 import { jsx as jsx4 } from "react/jsx-runtime";
 var root = null;
+var disposeChunkRecoveryHandlers = null;
 async function resolveAppConfig(config) {
   if (config.router || !config.conventionalRoutes) {
     return config;
@@ -5127,6 +5708,10 @@ async function resolveAppConfig(config) {
 }
 async function bootstrap(config) {
   const { rootId = "root", lifecycle } = config;
+  const isMicroApp = isMicroAppEnv();
+  if (!isMicroApp) {
+    clearChunkRecoveryCacheBustParam();
+  }
   const resolvedConfig = await resolveAppConfig(config);
   if (lifecycle?.onBeforeMount) {
     await lifecycle.onBeforeMount();
@@ -5135,8 +5720,22 @@ async function bootstrap(config) {
   if (!rootElement) {
     throw new Error(`\u627E\u4E0D\u5230\u6839\u5143\u7D20 #${rootId}`);
   }
-  root = createRoot(rootElement);
-  root.render(/* @__PURE__ */ jsx4(RootProvider, { config: resolvedConfig }));
+  disposeChunkRecoveryHandlers?.();
+  const nextDisposeChunkRecoveryHandlers = installGlobalChunkRecoveryHandlers({
+    config: resolvedConfig.chunkRecovery,
+    isMicroApp,
+    onError: (error) => resolvedConfig.lifecycle?.onError?.(error),
+    onRecoveryEvent: resolvedConfig.lifecycle?.onRecoveryEvent
+  });
+  try {
+    root = createRoot(rootElement);
+    root.render(/* @__PURE__ */ jsx4(RootProvider, { config: resolvedConfig, isMicroApp }));
+    disposeChunkRecoveryHandlers = nextDisposeChunkRecoveryHandlers;
+  } catch (error) {
+    nextDisposeChunkRecoveryHandlers();
+    root = null;
+    throw error;
+  }
   if (lifecycle?.onMounted) {
     setTimeout(() => {
       lifecycle.onMounted?.();
@@ -5149,6 +5748,8 @@ async function bootstrap(config) {
   }
 }
 function unmount() {
+  disposeChunkRecoveryHandlers?.();
+  disposeChunkRecoveryHandlers = null;
   if (root) {
     root.unmount();
     root = null;
@@ -5156,6 +5757,7 @@ function unmount() {
 }
 function createMicroApp(getConfig) {
   let microRoot = null;
+  let disposeMicroChunkRecoveryHandlers = null;
   return {
     /**
      * 微前端 bootstrap 生命周期
@@ -5179,8 +5781,22 @@ function createMicroApp(getConfig) {
       if (resolvedConfig.lifecycle?.onBeforeMount) {
         await resolvedConfig.lifecycle.onBeforeMount();
       }
-      microRoot = createRoot(rootElement);
-      microRoot.render(/* @__PURE__ */ jsx4(RootProvider, { config: resolvedConfig }));
+      disposeMicroChunkRecoveryHandlers?.();
+      const nextDisposeMicroChunkRecoveryHandlers = installGlobalChunkRecoveryHandlers({
+        config: resolvedConfig.chunkRecovery,
+        isMicroApp: true,
+        onError: (error) => resolvedConfig.lifecycle?.onError?.(error),
+        onRecoveryEvent: resolvedConfig.lifecycle?.onRecoveryEvent
+      });
+      try {
+        microRoot = createRoot(rootElement);
+        microRoot.render(/* @__PURE__ */ jsx4(RootProvider, { config: resolvedConfig, isMicroApp: true }));
+        disposeMicroChunkRecoveryHandlers = nextDisposeMicroChunkRecoveryHandlers;
+      } catch (error) {
+        nextDisposeMicroChunkRecoveryHandlers();
+        microRoot = null;
+        throw error;
+      }
       if (resolvedConfig.lifecycle?.onMounted) {
         setTimeout(() => {
           resolvedConfig.lifecycle?.onMounted?.();
@@ -5200,6 +5816,8 @@ function createMicroApp(getConfig) {
         microRoot.unmount();
         microRoot = null;
       }
+      disposeMicroChunkRecoveryHandlers?.();
+      disposeMicroChunkRecoveryHandlers = null;
     },
     /**
      * 微前端 update 生命周期（可选）
@@ -5227,11 +5845,16 @@ function getMicroAppPublicPath() {
 export {
   AppContext,
   AppContextProvider,
+  CHUNK_RECOVERY_ACTIVE_SYMBOL,
+  CHUNK_RECOVERY_CACHE_BUST_PARAM,
+  CHUNK_RECOVERY_STORAGE_KEY,
   ConventionalRouteGenerator,
   ConventionalRoutePlugin,
+  DEFAULT_CHUNK_RECOVERY_COOLDOWN_MS,
   ErrorBoundary,
   PluginManager,
   RootProvider,
+  RouteErrorBoundary,
   YwkfGenerator,
   YwkfGeneratorPlugin,
   analyticsPlugin,
@@ -5239,6 +5862,8 @@ export {
   bootstrap,
   browserCheckPlugin,
   build,
+  claimChunkRecoveryAttempt,
+  clearChunkRecoveryCacheBustParam,
   createBaseConfig,
   createDevConfig,
   createMicroApp,
@@ -5254,10 +5879,15 @@ export {
   generateConventionalRoutes,
   getDefaultBiomeConfig,
   getMicroAppPublicPath,
+  handleChunkLoadError,
   i18nPlugin,
+  installGlobalChunkRecoveryHandlers,
+  isChunkLoadError,
   isMicroAppEnv,
+  isMicroAppRuntime,
   mockPlugin,
   reactQueryPlugin,
+  resolveChunkRecoveryPolicy,
   tailwindPlugin,
   themePlugin,
   unmount,