vitarx-router 4.0.0-beta.22 → 4.0.0-beta.24

package/README.md

@@ -292,6 +292,70 @@ if (hasSuccess(result)) {
 | `duplicated` | 8  | 重复导航     |
 | `notfound`   | 16 | 路由未匹配    |
 
+## 路由未匹配处理
+
+当路由匹配失败（404）时，可以通过 `onNotFound` 钩子进行自定义处理。
+
+### onNotFound 钩子
+
+```typescript
+import { createRouter } from 'vitarx-router'
+
+const router = createRouter({
+  routes: [],
+  onNotFound(target) {
+    // target.index 为用户尝试访问的目标
+    console.log('路由未匹配:', target.index)
+  }
+})
+```
+
+**返回值说明：**
+
+| 返回值                        | 说明                   |
+|----------------------------|----------------------|
+| `NavTarget` / `RouteIndex` | 重定向到新目标              |
+| `RouteLocation`            | 作为未匹配路由的位置对象（渲染指定组件） |
+| `void`                     | 不处理，返回 `notfound` 状态 |
+
+### 重定向到 404 页面
+
+```typescript
+import { createRouter } from 'vitarx-router'
+
+const router = createRouter({
+  routes: [],
+  onNotFound(target) {
+    return { index: '/404' }
+  }
+})
+```
+
+### 渲染 404 组件（使用 createMissingRoute）
+
+```typescript
+import { createRouter, createMissingRoute } from 'vitarx-router'
+import NotFoundPage from './pages/NotFound.jsx'
+
+const router = createRouter({
+  routes: [],
+  onNotFound(target) {
+    return createMissingRoute(NotFoundPage, target, {
+      title: '页面未找到'
+    })
+  }
+})
+```
+
+### 名称导航不匹配
+
+名称导航（name-based）匹配失败时，路由器会直接抛出错误，因为名称导航是编程式调用，name 不存在属于代码 bug：
+
+```typescript
+// 如果 'userDetail' 路由不存在，将抛出错误
+router.push({ index: 'userDetail', params: { id: '123' } })
+```
+
 ## 导航守卫
 
 ### 全局前置守卫
@@ -472,18 +536,20 @@ declare module 'vitarx-router' {
 
 ### 助手函数
 
-| 函数                                     | 说明              |
-|----------------------------------------|-----------------|
-| `createRouter(options)`                | 创建路由器实例         |
-| `createWebRouter(options)`             | 创建 Web 模式路由器    |
-| `createMemoryRouter(options)`          | 创建 Memory 模式路由器 |
-| `createRouteManager(routes, options?)` | 创建路由管理器         |
-| `defineRoutes(...routes)`              | 定义路由表           |
-| `useRouter()`                          | 获取路由器实例         |
-| `useRoute(global?)`                    | 获取当前路由信息        |
-| `useLink(options)`                     | 创建链接助手          |
-| `onBeforeRouteLeave(guard)`            | 注册离开守卫          |
-| `onBeforeRouteUpdate(callback)`        | 注册更新钩子          |
+| 函数                                             | 说明                     |
+|------------------------------------------------|------------------------|
+| `createRouter(options)`                        | 创建路由器实例                |
+| `createWebRouter(options)`                     | 创建 Web 模式路由器           |
+| `createMemoryRouter(options)`                  | 创建 Memory 模式路由器        |
+| `createRouteManager(routes, options?)`         | 创建路由管理器                |
+| `defineRoutes(...routes)`                      | 定义路由表                  |
+| `createMissingRoute(component, target, meta?)` | 创建未匹配路由的 RouteLocation |
+| `useRouter()`                                  | 获取路由器实例                |
+| `useRoute(global?)`                            | 获取当前路由信息               |
+| `useLink(options)`                             | 创建链接助手                 |
+| `onBeforeRouteLeave(guard)`                    | 注册离开守卫                 |
+| `onBeforeRouteUpdate(callback)`                | 注册更新钩子                 |
+| `removePathEndSlash(path)`                     | 删除路径末尾的斜杠              |
 
 ### Router 实例方法
 

package/dist/core/common/utils.d.ts

@@ -7,6 +7,16 @@ import type { GuardResult, NavTarget, RouteIndex, RouteLocation, RoutePath, URLH
  * @returns {boolean} 如果值是一个导航目标对象则返回true，否则返回false
  */
 export declare function hasValidNavTarget(val: unknown): val is NavTarget;
+/**
+ * 检查给定的值是否为 RouteLocation 对象
+ *
+ * 通过检测 `matched` 和 `path` 属性来区分 RouteLocation 与 NavTarget，
+ * 因为 NavTarget 不包含这两个字段，而 RouteLocation 必定包含。
+ *
+ * @param val - 需要检查的值
+ * @returns {val is RouteLocation} 如果是 RouteLocation 对象则返回 true
+ */
+export declare function isRouteLocation(val: unknown): val is RouteLocation;
 /**
  * 检查给定的值是否为有效的路由索引
  *
@@ -28,7 +38,7 @@ export declare function hasOnlyChangeHash(route1: RouteLocation, route2: RouteLo
  * @param index - 要判断的索引
  * @returns {boolean} - 如果索引为路径索引则返回true，否则返回false
  */
-export declare function hasValidPath(index: any): index is RoutePath;
+export declare function isValidPath(index: unknown): index is RoutePath;
 /**
  * 移除路径字符串中的指定后缀
  * @param path - 原始路径字符串

package/dist/core/common/utils.js

@@ -7,10 +7,20 @@ import { normalizePath, parseQuery } from '../shared/utils.js';
  * @returns {boolean} 如果值是一个导航目标对象则返回true，否则返回false
  */
 export function hasValidNavTarget(val) {
-    // 首先检查值是否是一个普通对象
-    // 然后检查该对象是否包含 'index' 属性
     return isPlainObject(val) && 'index' in val && hasValidRouteIndex(val.index);
 }
+/**
+ * 检查给定的值是否为 RouteLocation 对象
+ *
+ * 通过检测 `matched` 和 `path` 属性来区分 RouteLocation 与 NavTarget，
+ * 因为 NavTarget 不包含这两个字段，而 RouteLocation 必定包含。
+ *
+ * @param val - 需要检查的值
+ * @returns {val is RouteLocation} 如果是 RouteLocation 对象则返回 true
+ */
+export function isRouteLocation(val) {
+    return isPlainObject(val) && 'matched' in val && 'path' in val;
+}
 /**
  * 检查给定的值是否为有效的路由索引
  *
@@ -39,7 +49,7 @@ export function hasOnlyChangeHash(route1, route2) {
  * @param index - 要判断的索引
  * @returns {boolean} - 如果索引为路径索引则返回true，否则返回false
  */
-export function hasValidPath(index) {
+export function isValidPath(index) {
     return isString(index) && index.startsWith('/');
 }
 /**

package/dist/core/router/checkOptions.js

@@ -1,4 +1,4 @@
-import { isComponent, isFunction } from 'vitarx';
+import { isFunction } from 'vitarx';
 import { RouteManager } from './manager.js';
 /**
  * 检查路由器配置选项的合法性
@@ -110,10 +110,4 @@ export const checkRouterOptions = (options) => {
             });
         }
     }
-    // 9. 检查 missing 组件的类型
-    if ('missing' in options && options.missing !== undefined) {
-        if (!isComponent(options.missing)) {
-            throw new Error('[Router] "missing" must be a valid component.');
-        }
-    }
 };

package/dist/core/router/manager.js

@@ -1,6 +1,6 @@
 import { isArray, isFunction, isString, logger, markRaw } from 'vitarx';
 import { resolveComponent, resolvePattern, resolveProps } from '../common/resolve.js';
-import { hasValidNavTarget, hasValidPath, hasValidRouteIndex } from '../common/utils.js';
+import { hasValidNavTarget, hasValidRouteIndex, isValidPath } from '../common/utils.js';
 import { isVariablePath, mergePathVariable, mergePattern, optionalVariableCount, validateAliasVariables } from '../common/variable.js';
 import { normalizePath } from '../shared/utils.js';
 /**
@@ -288,7 +288,7 @@ export class RouteManager {
      * @returns 匹配结果对象，包含路由记录和解析后的参数；未匹配返回 null
      */
     match(index, params) {
-        if (hasValidPath(index)) {
+        if (isValidPath(index)) {
             return this.matchByPath(index);
         }
         return this.matchByName(index, params);

package/dist/core/router/router.d.ts

@@ -1,5 +1,5 @@
 import { App, type ReadonlyObject } from 'vitarx';
-import type { AfterCallback, NavigateResult, NavigationGuard, NavOptions, NavTarget, ResolvedRouterConfig, Route, RouteIndex, RouteLocation, RouteRecord, RouterOptions, ScrollPosition, ScrollTarget, URLHash, URLQuery } from '../types/index.js';
+import type { AfterCallback, NavErrorListener, NavigateResult, NavigationGuard, NavOptions, NavTarget, NotFoundHandler, ResolvedRouterConfig, Route, RouteIndex, RouteLocation, RouteRecord, RouterOptions, ScrollPosition, ScrollTarget, URLHash, URLQuery } from '../types/index.js';
 import { RouteManager } from './manager.js';
 /**
  * 导航上下文
@@ -177,6 +177,16 @@ export declare abstract class Router {
      * @param guard
      */
     beforeEach(guard: NavigationGuard): void;
+    /**
+     * 添加错误处理回调函数
+     * @param handler
+     */
+    onError(handler: NavErrorListener): void;
+    /**
+     * 添加未匹配路由处理回调函数
+     * @param handler
+     */
+    onNotFound(handler: NotFoundHandler): void;
     /**
      * 跳转指定的历史记录位置
      *
@@ -319,13 +329,24 @@ export declare abstract class Router {
      * @returns 导航上下文对象
      */
     private createNavigationContext;
+    /**
+     * 执行导航流程
+     *
+     * 统一处理重复路由检测、hash 变化、重定向、守卫和导航完成。
+     * 被 navigate 和 handleNotFound（onNotFound 返回 RouteLocation 时）共用。
+     *
+     * @param context - 导航上下文
+     * @returns 导航结果
+     */
+    private processNavigation;
     /**
      * 处理路由未匹配（404）场景
      *
      * 当目标路由无法匹配时执行：
      * 1. 触发全局 onNotFound 钩子
-     * 2. 如果钩子返回了新的导航目标，进行重定向
-     * 3. 否则返回 notfound 状态
+     * 2. 如果钩子返回了 RouteLocation，将其设为导航目标继续正常导航流程
+     * 3. 如果钩子返回了新的导航目标（NavTarget），进行重定向
+     * 4. 否则返回 notfound 状态
      *
      * @param context - 导航上下文
      * @param target - 原始导航目标
@@ -437,6 +458,16 @@ export declare abstract class Router {
     private runScrollBehavior;
     /**
      * 处理 404 错误
+     *
+     * 执行 onNotFound 钩子链，按注册顺序依次调用，
+     * 第一个返回有效值的钩子会终止遍历。
+     *
+     * 返回值类型：
+     * - RouteLocation: 作为未匹配路由的位置对象（优先判断，因为结构更具体）
+     * - NavTarget: 重定向到新目标
+     * - string | symbol: 包装为 NavTarget 后重定向
+     * - void: 继续执行下一个钩子
+     *
      * @param target - 导航目标对象
      * @returns - 返回处理结果
      */
@@ -487,15 +518,6 @@ export declare abstract class Router {
      * @private
      */
     private reportError;
-    /**
-     * 创建缺失的路由
-     * @param component - 路由组件
-     * @param path - 路径
-     * @param query - 查询参数
-     * @param hash - 哈希值
-     * @returns {RouteLocation} - 返回创建的路由位置对象
-     */
-    private createMissingRoute;
     /**
      * 构建完整URL路径
      *

package/dist/core/router/router.js

@@ -1,7 +1,7 @@
 import { getLazyLoader, isArray, isFunction, isPlainObject, isPromise, isString, logger, nextTick, preloadComponent, readonly, shallowReactive } from 'vitarx';
 import { __ROUTER_KEY__, NavState } from '../common/constant.js';
 import { updateRouteLocation } from '../common/update.js';
-import { hasOnlyChangeHash, hasValidNavTarget, hasValidPath, hasValidRouteIndex, processGuardResult, registerHookTool, removePathSuffix, resolveNavTarget } from '../common/utils.js';
+import { hasOnlyChangeHash, hasValidNavTarget, hasValidRouteIndex, isRouteLocation, isValidPath, processGuardResult, registerHookTool, removePathSuffix, resolveNavTarget } from '../common/utils.js';
 import { cloneRouteLocation, normalizePath, stringifyQuery } from '../shared/utils.js';
 import { checkRouterOptions } from './checkOptions.js';
 import { RouteManager } from './manager.js';
@@ -247,6 +247,20 @@ export class Router {
     beforeEach(guard) {
         registerHookTool(this._hooks, 'beforeEach', guard);
     }
+    /**
+     * 添加错误处理回调函数
+     * @param handler
+     */
+    onError(handler) {
+        registerHookTool(this._hooks, 'onError', handler);
+    }
+    /**
+     * 添加未匹配路由处理回调函数
+     * @param handler
+     */
+    onNotFound(handler) {
+        registerHookTool(this._hooks, 'onNotFound', handler);
+    }
     /**
      * 后退到上一个历史记录
      */
@@ -430,6 +444,16 @@ export class Router {
         }
         // 解析目标路由
         const to = this.matchRoute(target, redirectFrom);
+        // name-based 导航匹配失败视为编程错误，直接抛出异常
+        // 因为名称导航是编程式调用，name 不存在或参数校验失败属于代码 bug
+        if (!to && !isValidPath(target.index)) {
+            const name = target.index;
+            const route = this.manager.findByName(name);
+            if (route) {
+                throw new Error(`[Router] Route "${String(name)}" matched but params validation failed. Check required params and their formats.`);
+            }
+            throw new Error(`[Router] Route not found: "${String(name)}". Name-based navigation must target a registered route.`);
+        }
         // 确定来源路由
         const from = fromRoute ?? cloneRouteLocation(this._routeLocation);
         // 构建导航结果基础对象
@@ -470,22 +494,61 @@ export class Router {
             }
         };
     }
+    /**
+     * 执行导航流程
+     *
+     * 统一处理重复路由检测、hash 变化、重定向、守卫和导航完成。
+     * 被 navigate 和 handleNotFound（onNotFound 返回 RouteLocation 时）共用。
+     *
+     * @param context - 导航上下文
+     * @returns 导航结果
+     */
+    async processNavigation(context) {
+        // 首次导航后才需检测重复和 hash 变化（首次导航无 from，不存在重复场景）
+        if (context.from.matched.length) {
+            // 重复路由：目标与当前路由完全一致，直接返回
+            const duplicatedResult = this.handleDuplicatedRoute(context);
+            if (duplicatedResult)
+                return duplicatedResult;
+            // 仅 hash 变化：路径和参数不变，仅 hash 不同，走轻量处理
+            const hashOnlyResult = this.handleHashOnlyChange(context);
+            if (hashOnlyResult)
+                return hashOnlyResult;
+        }
+        // 重定向：路由配置了 redirect，递归导航到新目标
+        const redirectResult = await this.handleRedirect(context);
+        if (redirectResult)
+            return redirectResult;
+        // 守卫流程：执行 beforeEach 和 beforeEnter，可能中止导航
+        const guardResult = await this.executeGuards(context);
+        if (guardResult)
+            return guardResult;
+        // 守卫通过，完成导航：更新状态、触发 afterEach、渲染组件
+        return this.finalizeNavigation(context);
+    }
     /**
      * 处理路由未匹配（404）场景
      *
      * 当目标路由无法匹配时执行：
      * 1. 触发全局 onNotFound 钩子
-     * 2. 如果钩子返回了新的导航目标，进行重定向
-     * 3. 否则返回 notfound 状态
+     * 2. 如果钩子返回了 RouteLocation，将其设为导航目标继续正常导航流程
+     * 3. 如果钩子返回了新的导航目标（NavTarget），进行重定向
+     * 4. 否则返回 notfound 状态
      *
      * @param context - 导航上下文
      * @param target - 原始导航目标
      * @returns 导航结果
      */
-    handleNotFound(context, target) {
+    async handleNotFound(context, target) {
         const notFoundResult = this.runNotFoundHook(target);
-        // 钩子返回了新的导航目标，进行重定向
         if (notFoundResult) {
+            // 钩子返回了 RouteLocation，将其设为导航目标，继续正常导航流程
+            if (isRouteLocation(notFoundResult)) {
+                context.to = notFoundResult;
+                context.result.to = notFoundResult;
+                return this.processNavigation(context);
+            }
+            // 钩子返回了 NavTarget，进行重定向
             context.checkRedirectLoop(String(notFoundResult.index));
             return this.navigate(notFoundResult, context.from);
         }
@@ -677,31 +740,12 @@ export class Router {
     async navigate(target, fromRoute, redirectFrom) {
         // 创建导航上下文
         const context = this.createNavigationContext(target, fromRoute, redirectFrom);
-        // 场景1: 路由未匹配 (404)
+        // 路由未匹配 (404)
         if (!context.to) {
             return this.handleNotFound(context, target);
         }
-        // 仅在路由第一次路由后检测重复路由
-        if (context.from.matched.length) {
-            // 场景2: 重复路由
-            const duplicatedResult = this.handleDuplicatedRoute(context);
-            if (duplicatedResult)
-                return duplicatedResult;
-            // 场景3: 仅hash变化
-            const hashOnlyResult = this.handleHashOnlyChange(context);
-            if (hashOnlyResult)
-                return hashOnlyResult;
-        }
-        // 场景4: 路由重定向
-        const redirectResult = await this.handleRedirect(context);
-        if (redirectResult)
-            return redirectResult;
-        // 场景5: 执行守卫流程
-        const guardResult = await this.executeGuards(context);
-        if (guardResult)
-            return guardResult;
-        // 场景6: 完成导航
-        return this.finalizeNavigation(context);
+        // 处理导航
+        return this.processNavigation(context);
     }
     // ============================================================
     // 导航完成与滚动行为
@@ -769,6 +813,16 @@ export class Router {
     // ============================================================
     /**
      * 处理 404 错误
+     *
+     * 执行 onNotFound 钩子链，按注册顺序依次调用，
+     * 第一个返回有效值的钩子会终止遍历。
+     *
+     * 返回值类型：
+     * - RouteLocation: 作为未匹配路由的位置对象（优先判断，因为结构更具体）
+     * - NavTarget: 重定向到新目标
+     * - string | symbol: 包装为 NavTarget 后重定向
+     * - void: 继续执行下一个钩子
+     *
      * @param target - 导航目标对象
      * @returns - 返回处理结果
      */
@@ -778,8 +832,13 @@ export class Router {
         for (const hook of this._hooks.onNotFound) {
             try {
                 const result = hook.call(this, target);
+                // 优先判断 RouteLocation（有 matched 和 path 属性）
+                if (isRouteLocation(result))
+                    return result;
+                // 判断 NavTarget（有 index 属性）
                 if (hasValidNavTarget(result))
                     return result;
+                // 字符串或 symbol 包装为 NavTarget
                 if (isString(result) || typeof result === 'symbol') {
                     return {
                         index: result
@@ -928,25 +987,6 @@ export class Router {
     // ============================================================
     // 路由匹配与URL构建
     // ============================================================
-    /**
-     * 创建缺失的路由
-     * @param component - 路由组件
-     * @param path - 路径
-     * @param query - 查询参数
-     * @param hash - 哈希值
-     * @returns {RouteLocation} - 返回创建的路由位置对象
-     */
-    createMissingRoute(component, path, query = {}, hash = '') {
-        return {
-            href: this.buildUrl(path, query, hash),
-            path,
-            hash,
-            params: {},
-            query,
-            meta: {},
-            matched: [{ path, isGroup: false, component: { default: component } }]
-        };
-    }
     /**
      * 构建完整URL路径
      *
@@ -977,7 +1017,7 @@ export class Router {
      */
     matchRoute(target, redirectFrom) {
         let matchTarget = target.index;
-        const isPath = hasValidPath(matchTarget);
+        const isPath = isValidPath(matchTarget);
         // 如果配置了后缀且目标是路径，则去除后缀
         if (this.config.suffix && isPath) {
             // 去除路径后缀
@@ -987,9 +1027,6 @@ export class Router {
         let match;
         if (isPath) {
             match = this.manager.matchByPath(matchTarget);
-            if (!match && this.config.missing) {
-                return this.createMissingRoute(this.config.missing, matchTarget, target.query, target.hash);
-            }
         }
         else {
             match = this.manager.matchByName(matchTarget, target.params);

package/dist/core/shared/link.js

@@ -1,5 +1,5 @@
 import { computed, isPlainObject, isString, logger } from 'vitarx';
-import { hasValidNavTarget, hasValidPath } from '../common/utils.js';
+import { hasValidNavTarget, isValidPath } from '../common/utils.js';
 import { useRouter } from './inject.js';
 import { cloneRouteLocation, parseQuery } from './utils.js';
 /**
@@ -104,7 +104,7 @@ export function useLink(props) {
         if (route.value?.href) {
             return route.value.href;
         }
-        if (isPlainObject(props.to) && hasValidPath(props.to.index)) {
+        if (isPlainObject(props.to) && isValidPath(props.to.index)) {
             return props.to.index;
         }
         if (isString(props.to)) {

package/dist/core/shared/utils.d.ts

@@ -1,5 +1,5 @@
 import { type DeepReadonly } from 'vitarx';
-import type { RouteLocation } from '../types/index.js';
+import type { NotFoundTarget, RouteLocation, RouteMetaData, RouteViewComponent } from '../types/index.js';
 /**
  * 将 query 字符串转为对象
  *
@@ -14,6 +14,17 @@ export declare function parseQuery(queryString: string): Record<string, string>;
  * @return {string} 转换后的查询字符串（如 ?key1=value1&key2=value2）
  */
 export declare function stringifyQuery(obj: Record<string, string>): `?${string}` | '';
+/**
+ * 去除路径末尾的斜杠
+ *
+ * @example
+ * removePathEndSlash('/foo/') // '/foo'
+ * removePathEndSlash('/foo') // '/foo'
+ *
+ * @param {string} str - 路径字符串
+ * @return {string} - 去除末尾斜杠后的路径字符串
+ */
+export declare function removePathEndSlash<T extends string>(str: T): T;
 /**
  * 归一化path
  *
@@ -38,3 +49,27 @@ export declare function normalizePath(path: string, removeEndSlash?: boolean): `
  * @return {RouteLocation} - 克隆过后的对象
  */
 export declare function cloneRouteLocation(route: RouteLocation | DeepReadonly<RouteLocation>): RouteLocation;
+/**
+ * 创建未匹配路由的 RouteLocation 对象
+ *
+ * 用于在 onNotFound 钩子中快速创建一个可渲染的 RouteLocation，
+ * 使路由匹配失败时仍能渲染指定组件（如 404 页面）。
+ *
+ * 该函数要求 target.index 必须为路径（以 `/` 开头），
+ * 因为名称导航（name-based）匹配失败属于编程错误，应直接抛出异常，
+ * 而非创建伪路由位置。
+ *
+ * @example
+ * ```ts
+ * // 在 onNotFound 钩子中使用
+ * onNotFound(target) {
+ *   return createMissingRoute(NotFoundPage, target, { title: '页面未找到' })
+ * }
+ * ```
+ *
+ * @param component - 未匹配时要渲染的组件
+ * @param target - 用户的原始导航意图（index 必须为路径）
+ * @param meta - 可选的自定义 meta 信息，默认为空对象
+ * @returns {RouteLocation} 可在 onNotFound 钩子中直接返回的 RouteLocation
+ */
+export declare function createMissingRoute(component: RouteViewComponent, target: NotFoundTarget, meta?: RouteMetaData): RouteLocation;

package/dist/core/shared/utils.js

@@ -25,6 +25,21 @@ export function stringifyQuery(obj) {
     // 如果对象为空或没有任何有效查询参数，返回空字符串
     return queryString ? `?${queryString}` : '';
 }
+/**
+ * 去除路径末尾的斜杠
+ *
+ * @example
+ * removePathEndSlash('/foo/') // '/foo'
+ * removePathEndSlash('/foo') // '/foo'
+ *
+ * @param {string} str - 路径字符串
+ * @return {string} - 去除末尾斜杠后的路径字符串
+ */
+export function removePathEndSlash(str) {
+    if (str === '/')
+        return str;
+    return str.endsWith('/') ? str.slice(0, -1) : str;
+}
 /**
  * 归一化path
  *
@@ -44,8 +59,8 @@ export function stringifyQuery(obj) {
 export function normalizePath(path, removeEndSlash = false) {
     // 去除所有空格 处理重复//
     let normalizedPath = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
-    if (removeEndSlash && normalizedPath.endsWith('/') && normalizedPath !== '/') {
-        normalizedPath = normalizedPath.replace(/\/$/, '');
+    if (removeEndSlash) {
+        normalizedPath = removePathEndSlash(normalizedPath);
     }
     // 去除尾随斜杠
     return normalizedPath;
@@ -60,3 +75,41 @@ export function cloneRouteLocation(route) {
     const { matched, ...rest } = toRaw(route);
     return Object.assign(deepClone(rest), { matched: Array.from(matched) });
 }
+/**
+ * 创建未匹配路由的 RouteLocation 对象
+ *
+ * 用于在 onNotFound 钩子中快速创建一个可渲染的 RouteLocation，
+ * 使路由匹配失败时仍能渲染指定组件（如 404 页面）。
+ *
+ * 该函数要求 target.index 必须为路径（以 `/` 开头），
+ * 因为名称导航（name-based）匹配失败属于编程错误，应直接抛出异常，
+ * 而非创建伪路由位置。
+ *
+ * @example
+ * ```ts
+ * // 在 onNotFound 钩子中使用
+ * onNotFound(target) {
+ *   return createMissingRoute(NotFoundPage, target, { title: '页面未找到' })
+ * }
+ * ```
+ *
+ * @param component - 未匹配时要渲染的组件
+ * @param target - 用户的原始导航意图（index 必须为路径）
+ * @param meta - 可选的自定义 meta 信息，默认为空对象
+ * @returns {RouteLocation} 可在 onNotFound 钩子中直接返回的 RouteLocation
+ */
+export function createMissingRoute(component, target, meta) {
+    const path = target.index;
+    const query = target.query ?? {};
+    const hash = target.hash ?? '';
+    const params = target.params ?? {};
+    return {
+        href: path,
+        path,
+        hash,
+        params,
+        query,
+        meta: meta || {},
+        matched: [{ path, isGroup: false, component: { default: component } }]
+    };
+}

package/dist/core/types/hooks.d.ts

@@ -1,6 +1,6 @@
 import type { Router } from '../router/router.js';
 import type { NavTarget, RouteLocation } from './navigation.js';
-import type { RouteIndex } from './route.js';
+import type { RouteIndex, RoutePath } from './route.js';
 /**
  * 守卫结果
  *
@@ -32,17 +32,26 @@ export type NavigationGuard = (this: Router, to: RouteLocation, from: RouteLocat
  * @param from - 上一个路由对象
  */
 export type AfterCallback = (this: Router, to: RouteLocation, from: RouteLocation) => void;
+/**
+ * 未匹配路由目标类型
+ */
+export type NotFoundTarget = NavTarget<RoutePath>;
 /**
  * 路由未匹配钩子
  *
  * 触发时机: 路由匹配失败 (404) 时。
- * 用途: 可用于统一跳转 404 页面或记录错误日志。
+ * 用途: 可用于统一跳转 404 页面、渲染 404 组件或记录错误日志。
+ *
+ * 返回值说明:
+ * - NavTarget | RouteIndex: 重定向到新目标
+ * - RouteLocation: 作为未匹配路由的位置对象（可配合 createMissingRoute 使用）
+ * - void: 不处理，返回 notfound 状态
  *
  * @param this - 路由器实例
  * @param target - 用户的原始导航意图
- * @returns {NavTarget | RouteIndex | void} 返回新目标表示重定向，无返回值则抛出错误
+ * @returns {NavTarget | RouteIndex | RouteLocation | void} 返回新目标表示重定向，返回 RouteLocation 表示渲染指定组件，无返回值则返回 notfound 状态
  */
-export type NotFoundHandler = (this: Router, target: NavTarget) => NavTarget | RouteIndex | void;
+export type NotFoundHandler = (this: Router, target: NotFoundTarget) => NavTarget | RouteIndex | RouteLocation | void;
 /**
  * 路由错误处理钩子
  *

package/dist/core/types/options.d.ts

@@ -1,7 +1,7 @@
 import type { MakeRequired } from 'vitarx';
 import type { RouteManager } from '../router/manager.js';
 import type { AfterCallback, NavErrorListener, NavigationGuard, NotFoundHandler } from './hooks.js';
-import type { InjectPropsHandler, Route, RouteViewComponent } from './route.js';
+import type { InjectPropsHandler, Route } from './route.js';
 import type { BeforeScrollCallback } from './scroll.js';
 /**
  * 定义路由器配置选项接口
@@ -87,14 +87,5 @@ export interface RouterOptions {
      * @param from - 源路由对象
      */
     onError?: NavErrorListener | NavErrorListener[];
-    /**
-     * 未匹配到路由时要渲染的组件
-     *
-     * 如果你需要在未匹配到路由时重定向到指定的页面，则不应该使用`missing`选项，
-     * 而是应该使用 `onNotFound` 钩子指定重定向目标。
-     *
-     * > 注意：如果你设置了`missing`选项，`path` 导航不匹配时也会更新`URL`地址，然后渲染`missing`组件。
-     */
-    missing?: RouteViewComponent;
 }
 export type ResolvedRouterConfig = MakeRequired<Omit<RouterOptions, 'routes' | 'beforeEach' | 'afterEach' | 'onError' | 'onNotFound'>, 'mode' | 'base'>;

package/dist/file-router/macros/astValueExtractor.js

@@ -23,7 +23,11 @@ function extractAstLiteralValue(node) {
             for (const prop of node.properties) {
                 if (prop.type !== 'ObjectProperty')
                     continue;
-                const key = prop.key.type === 'Identifier' ? prop.key.name : null;
+                const key = prop.key.type === 'Identifier'
+                    ? prop.key.name
+                    : prop.key.type === 'StringLiteral'
+                        ? prop.key.value
+                        : null;
                 if (key) {
                     obj[key] = extractAstLiteralValue(prop.value);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.22",
+  "version": "4.0.0-beta.24",
   "description": "Official routing solution for Vitarx framework with declarative routing, navigation guards, dynamic routes, file-based routing with HMR, and full TypeScript support.",
   "author": "ZhuChonglin <8210856@qq.com>",
   "license": "MIT",