vitarx-router 4.0.0-beta.21 → 4.0.0-beta.23

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('/');
 }
 /**
@@ -71,7 +81,7 @@ export function parseHashContent(hashContent) {
     // 同样限制分割数为 2，防止路径中包含 ?
     const [pathname, queryString] = pathAndQuery.split('?', 2);
     // 3. 格式化路径
-    path = normalizePath(pathname || '/');
+    path = pathname ? normalizePath(pathname) : '/';
     // 4. 解析查询参数
     if (queryString) {
         query = parseQuery(queryString);

package/dist/core/common/variable.js

@@ -97,7 +97,7 @@ export function mergePathVariable(path, params) {
         return String(value).replace(/\s+/g, '_');
     });
     // 使用 formatPath 处理可能出现的双斜杠 (如 /user//) 或首尾斜杠问题
-    return normalizePath(fullPath);
+    return normalizePath(fullPath, true);
 }
 /**
  * 合并两个路由模式对象

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.d.ts

@@ -9,7 +9,9 @@ export interface RouteManagerOptions {
     /**
      * 是否启用严格模式
      *
-     * 启用后路径匹配将严格匹配，即路径末尾的斜杠会被视为重要字符
+     * 启用后路径匹配将严格匹配即 /user/ 结尾存在斜杠会匹配失败
+     *
+     * 禁用后路径匹配将宽匹配即 /user/ 会匹配 /user
      *
      * @default false
      */
@@ -23,8 +25,8 @@ export interface RouteManagerOptions {
     /**
      * 是否启用索引回退匹配。
      *
-     * 开启后，当访问深层路径（如 /user/index）未匹配时，
-     * 会尝试移除最后一段路径（/user）再次进行匹配。
+     * 开启后，当访问深层index路径（如 /user/index）未匹配时，
+     * 会尝试移除index路径（/user）再次进行匹配。
      * 匹配成功则渲染组件，且保持 URL 不变。
      *
      * 仅支持匹配静态路径，不做动态路径匹配！
@@ -126,7 +128,7 @@ export declare class RouteManager {
      * @returns 规范化后的路径（根据 ignoreCase 配置转换为小写）
      * @private
      */
-    private normalizePath;
+    private toLookupPath;
     /**
      * 根据路径查找路由
      *

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';
 /**
@@ -127,7 +127,7 @@ export class RouteManager {
      * @returns 规范化后的路径（根据 ignoreCase 配置转换为小写）
      * @private
      */
-    normalizePath(path) {
+    toLookupPath(path) {
         return this.config.ignoreCase ? path.toLowerCase() : path;
     }
     /**
@@ -137,7 +137,7 @@ export class RouteManager {
      * @returns 路由记录对象，如果未找到则返回 undefined
      */
     findByPath(path) {
-        const normalizedPath = this.normalizePath(path);
+        const normalizedPath = this.toLookupPath(path);
         return this.staticRoutes.get(normalizedPath) ?? this.aliasRoutes.get(normalizedPath) ?? null;
     }
     /**
@@ -183,9 +183,7 @@ export class RouteManager {
             normalizedPath = normalizedPath.slice(0, -1);
         }
         // 1. 标准化路径
-        const lookupPath = this.config.ignoreCase
-            ? normalizedPath.toLowerCase()
-            : normalizedPath;
+        const lookupPath = this.toLookupPath(normalizedPath);
         // 2. 静态路由精确匹配
         const staticRoute = this.staticRoutes.get(lookupPath);
         if (staticRoute) {
@@ -197,14 +195,14 @@ export class RouteManager {
             return { path, route: aliasRoute, params: {} };
         }
         // 3. 动态路由匹配
-        const pathSegments = normalizedPath.split('/').filter(Boolean);
+        const pathSegments = path.split('/').filter(Boolean);
         const segmentCount = pathSegments.length;
         const dynamicCandidates = this.dynamicRoutes.get(segmentCount);
         if (dynamicCandidates) {
             for (const { regex, route } of dynamicCandidates) {
                 regex.lastIndex = 0;
                 // 执行正则匹配
-                const regexResult = regex.exec(normalizedPath);
+                const regexResult = regex.exec(path);
                 if (regexResult) {
                     const params = {};
                     // 解析捕获组参数
@@ -222,6 +220,7 @@ export class RouteManager {
                 }
             }
         }
+        // 4. 结尾斜杠索引回退匹配
         if (lookupPath.endsWith('/index') && this.config.fallbackIndex) {
             const fallbackPath = lookupPath.slice(0, -6);
             const fallbackRoute = this.staticRoutes.get(fallbackPath || '/');
@@ -289,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);
@@ -354,14 +353,14 @@ export class RouteManager {
         // 删除当前路由
         this.routes.delete(route);
         // 删除静态路由映射
-        this.staticRoutes.delete(this.normalizePath(route.path));
+        this.staticRoutes.delete(this.toLookupPath(route.path));
         // 删除命名路由映射
         if (route.name)
             this.namedRoutes.delete(route.name);
         // 删除别名映射
         if (route.aliases) {
             for (const alias of route.aliases) {
-                this.aliasRoutes.delete(this.normalizePath(alias));
+                this.aliasRoutes.delete(this.toLookupPath(alias));
                 // 如果别名是动态路由，也需要从 dynamicRoutes 中移除
                 if (isVariablePath(alias)) {
                     this.removeAliasDynamicRoute(alias, route);
@@ -462,7 +461,7 @@ export class RouteManager {
             record.parent = parent;
         }
         const rawPath = route.path.trim();
-        record.path = normalizePath(parent ? `${parent.path}/${rawPath}` : `/${rawPath}`);
+        record.path = normalizePath(parent ? `${parent.path}/${rawPath}` : `/${rawPath}`, true);
         if (route.name) {
             record.name = route.name;
         }
@@ -513,13 +512,13 @@ export class RouteManager {
                     aliasPath = parent.path;
                 }
                 else if (rawAlias.startsWith('/')) {
-                    aliasPath = normalizePath(rawAlias);
+                    aliasPath = normalizePath(rawAlias, true);
                 }
                 else if (!parent) {
-                    aliasPath = normalizePath(`/${rawAlias}`);
+                    aliasPath = normalizePath(`/${rawAlias}`, true);
                 }
                 else {
-                    aliasPath = normalizePath(`${parent.path}/${rawAlias}`);
+                    aliasPath = normalizePath(`${parent.path}/${rawAlias}`, true);
                 }
                 record.aliases.push(aliasPath);
             }
@@ -552,7 +551,7 @@ export class RouteManager {
             this.registerDynamicRoute(route, route.fullPattern);
         }
         else {
-            const path = this.normalizePath(route.path);
+            const path = this.toLookupPath(route.path);
             // 检查是否已存在相同路径的路由
             if (this.staticRoutes.has(path)) {
                 // 抛出错误：检测到重复的路由路径
@@ -564,7 +563,6 @@ export class RouteManager {
         // 注册别名
         if (route.aliases && route.aliases.length > 0) {
             for (const alias of route.aliases) {
-                const aliasPath = this.normalizePath(alias);
                 if (isVariablePath(alias)) {
                     if (!validateAliasVariables(route.pattern, alias)) {
                         throw new Error(`[Router] Alias "${alias}" variables do not match route "${route.path}" pattern`);
@@ -573,6 +571,7 @@ export class RouteManager {
                     this.registerDynamicRoute(route, regex, alias);
                 }
                 else {
+                    const aliasPath = this.toLookupPath(alias);
                     if (route.pattern && route.pattern.length > 0) {
                         throw new Error(`[Router] Alias "${alias}" for dynamic route "${route.path}" must contain variables`);
                     }

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

@@ -319,13 +319,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 +448,16 @@ export declare abstract class Router {
     private runScrollBehavior;
     /**
      * 处理 404 错误
+     *
+     * 执行 onNotFound 钩子链，按注册顺序依次调用，
+     * 第一个返回有效值的钩子会终止遍历。
+     *
+     * 返回值类型：
+     * - RouteLocation: 作为未匹配路由的位置对象（优先判断，因为结构更具体）
+     * - NavTarget: 重定向到新目标
+     * - string | symbol: 包装为 NavTarget 后重定向
+     * - void: 继续执行下一个钩子
+     *
      * @param target - 导航目标对象
      * @returns - 返回处理结果
      */
@@ -487,15 +508,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';
@@ -430,6 +430,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 +480,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 +726,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 +799,16 @@ export class Router {
     // ============================================================
     /**
      * 处理 404 错误
+     *
+     * 执行 onNotFound 钩子链，按注册顺序依次调用，
+     * 第一个返回有效值的钩子会终止遍历。
+     *
+     * 返回值类型：
+     * - RouteLocation: 作为未匹配路由的位置对象（优先判断，因为结构更具体）
+     * - NavTarget: 重定向到新目标
+     * - string | symbol: 包装为 NavTarget 后重定向
+     * - void: 继续执行下一个钩子
+     *
      * @param target - 导航目标对象
      * @returns - 返回处理结果
      */
@@ -778,8 +818,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 +973,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路径
      *
@@ -965,7 +991,7 @@ export class Router {
         const queryStr = stringifyQuery(query);
         const href = `${path}${queryStr}${hashStr}`;
         return this.config.mode === 'hash'
-            ? normalizePath(`${this.config.base}/#${href}`, true)
+            ? normalizePath(`${this.config.base}#${href}`)
             : normalizePath(`${this.config.base}${href}`);
     }
     /**
@@ -977,7 +1003,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 +1013,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)) {
@@ -130,7 +130,7 @@ export function useLink(props) {
         const matchedRoute = route.value;
         if (!matchedRoute)
             return false;
-        return router.route.href === matchedRoute.href;
+        return router.route.path === matchedRoute.path;
     });
     /**
      * 导航处理函数

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,22 +14,34 @@ 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
  *
- * 去除所有空格、替换重复的斜杠、去除尾部的斜杠
+ * 去除所有空格、替换重复的斜杠
  *
  * @example
  * normalizePath('/  foo') // '/foo'
- * normalizePath('/foo/') // '/foo'
+ * normalizePath('/foo/') // '/foo/'
  * normalizePath('/foo/bar') // '/foo/bar'
  * normalizePath('foo/') // '/foo'
+ * normalizePath('/foo/',true) // '/foo'
  *
  * @param {string} path - 路径字符串
- * @param [hashMode = false] -  是否为hash模式，如果是则兼容`/#/`
+ * @param {boolean} removeEndSlash - 是否去除尾随斜杠
  * @return {string} - 格式化后的路径字符串
  */
-export declare function normalizePath(path: string, hashMode?: boolean): `/${string}`;
+export declare function normalizePath(path: string, removeEndSlash?: boolean): `/${string}`;
 /**
  * 克隆路由位置对象
  *
@@ -37,3 +49,27 @@ export declare function normalizePath(path: string, hashMode?: boolean): `/${str
  * @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,27 +25,45 @@ 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
  *
- * 去除所有空格、替换重复的斜杠、去除尾部的斜杠
+ * 去除所有空格、替换重复的斜杠
  *
  * @example
  * normalizePath('/  foo') // '/foo'
- * normalizePath('/foo/') // '/foo'
+ * normalizePath('/foo/') // '/foo/'
  * normalizePath('/foo/bar') // '/foo/bar'
  * normalizePath('foo/') // '/foo'
+ * normalizePath('/foo/',true) // '/foo'
  *
  * @param {string} path - 路径字符串
- * @param [hashMode = false] -  是否为hash模式，如果是则兼容`/#/`
+ * @param {boolean} removeEndSlash - 是否去除尾随斜杠
  * @return {string} - 格式化后的路径字符串
  */
-export function normalizePath(path, hashMode = false) {
+export function normalizePath(path, removeEndSlash = false) {
     // 去除所有空格 处理重复//
-    const formated = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
-    if (formated === '/' || (hashMode && formated === '/#/'))
-        return formated;
-    return formated.replace(/\/$/, '');
+    let normalizedPath = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
+    if (removeEndSlash) {
+        normalizedPath = removePathEndSlash(normalizedPath);
+    }
+    // 去除尾随斜杠
+    return normalizedPath;
 }
 /**
  * 克隆路由位置对象
@@ -57,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.21",
+  "version": "4.0.0-beta.23",
   "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",