generator-mico-cli 0.2.30 → 0.2.32

package/generators/h5-react/templates/scripts/gateway.ts

@@ -0,0 +1,241 @@
+/**
+ * 本地开发网关脚本：读取根目录 `page.config.ts`，为每个 `apps/<key>` 分配端口并启动 `pnpm dev`，
+ * 再启动统一 HTTP/WebSocket 代理（默认从 3000 起占端口），通过路径前缀将流量转发到对应子应用。
+ */
+import http from 'http';
+import path from 'path';
+import fs from 'fs';
+import { spawn, type ChildProcessWithoutNullStreams } from 'child_process';
+import httpProxy from 'http-proxy';
+import portfinder from 'portfinder';
+import chalk from 'chalk';
+
+/**
+ * 仓库根目录的 `page.config.ts`：键名为子应用目录名（对应 `apps/<key>`）。
+ */
+import pageConfig from '../page.config.ts';
+
+/** 单个子应用在网关中的运行时元数据（端口、路径前缀等）。 */
+interface PageConfig {
+  key: string;
+  name: string;
+  fullPath: string;
+  prefixPath: string;
+  port: number;
+}
+
+/**
+ * 遍历 `page.config.ts` 的每个键，在 `apps/<key>` 下读取 `package.json`，
+ * 并为每个子应用从 4000 起顺序分配可用端口，生成 `PageConfig` 列表。
+ */
+async function formatPageConfig(): Promise<PageConfig[]> {
+  const pageConfigs: PageConfig[] = [];
+  const appPath = path.join(process.cwd(), 'apps');
+  let basePort = 4000;
+  for (const [key, value] of Object.entries(pageConfig)) {
+    const appPackagePath = path.join(appPath, key, 'package.json');
+    try {
+      const appPackage = await fs.promises.readFile(appPackagePath, 'utf8');
+      const appPackageJson = JSON.parse(appPackage);
+      const port = await portfinder.getPortPromise({ port: basePort });
+      basePort = port + 1;
+      const pageConfig: PageConfig = {
+        key,
+        name: appPackageJson.name,
+        fullPath: path.join(appPath, key),
+        prefixPath: `/${key}`,
+        port,
+      };
+      pageConfigs.push(pageConfig);
+    } catch (error) {
+      console.error(`[${key}] 读取 package.json 失败: ${(error as Error).message}`);
+      continue;
+    }
+  }
+  return pageConfigs;
+}
+
+/**
+ * 在各自 `cwd` 下执行 `pnpm run dev -p <port>` 启动每个子应用。
+ * 监听 stdout 出现 Ready/successfully 时视为已就绪并 resolve（stderr 常含非错误日志，见下方）。
+ */
+async function runApp(pageConfigs: PageConfig[]) {
+  const promises = pageConfigs.map(config => {
+    return new Promise<ChildProcessWithoutNullStreams>((resolve, reject) => {
+      const child = spawn('pnpm', ['run', 'dev'], {
+        cwd: config.fullPath,
+        env: { ...process.env, PORT: String(config.port) },
+        // 如需在终端直接看到子应用原始输出，可改为 stdio: 'inherit'（需自行调整就绪判断逻辑）
+        shell: process.platform === 'win32',
+      });
+      child.on('error', (err) => {
+        console.error(chalk.red(`[${config.key}] 子进程启动失败:`), err.message);
+      });
+      child.on('exit', (code, signal) => {
+        if (code !== null && code !== 0) {
+          console.error(chalk.red(`[${config.key}] 子进程退出 code=${code} signal=${signal}`));
+        }
+      });
+      child.stdout.on('data', (data) => {
+        const msg = data.toString();
+        console.log(`${chalk.green(`[${config.key}]`)} ${msg}`);
+        const reg = /Local: http:\/\/localhost:(\d+)/
+        const match = msg.match(reg);
+        if (match) {
+          const port = match[1];
+          config.port = parseInt(port);
+          setTimeout(() => {
+            resolve(child)
+          });
+        }
+      });
+      child.stderr.on('data', (data) => {
+        const msg = data.toString();
+        console.log(`${chalk.dim(`[${config.key}]`)} ${msg}`);
+      });
+    })
+  })
+  return Promise.all(promises).then((childs) => {
+    console.log(chalk.green('所有子应用已启动'))
+    pageConfigs.forEach(config => {
+      console.log(`${chalk.green(`[${config.key}]`)} 子应用已启动：${chalk.blue(`http://127.0.0.1:${config.port}`)}`)
+    })
+    return childs
+  })
+}
+
+/**
+ * 根据当前请求解析应转发到的子应用：优先用路径匹配；无 Referer 或 Referer 为根时用请求路径；
+ * 否则用 Referer 的路径（便于静态资源等请求仍落到同一子应用）。无匹配时回退上次目标或第一个应用。
+ */
+function getTargetByRes(req: http.IncomingMessage, pageConfigs: PageConfig[], lastTargetPageConfig: PageConfig | null) {
+  const pathname = urlPathname(req.url) ?? '/';
+  const refererPathname = urlPathname(req.headers.referer)
+  const targetPathname = (
+    !refererPathname || refererPathname === '/'
+      ? pathname
+      : refererPathname
+  )
+  const pathConfig = getTargetByPath(targetPathname, pageConfigs);
+  return pathConfig ?? lastTargetPageConfig ?? pageConfigs[0]!;
+}
+
+/** 判断 `pathname` 是否属于某子应用（等于 `prefixPath` 或以其为前缀）。 */
+function getTargetByPath(pathname: string, pageConfigs: PageConfig[]) {
+  for (const config of pageConfigs) {
+    if (pathname === config.prefixPath || pathname.startsWith(`${config.prefixPath}/`)) {
+      return config;
+    }
+  }
+  return null;
+}
+
+/** 从完整 URL 或相对路径中解析 pathname；无效输入返回 `null`。 */
+function urlPathname(url: string | undefined) {
+  if (!url) return null;
+  try {
+    return new URL(url, 'http://127.0.0.1').pathname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 转发到子应用 dev 服务器前去掉网关层前缀（如 `/app`），使子应用收到根路径下的请求。
+ */
+function rewriteUrlForTarget(rawUrl: string | undefined, target: PageConfig): string {
+  if (!rawUrl) return '/';
+  const url = new URL(rawUrl, 'http://127.0.0.1');
+  url.pathname = url.pathname.replace(new RegExp(`^${target.prefixPath}`), '') || '/';
+  return url.toString();
+}
+
+/**
+ * 在可用端口（默认从 3000 起探测）上启动 HTTP 代理，支持 WebSocket；
+ * 根路径 `/` 返回各子应用入口链接，其余请求按路由规则转发到对应本地端口。
+ */
+async function runProxyServer(pageConfigs: PageConfig[]) {
+  const proxy = httpProxy.createProxyServer({ ws: true });
+  proxy.on('error', (err, req, res) => {
+    console.error(chalk.red('[proxy error]'), err.message);
+  });
+
+  let lastTargetPageConfig: PageConfig | null = null;
+
+  const server = http.createServer((req, res) => {
+    const pathname = urlPathname(req.url) ?? '/';
+    if (pathname === '/' || pathname === '') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      const links = pageConfigs
+        .map((c) => `  <li><a href="${c.prefixPath}">${c.prefixPath}</a> (${c.key})</li>`)
+        .join('\n');
+      res.end(
+        `<!DOCTYPE html><html><body><h1>子应用入口</h1><ul>\n${links}\n</ul></body></html>`
+      );
+      return;
+    }
+
+    lastTargetPageConfig = getTargetByRes(req, pageConfigs, lastTargetPageConfig);
+    req.url = rewriteUrlForTarget(req.url, lastTargetPageConfig);
+    proxy.web(req, res, {
+      target: `http://127.0.0.1:${lastTargetPageConfig.port}`,
+      changeOrigin: true,
+    });
+  });
+
+  server.on('upgrade', (req, socket, head) => {
+    lastTargetPageConfig = getTargetByRes(req, pageConfigs, lastTargetPageConfig);
+    req.url = rewriteUrlForTarget(req.url, lastTargetPageConfig);
+    proxy.ws(req, socket, head, {
+      target: `http://127.0.0.1:${lastTargetPageConfig.port}`,
+    });
+  });
+  const port = await portfinder.getPortPromise({ port: 3000 });
+  server.listen(port, () => {
+    console.log(chalk.green(`[gateway] 代理服务已启动 端口：${chalk.blue(port)}`));
+    console.log(`>>> 统一通过代理访问: ${chalk.blue(`http://127.0.0.1:${port}`)}`);
+    pageConfigs.forEach(config => {
+      console.log(`${chalk.green(`[${config.key}]`)} 子应用访问路径：${chalk.blue(`http://127.0.0.1:${port}${config.prefixPath}`)}`)
+    })
+  });
+  return server;
+}
+
+/**
+ * 在收到 SIGINT（Ctrl+C）或 SIGTERM 时关闭代理 `server` 并终止所有子进程；
+ * `server.close` 若迟迟不回调，3 秒后强制 `process.exit(0)`。
+ */
+function listenerClose(server: http.Server, childs: ChildProcessWithoutNullStreams[]) {
+  let cleaning = false;
+  const cleanup = () => {
+    if (cleaning) return;
+    cleaning = true;
+
+    server.close(() => {
+      childs.forEach((child) => {
+        if (child.killed) return;
+        child.kill('SIGTERM');
+      });
+      process.exit(0);
+    });
+    // 若 server.close 回调未及时触发，超时后强制退出
+    setTimeout(() => process.exit(0), 3000);
+  };
+
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}
+
+/** 加载配置 → 拉起子应用 → 启动网关代理 → 注册退出清理。 */
+async function main() {
+  const pageConfigs = await formatPageConfig();
+  if (pageConfigs.length === 0) {
+    console.error('未开启任何子应用，请检查 page.config.ts 配置');
+    process.exit(1);
+  }
+  const childs = await runApp(pageConfigs);
+  const proxyServer = await runProxyServer(pageConfigs);
+  listenerClose(proxyServer, childs);
+}
+
+main()

package/generators/h5-react/templates/turbo.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalEnv": [
+    "CDN_PUBLIC_PATH",
+    "BRANCH_OR_TAG",
+    "VERSION",
+    "SENTRY_AUTH_TOKEN"
+  ],
+  "envMode": "loose",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.production",
+        ".env.production.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "build:development": {
+      "dependsOn": ["^build:development"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.development",
+        ".env.development.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "build:testing": {
+      "dependsOn": ["^build:testing"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.testing",
+        ".env.testing.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "build:production": {
+      "dependsOn": ["^build:production"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!.umi/**",
+        "!.turbo/**",
+        "!src/.umi/**",
+        "!src/.umi-production/**",
+        "!src/.umi-test/**",
+        ".env",
+        ".env.local",
+        ".env.production",
+        ".env.production.local"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": {
+      "outputs": []
+    },
+    "lint:fix": {
+      "outputs": []
+    }
+  }
+}

package/generators/micro-react/README.md

@@ -0,0 +1,34 @@
+# micro-react 生成器
+
+创建完整的 qiankun 微前端 Monorepo。详细 prompt、模板变量、后置动作请见 [docs/generators.md#micro-react](../../docs/generators.md#micro-react)。
+
+## 快速索引
+
+| 文件 | 职责 |
+|---|---|
+| `index.js` | Yeoman 生成器类（`initializing` / `prompting` / `writing` / `install` / `end`） |
+| `meta.json` | `mico list` 展示的名称、描述、features |
+| `ignore-list.json` | `collectFiles` 按路径片段过滤的清单 |
+| `templates/` | 模板根（本仓库文档审计不覆盖此目录） |
+
+## 使用
+
+```bash
+mkdir my-project && cd my-project
+mico create micro-react
+# 可选：--dry-run / --verbose / --force
+```
+
+要求当前目录**不**是已有 monorepo（没有 `pnpm-workspace.yaml`）；`--force` 可绕过此检查。
+
+## 模板变量速查
+
+| 变量 | 类型 | 来源 |
+|---|---|---|
+| `projectName` / `ProjectName` | string | prompt，`toKebab` / `toPascal` |
+| `appId` | string | prompt |
+| `packageScope` | string | prompt |
+| `cdnPrefix` / `cdnPrefixPath` | string | prompt；`cdnPrefixPath` 为空或带尾斜杠 |
+| `author` | string | prompt |
+| `intlTag` | string | prompt |
+| `micoUiVersion` / `themeVersion` | string | `npm view @mico-platform/{ui,theme} version`，前缀 `^`，失败回退 `^1.0.0` |

package/generators/micro-react/index.js

@@ -186,6 +186,8 @@ module.exports = class extends Generator {
       const templateData = {
         projectName: this.projectName,
         ProjectName: this.ProjectName,
+        // 用于 MFSU mfName 等需要合法 JS 标识符的场景（不允许 `-`）
+        projectNameSnake: this.projectName.replace(/-/g, '_'),
         appId: this.appId,
         packageScope: this.packageScope,
         author: this.author,

package/generators/micro-react/templates/apps/layout/config/config.dev.ts

@@ -34,7 +34,7 @@ const config: ReturnType<typeof defineConfig> = {
           // 关闭权限控制（调试用）
           disableAuth: false,
           // SSO 外跳地址（与 resolveExternalLoginPath 读取的 externalLoginPath 一致；生产由注入的 __MICO_CONFIG__ 提供）
-          externalLoginPath: 'https://micous-idp.cig.tencentcs.com/sso/tn-456d1d3feb5f4e09ad28ab35ee4d2e66/ai-138064426b9e43818098705df5400eef/cas',
+          externalLoginPath: 'https://micous-idp.cig.tencentcs.com/sso/tn-456d1d3feb5f4e09ad28ab35ee4d2e66/ai-4919cf3d4883490b956b90376cfb86e7/cas',
           // 多语言中台（可选）：intl 与 common-intl 包 initIntl 合并；见 packages/common-intl/README.md
           // 这里只是一个例子，需要根据业务在翻译中台的配置来替换
           // intl: {
@@ -80,6 +80,26 @@ const config: ReturnType<typeof defineConfig> = {
     'process.env.LOCALE_REQUEST_URL':
       'https://api-test.micoplatform.com/lang_server/pull',
   },
+
+  /**
+   * @name MFSU 配置
+   * @description
+   * - mfName: 唯一名隔离微前端 runtime，避免多应用共存时 MFSU 容器冲突
+   * - exclude:
+   *   - `@mico-platform/theme`：theme 子路径解析
+   *   - `@mico-platform/ui`：尽量与主应用一起编译
+   *   - `<%= packageScope %>/*`：workspace 包走 webpack 编译，开发态可在 DevTools 直接定位到 packages/* 源码
+   * - shared: React 单例，确保 MFSU 预打包里的组件（如 Layout）与主应用共用同一份 React，否则 useContext 报 null
+   * @doc https://umijs.org/docs/api/config#mfsu
+   */
+  mfsu: {
+    mfName: 'mf_<%= projectNameSnake %>_layout',
+    exclude: ['@mico-platform/theme', '@mico-platform/ui', /^<%= packageScope %>\//],
+    shared: {
+      react: { singleton: true },
+      'react-dom': { singleton: true },
+    },
+  },
 };
 
 export default defineConfig(config);

package/generators/micro-react/templates/apps/layout/config/config.ts

@@ -124,21 +124,6 @@ const config: ReturnType<typeof defineConfig> = {
    */
   extraBabelPresets: ['@mico-platform/ui/babel-preset'],
 
-  /**
-   * @name MFSU 配置
-   * @description
-   * - exclude: theme 子路径解析；ui 尽量与主应用一起编译
-   * - shared: React 单例，确保 MFSU 预打包里的组件（如 Layout）与主应用共用同一份 React，否则 useContext 报 null
-   * @doc https://umijs.org/docs/guides/mfsu
-   */
-  mfsu: {
-    exclude: ['@mico-platform/theme', '@mico-platform/ui'],
-    shared: {
-      react: { singleton: true },
-      'react-dom': { singleton: true },
-    },
-  },
-
   /**
    * @name qiankun 微前端配置
    * @description 作为主应用，动态加载子应用

package/generators/micro-react/templates/apps/layout/docs/arch-/346/227/245/345/277/227/344/270/216/345/270/270/351/207/217.md

@@ -4,7 +4,15 @@
 
 ## Logger 工具
 
-生产环境静默的日志工具，使用 `bind` 保持正确的调用栈位置。
+默认：**开发环境**全量输出；**生产环境**仅 `log` / `info` / `warn` 静默，`error` 仍带前缀输出。使用 `bind` 保持正确的调用栈位置。
+
+### 生产临时全量日志（首屏 query）
+
+首屏 URL 带 **`?debug=1`**（或 `debug=true` / `yes`，大小写不敏感）时，在**本模块首次加载**时解析一次，之后 `log` / `info` / `warn` 与开发环境行为一致；**不**随 SPA 内路由或 query 变更而动态开关（需整页刷新并带上参数）。
+
+常量 **`DEBUG_LOGS_QUERY_KEY`**（当前为 `'debug'`）与 **`isLayoutDebugLogsEnabled`**（布尔）可从 `@/common/logger` 引用。
+
+**安全与合规**：仅用于临时排障；控制台可能含业务或个人信息，**勿长期公开或转发**带 `debug` 的生产链接；接入日志采集时需自行脱敏。
 
 ### 使用
 
@@ -18,12 +26,12 @@ layoutLogger.error('error'); // 保持原始调用栈位置
 ### 实现原理
 
 ```typescript
-// 使用 bind 而非 wrapper，保持控制台显示正确的调用位置
-const createLogger = (prefix: string) => ({
-  log: console.log.bind(console, `[${prefix}]`),
-  error: console.error.bind(console, `[${prefix}]`),
-  // ...
-});
+// 使用 bind 而非 wrapper，保持控制台显示实际调用位置
+// 生产且未开 debug：log/info/warn 为 noop，error 仍 bind
+const createLogger = (prefix: string) =>
+  isLayoutDebugLogsEnabled
+    ? createVerboseHandlers(`[${prefix}]`)
+    : createQuietHandlers(`[${prefix}]`);
 ```
 
 ### 预定义 Logger
@@ -100,6 +108,6 @@ export const STORAGE_KEYS = {
 
 ## 注意事项
 
-- Logger 仅在开发环境输出，生产环境静默
+- 生产默认仅 `error` 输出；首屏 `?debug=1` 等可打开全量日志（见上文），用完建议去掉参数或整页刷新无参 URL
 - 使用 `bind` 实现，DevTools 显示实际调用位置而非 logger.ts
 - 新增路由常量应添加到 `ROUTES` 对象

package/generators/micro-react/templates/apps/layout/docs/feat-/346/236/204/345/273/272define/344/270/216/345/205/215/350/256/244/350/257/201/345/210/235/345/247/213/346/200/201.md

@@ -1,11 +1,13 @@
 # 构建 define 精简与免认证页初始态
 
-> 创建时间：2026-03-24
+> 创建时间：2026-03-24  
+> 更新：2026-05-13（补充 `defaultPath` 首屏与 `authCheckPath`、与手动跳转认证页的差异；补充从免认证页跳进认证页后 **`refresh` → `fetchUserInfo`** 的说明）
 
 ## 功能概述
 
 1. **Umi `define`**：不再通过构建期注入 `process.env.EXTERNAL_LOGIN_PATH`（本模板从未注入 `APP_ID`）；SSO 外跳等依赖运行时 `window.__MICO_CONFIG__`。
 2. **`getInitialState`**：免认证路由下即使本地仍有 token，也不请求用户信息接口，减少无效调用。
+3. **`/` + `defaultPath` 首屏**：若仅用 `location.pathname === '/'` 判断是否免认证，可能与「即将 `replace` 到的默认页」的认证要求不一致；见下文 **`authCheckPath`**。
 
 ## 技术方案
 
@@ -21,7 +23,46 @@
 
 ### 初始态
 
-`src/app.tsx` 中仅在 `getStoredAuthToken() && !skipAuth` 时调用 `fetchUserInfoFn()`；`skipAuth = isNoAuthRoute || isPageAuthFree`。
+`src/app.tsx` 中仅在 `getStoredAuthToken() && !skipAuth` 时调用 `fetchUserInfoFn()`；`skipAuth` 由 **`isNoAuthRoute(authCheckPath) || isPageAuthFree(authCheckPath)`** 计算（见下节 **`authCheckPath`**，勿与仅看 `location.pathname` 混淆）。
+
+### `defaultPath` 与 `authCheckPath`（首屏重定向 vs 手动进认证页）
+
+#### 背景
+
+访问 **`/`** 且配置了 **`window.__MICO_CONFIG__.defaultPath`**（且不为 `/`）时，`app.tsx` 的 **`onRouteChange`** 会 **`history.replace(defaultPath)`**（例如跳到工作台）。**`getInitialState` 与 `onRouteChange` 的执行顺序下，首屏拿到的 `history.location.pathname` 往往仍是 `/`**。
+
+若 **`/`** 被配进 **`noAuthRouteList`**，或 **`/`** 对应页面 **`accessControlEnabled: false`**（页面级免认证），则仅按 **`pathname === '/'`** 会得到 **`skipAuth === true`**：不执行 **`ensureSsoSession`**、不按需认证页拉用户；随后用户马上被重定向到 **`defaultPath` 所指的需登录页**，形成「用免认证壳路径误判、绕开目标页认证」的窗口。为此在 **`getInitialState`**（约自 `app.tsx` 215 行起）对 **`defaultPath`** 做与 **`onRouteChange`** 一致的重定向预判。
+
+#### `authCheckPath` 规则
+
+- 当 **`pathname === '/'`** 且存在有效 **`defaultPath`**（与 `/` 不同）时，视为即将发生默认重定向，令 **`authCheckPath = defaultPath`**；
+- 否则 **`authCheckPath = location.pathname`**。
+
+**`isNoAuthRoute`、`isPageAuthFree` 以及由此得到的 `skipAuth`、`ensureSsoSession`、是否拉 `fetchUserInfo` 等，均基于 `authCheckPath`**，使首屏认证语义与 **重定向目标页** 一致，而不是与瞬时的 **`/`** 一致。
+
+实现上 **`authCheckPath`** 与 **`handleAuthFailureRedirect`**（`src/common/request/sso.ts`）共用 **`resolveAuthCheckPath(pathname)`**（`src/common/auth/auth-check-path.ts`），避免无 token 时 **`getInitialState` 已按 `defaultPath` 判定需认证**，但 SSO 外跳仍按浏览器地址 **`/`** 误判为免认证而**不触发重定向**。
+
+#### 与「从免认证页手动点到认证页」的区别
+
+| 场景 | 典型 `location.pathname` | 为何不会误判 |
+| --- | --- | --- |
+| **`/` + `defaultPath` 首屏** | 首屏仍为 **`/`**，真实要去 **`defaultPath`** | 若只看 **`/`**，可能与 **`defaultPath`** 的认证要求不一致；必须用 **`authCheckPath`** 把判断「对齐到目标页」。 |
+| **应用内从免认证页导航到认证页**（如 `/login` → `/app`） | 导航后 **`/app/...`** | 不会用旧页的免认证 pathname 算 **`skipAuth`**；且布局里 **`useRoutePermissionRefresh`** 在 pathname 变为**非** `isNoAuthRoute` 时会调用 **`@@initialState` 的 `refresh()`**，从而**再次执行 `getInitialState`**，在 **`getStoredAuthToken() && !skipAuth`** 成立时拉 **`fetchUserInfo`**（见下节）。整页刷新直达认证页时逻辑相同，仅触发时机为首屏而非路由变更。 |
+| **外链直达或地址栏改为认证页** | 直接进入 **`/app/xxx`** | 首屏 `getInitialState` 即按认证页计算 **`skipAuth`**；有 token 则拉 **`fetchUserInfo`**。 |
+
+#### 为何客户端从免认证跳进认证页后会拉取用户权限（`fetchUserInfo`）
+
+1. **首屏停在免认证路径**：`getInitialState` 里 **`skipAuth === true`**，模板在 **`getStoredAuthToken() && !skipAuth`** 条件下**不会**为当前首屏去调用户信息接口，`currentUser` 可能仍为空（见 `app.tsx`）。
+
+2. **`pathname` 变为需认证路径**：`layouts/index.tsx` 使用 **`useRoutePermissionRefresh`**（`src/hooks/useRoutePermissionRefresh.ts`）。在**跳过首次渲染**之后，每当 **`location.pathname` 变化**且新路径**不是** **`isNoAuthRoute`** 所指的静态免认证路由时，会防抖调用 Umi **`useModel('@@initialState').refresh()`**。
+
+3. **`refresh()` 会重新执行 `getInitialState`**：此时用于计算 **`skipAuth`** 的路径已是认证页（并适用上文 **`authCheckPath`** 规则），一般 **`skipAuth === false`**；若本地仍有 **`getStoredAuthToken()`**，即进入 **`fetchUserInfoFn()`**，请求 **`GET /user/info/`** 等，更新 **`menu_perms`、`button_perms`** 等，供菜单、PermissionFilter、MicroAppLoader 注入子应用等使用。
+
+4. **与「整页刷新且首屏已在认证页」**：走同一套 `getInitialState` 分支；差别是触发源为 **路由变更 + `refresh()`**，而非 **应用冷启动首屏**。
+
+5. **实现细节**：`useRoutePermissionRefresh` 仅以 **`isNoAuthRoute(pathname)`** 判断是否跳过刷新；若某路由**仅**页面级 **`isPageAuthFree`** 而不在 `noAuthRouteList` 中，离开该页时 pathname 变化仍可能触发 **`refresh()`**——即「离开静态免认证名单就允许刷新权限」的策略。
+
+**结论**：「绕过认证」风险来自 **「URL 暂时是免认证的 `/`，但实际业务要去需 SSO 的 `defaultPath`」** 这一种 **首屏 + 默认重定向** 组合；**`authCheckPath`** 专门纠偏这一种。**手动从免认证页进入认证页**时，浏览器地址已是认证路径，鉴权按认证页执行，**不依赖**与 `defaultPath` 相同的特殊分支；二者差异在于 **是否存在「pathname 与真实首屏业务路径不一致」的短暂错位**。在 **SPA** 下，进入认证页后还会经 **`useRoutePermissionRefresh` → `refresh()`** 在 **有 token** 时补拉 **`fetchUserInfo`**（见上节），避免 **`currentUser` 仍为空**、菜单与子应用权限数据落后。
 
 ## 文件清单
 
@@ -31,7 +72,11 @@
 | `config/config.prod.ts` | 移除 `EXTERNAL_LOGIN_PATH` define |
 | `config/config.prod.development.ts` | 同上 |
 | `config/config.prod.testing.ts` | 同上 |
-| `src/app.tsx` | `fetchUserInfo` 条件增加 `!skipAuth` |
+| `src/app.tsx` | `getInitialState` 使用 `resolveAuthCheckPath` |
+| `src/common/auth/auth-check-path.ts` | `resolveAuthCheckPath`：`/` + `defaultPath` 与真实鉴权路径对齐 |
+| `src/common/request/sso.ts` | `handleAuthFailureRedirect` 使用 `resolveAuthCheckPath`，与 `getInitialState` 一致 |
+| `src/hooks/useRoutePermissionRefresh.ts` | 非静态免认证路径的 pathname 变更时 `refresh()`，触发重跑 `getInitialState` 以拉权限 |
+| `src/layouts/index.tsx` | 使用 `useRoutePermissionRefresh` |
 
 ## 部署注意
 
@@ -40,5 +85,6 @@
 
 ## 相关文档
 
+- [菜单权限控制](./feature-菜单权限控制.md)（SSO 步骤与 pathname / `authCheckPath` 关系）
 - [fix-SSO无限重定向](./fix-SSO无限重定向.md)
 - [arch-请求模块](./arch-请求模块.md)

package/generators/micro-react/templates/apps/layout/docs/feature-/350/217/234/345/215/225/346/235/203/351/231/220/346/216/247/345/210/266.md

@@ -1,6 +1,6 @@
 # 菜单权限控制
 
-> 创建时间：2026-01-24 更新时间：2026-03-27（同步 `getMenuPage`：pageId 优先，path 兜底）
+> 创建时间：2026-01-24 更新时间：2026-03-27（同步 `getMenuPage`：pageId 优先，path 兜底）；2026-05-13（`getInitialState` 与 `authCheckPath` 说明链至 feat-构建define）
 
 ## 功能概述
 
@@ -84,6 +84,8 @@
 └──────────────────────────────────────────────┘
 ```
 
+**首屏 `getInitialState` 与步骤 1**：若 URL 为 **`/`** 且配置了 **`__MICO_CONFIG__.defaultPath`**（非 `/`），`onRouteChange` 会 **`replace`** 到默认路径，首屏瞬间 **`location.pathname` 可能仍为 `/`**。此时步骤 1 不能只看 **`pathname`**，需用 **`authCheckPath`**（见 [feat-构建define与免认证初始态](./feat-构建define与免认证初始态.md) 中「`defaultPath` 与 `authCheckPath`」）。图中步骤 1 的「pathname」在 **`getInitialState`** 语境下指 **`authCheckPath`**；从免认证页**手动**进入认证页时，地址已是认证路径，无「`/` 壳 vs `defaultPath` 目标」错位。**客户端 SPA** 下进入认证页后，还会由 **`useRoutePermissionRefresh` → `@@initialState.refresh()`** 重跑 `getInitialState`，在 **有 token** 时拉 **`fetchUserInfo`**（详见该文档「为何客户端从免认证跳进认证页后会拉取用户权限」）。
+
 ### 权限判断逻辑（详细）
 
 ```

package/generators/micro-react/templates/apps/layout/docs/feature-/350/267/257/347/224/261/346/235/203/351/231/220/346/227/245/345/277/227.md

@@ -9,14 +9,14 @@
 1. **`routePermission`**：`BasicLayout` 中 **`isForbidden` 路由权限判定**（为何放行 / 为何 403）。
 2. **`menuFilter`**：`filterMenuItems` 中**被隐藏的菜单项**及**隐藏原因**（侧栏不可见条目）。
 
-日志均经 `layoutLogger` 输出，**仅开发环境生效**，生产构建无控制台输出。
+日志均经 `layoutLogger` 输出；**默认仅开发环境**会在控制台看到 `log`；生产首屏带 `?debug=1`（等）时行为与开发一致，见 [日志与常量](./arch-日志与常量.md)。
 
 ## 技术方案
 
 ### 技术栈
 
 - 框架：React 18 + @umijs/max
-- 日志：`apps/layout/src/common/logger.ts` 的 `layoutLogger`（`NODE_ENV === 'development'` 时 `console.log`）
+- 日志：`apps/layout/src/common/logger.ts` 的 `layoutLogger`（开发环境或生产首屏 `debug` query 时输出 `log`）
 
 ### 核心实现
 
@@ -142,13 +142,13 @@ menuFilter
 | 决策点 | 选择 | 理由 |
 |--------|------|------|
 | 日志前缀 | 固定 `'routePermission'` + 对象载荷 | 可过滤、可结构化，便于 AI/人工检索 |
-| 生产环境 | 静默 | `layoutLogger` 在 `production` 下不输出 |
+| 生产环境 | 默认静默 `log` | `layoutLogger` 在 production 下 `log`/`info`/`warn` 为 noop；首屏 `?debug=1` 等同开发 |
 | 无 `currentRoute` 不打日志 | 跳过 | 静态路由访问频繁，避免噪音 |
 | `menuFilter` 与超管/关权限 | 不打 | 无过滤效果时无隐藏项可记 |
 
 ## 已知限制与待改进
 
-- 日志仅在**开发环境**可见；线上问题需依赖 Sentry 或其它监控，不在本功能内。
+- **默认**仅开发环境会在控制台看到本功能的 `log`；生产首屏带 `?debug=1`（等）时亦会输出，见 [日志与常量](./arch-日志与常量.md)。线上问题仍主要依赖 Sentry 或其它监控。
 - `renderContent` 另有 `renderContent:` 日志，与 `routePermission` 独立，排查时可同时参考。
 
 ## 注意事项

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -22,6 +22,7 @@ import {
   type ILang,
 } from '<%= packageScope %>/common-intl';
 import * as CommonIntl from '<%= packageScope %>/common-intl';
+import { resolveAuthCheckPath } from './common/auth/auth-check-path';
 import { getStoredAuthToken } from './common/auth/auth-manager';
 import type { IUserInfo } from './common/auth/type';
 import { fetchUserInfo } from './services/user';
@@ -210,16 +211,21 @@ export async function getInitialState(): Promise<{
   };
 
   const { location } = history;
-  const noAuthRoute = isNoAuthRoute(location.pathname);
-  const skipAuth = noAuthRoute || isPageAuthFree(location.pathname);
+  // 如果当前路径是 / 且配置了 defaultPath（onRouteChange 会立即重定向），
+  // 用目标路径判断是否需要认证，避免用免认证的兜底页绕过目标页的认证要求（与 resolveAuthCheckPath、sso handleAuthFailureRedirect 一致）
+  const authCheckPath = resolveAuthCheckPath(location.pathname);
+
+  const noAuthRoute = isNoAuthRoute(authCheckPath);
+  const skipAuth = noAuthRoute || isPageAuthFree(authCheckPath);
 
   // 非免认证路由：走 SSO 流程
   if (!skipAuth) {
     await ensureSsoSession();
   }
 
-  // 有 token 就获取用户信息（登录后 refresh、免认证页同样需要 currentUser：
-  // 如 PermissionFilter / MicroAppLoader 注入子应用的 button_perms）
+  // 仅在「需认证」路径且本地已有 token 时拉取用户信息（登录态刷新等）。
+  // 免认证 / 页面级免认证路径不强制 SSO，本地未必有 token；不进入本分支则无 currentUser，
+  // PermissionFilter、MicroAppLoader 注入子应用的 button_perms 等按无登录用户（无权限）处理。
   if (getStoredAuthToken() && !skipAuth) {
     const userInfo = await fetchUserInfoFn();
     if (userInfo) {

package/generators/micro-react/templates/apps/layout/src/common/auth/auth-check-path.ts

@@ -0,0 +1,14 @@
+/**
+ * 与 `app.tsx` 中 `getInitialState` 的鉴权路径语义一致：
+ * 访问 `/` 且配置了 `window.__MICO_CONFIG__.defaultPath`（非 `/`）时，`onRouteChange` 会 `replace` 到该路径，
+ * 首屏 `location.pathname` 可能仍为 `/`，但免认证 / SSO 失败重定向等判断应以**目标路径**为准。
+ */
+export function resolveAuthCheckPath(pathname: string): string {
+  if (typeof window === 'undefined') {
+    return pathname;
+  }
+  const defaultPath = window.__MICO_CONFIG__?.defaultPath;
+  const willRedirectToDefault =
+    pathname === '/' && !!defaultPath && defaultPath !== '/';
+  return willRedirectToDefault ? defaultPath : pathname;
+}