vitarx-router 4.0.0-beta.16 → 4.0.0-beta.18

package/README.md

@@ -423,20 +423,7 @@ export const router = createRouter({ routes })
 
 ### 文件路由配置选项
 
-| 选项               | 类型                                         | 默认值           | 说明       |
-|------------------|--------------------------------------------|---------------|----------|
-| `pages`          | `PageSource \| readonly PageSource[]`      | `'src/pages'` | 页面来源配置   |
-| `pathStrategy`   | `'kebab' \| 'lowercase' \| 'raw'`          | `'kebab'`     | 路径格式化策略  |
-| `importMode`     | `'lazy' \| 'sync' \| ImportModeFunction`   | `'lazy'`      | 组件导入模式   |
-| `injectImports`  | `readonly string[]`                        | -             | 自定义导入语句  |
-| `dts`            | `boolean \| string`                        | `false`       | 类型声明文件配置 |
-| `layoutFileName` | `string`                                   | `'_layout'`   | 布局文件名    |
-| `configFileName` | `string`                                   | `'_config'`   | 分组配置文件名  |
-| `transform`      | `CodeTransformHook`                        | -             | 代码转换钩子   |
-| `extendRoute`    | `ExtendRouteHook`                          | -             | 路由扩展钩子   |
-| `pathParser`     | `PathParser`                               | -             | 自定义路径解析器 |
-
-详细配置请参考 [File Router 文档](src/file-router/README.md)。
+请参考 [File Router 文档](src/file-router/README.md)。
 
 ## TypeScript 支持
 

package/dist/components/RouterView.js

@@ -29,7 +29,7 @@ export function RouterView(props) {
         const currentRoute = matchedRoute.value;
         if (!currentRoute)
             return null;
-        let injectProps = currentRoute.props?.[viewName.value] ?? router.config.props ?? false;
+        let injectProps = currentRoute.props?.[viewName.value] ?? router.config.props ?? true;
         if (injectProps === false)
             return null; // 如果属性为 false，返回null
         if (injectProps === true && currentRoute.pattern) {

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

@@ -70,6 +70,11 @@ export declare abstract class Router {
      * @private
      */
     private readonly _routeLocation;
+    /**
+     * 只读路由位置对象
+     * @private
+     */
+    private readonly _readonlyLocation;
     /**
      * 存储就绪状态的 Promise（延迟创建）
      * @private

package/dist/core/router/router.js

@@ -34,6 +34,16 @@ export class Router {
             writable: true,
             value: void 0
         });
+        /**
+         * 只读路由位置对象
+         * @private
+         */
+        Object.defineProperty(this, "_readonlyLocation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * 存储就绪状态的 Promise（延迟创建）
          * @private
@@ -159,12 +169,13 @@ export class Router {
             matched: shallowReactive([]),
             meta: shallowReactive({})
         });
+        this._readonlyLocation = readonly(this._routeLocation);
     }
     /**
      * 获取当前路由位置对象
      */
     get route() {
-        return readonly(this._routeLocation);
+        return this._readonlyLocation;
     }
     /**
      * 获取解析后的路由记录数组

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

@@ -48,6 +48,13 @@ export interface UseLinkReturn {
      */
     navigate: (e?: MouseEvent) => Promise<NavigateResult | void>;
 }
+/**
+ * 判断是否为外部链接
+ *
+ * @param href - 链接地址
+ * @returns 是否为外部链接
+ */
+export declare function isExternalLink(href: string): boolean;
 /**
  * 创建一个链接助手，用于处理路由导航、生成链接属性及判断激活状态。
  *

package/dist/core/shared/link.js

@@ -14,6 +14,15 @@ const handleTransition = async (callback) => {
     const transition = document.startViewTransition(callback);
     await transition.finished;
 };
+/**
+ * 判断是否为外部链接
+ *
+ * @param href - 链接地址
+ * @returns 是否为外部链接
+ */
+export function isExternalLink(href) {
+    return href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//');
+}
 /**
  * 创建一个链接助手，用于处理路由导航、生成链接属性及判断激活状态。
  *
@@ -31,7 +40,6 @@ const handleTransition = async (callback) => {
  */
 export function useLink(props) {
     const router = useRouter();
-    const httpRegex = /^(https?):\/\/[^\s\/$.?#].\S*$/i;
     /**
      * 计算属性：解析目标路由
      * @returns 返回解析后的路由位置对象，如果无效则返回 null
@@ -45,7 +53,7 @@ export function useLink(props) {
         }
         else if (isString(to)) {
             // 如果是 HTTP/HTTPS 链接则返回 null
-            if (httpRegex.test(to))
+            if (isExternalLink(to))
                 return null;
             target = { index: to };
         }
@@ -100,12 +108,7 @@ export function useLink(props) {
             return props.to.index;
         }
         if (isString(props.to)) {
-            if (httpRegex.test(props.to)) {
-                return props.to;
-            }
-            if (props.to.startsWith('/')) {
-                return props.to;
-            }
+            return props.to;
         }
         return 'javascript:void(0)';
     });

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

@@ -48,6 +48,8 @@ export interface RouterOptions {
      * 全局 props 注入配置
      *
      * 优先级低于 route 的 props 配置
+     *
+     * @default true
      */
     props?: boolean | InjectPropsHandler;
     /**

package/dist/file-router/generator/generateRoutes.js

@@ -62,7 +62,7 @@ function buildRouteNode(page, extendRoute, parent) {
         isGroup: page.isGroup,
         filePath: page.filePath,
         path: page.path,
-        fullPath: parent ? normalizeRoutePath(parent.fullPath + '/' + page.path) : page.path
+        fullPath: normalizeRoutePath(parent ? `${parent.fullPath}/${page.path}` : page.path)
     };
     // 处理组件配置
     if (page.components) {

package/dist/file-router/index.d.ts

@@ -10,8 +10,8 @@ import { type GenerateResult } from './generator/index.js';
 import { type FilterOptions } from './parser/index.js';
 import type { FileRouterOptions, ScanNode } from './types/index.js';
 export { resolvePageConfigs } from './config/resolve.js';
-export { mergePageOptions } from './macros/definePage.js';
 export * from './generator/index.js';
+export { mergePageOptions } from './macros/definePage.js';
 export type * from './types/index.js';
 export * from './utils/logger.js';
 /**
@@ -82,13 +82,71 @@ export declare class FileRouter {
     private processDir;
     /**
      * 处理文件
+     *
+     * 根据文件类型分发到对应的处理器。
+     *
      * @param filePath - 文件路径
      * @param page - 页面配置
-     * @param pageMapping - 子路由
+     * @param pageMapping - 同路径路由映射
      * @param parent - 父节点
      * @private
      */
     private processFile;
+    /**
+     * 解析文件信息与类型
+     *
+     * 统一入口，避免多处重复调用 extractFileInfo + getPageType。
+     *
+     * @param filePath - 文件路径
+     * @param page - 页面配置
+     * @returns 文件信息与类型
+     */
+    private resolveFile;
+    /**
+     * 处理分组配置文件
+     *
+     * 解析 definePage 宏并合并到父路由选项中。
+     *
+     * @param filePath - 文件路径
+     * @param parent - 父节点
+     */
+    private processConfigFile;
+    /**
+     * 处理分组布局文件
+     *
+     * 将布局组件注册到父路由的 components 中。
+     *
+     * @param filePath - 文件路径
+     * @param fileInfo - 文件信息
+     * @param parent - 父节点
+     */
+    private processLayoutFile;
+    /**
+     * 处理页面文件
+     *
+     * 解析路由路径、视图命名和页面选项，创建或合并路由节点。
+     *
+     * @param filePath - 文件路径
+     * @param fileInfo - 文件信息
+     * @param page - 页面配置
+     * @param pageMapping - 同路径路由映射
+     * @param parent - 父节点
+     * @param [precomputedParsed] - 预计算的解析结果，避免重复调用 parsePageFile
+     * @returns 新创建的路由节点，或 null（合并到已有路由时）
+     */
+    private processPageFile;
+    /**
+     * 在已有路由树中查找同路径路由
+     *
+     * 用于 addPage 场景：新增文件时需要检查是否已存在同路径的路由节点，
+     * 以便将命名视图合并到已有路由而非创建重复路由。
+     *
+     * @param pathKey - 标准化后的路由路径
+     * @param prefix - 路径前缀
+     * @param parent - 父节点
+     * @returns 同路径的路由节点，未找到返回 null
+     */
+    private findSameRoute;
     /**
      * 应用路径策略
      *
@@ -106,9 +164,9 @@ export declare class FileRouter {
      * 获取文件类型
      *
      * @param file - 文件绝对路径
-     * @param name - 文件名
-     * @param pages - 页面配置，默认为 `config.pages`
-     * @returns {string} - 文件类型，可选值有 `layout`、`config`、`page`、`ignore`
+     * @param rawName - 文件名（不含扩展名和 @视图命名）
+     * @param pages - 页面配置
+     * @returns 文件类型
      */
     private getPageType;
     /**
@@ -119,6 +177,16 @@ export declare class FileRouter {
      * @returns {boolean} - 是否为页面文件
      */
     isPageFile(file: string, filter?: FilterOptions | readonly FilterOptions[]): boolean;
+    /**
+     * 获取文件的完整路由路径
+     *
+     * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+     * 非页面文件（布局文件、配置文件等）返回 null。
+     *
+     * @param filePath - 文件绝对路径
+     * @returns 完整路由路径，非页面文件返回 null
+     */
+    getRouteFullPath(filePath: string): string | null;
     /**
      * 写入类型定义文件
      */
@@ -147,7 +215,10 @@ export declare class FileRouter {
     /**
      * 添加页面文件
      *
-     * @param filePath
+     * 根据文件类型直接调用对应处理器，避免重复类型判断和文件解析。
+     *
+     * @param filePath - 文件路径
+     * @returns 是否创建了新的路由节点
      */
     addPage(filePath: string): boolean;
     /**

package/dist/file-router/index.js

@@ -16,11 +16,12 @@ import { resolveConfig } from './config/index.js';
 import { generateRoutes } from './generator/index.js';
 import { isEqualPageOptions, mergePageOptions, parseDefinePage, removeDefinePage } from './macros/index.js';
 import { checkDefaultExport, isPageFile, isPageFileInDirs } from './parser/index.js';
-import { parsePageFile } from './parser/parsePage.js';
+import { extractFileInfo, parsePageFile } from './parser/parsePage.js';
+import { computeRouteFullPath } from './parser/routePath.js';
 import { applyPathStrategy, info, normalizePathSeparator, readFileContent, resolvePathVariable, validateOptions, warn } from './utils/index.js';
 export { resolvePageConfigs } from './config/resolve.js';
-export { mergePageOptions } from './macros/definePage.js';
 export * from './generator/index.js';
+export { mergePageOptions } from './macros/definePage.js';
 export * from './utils/logger.js';
 /**
  * 文件路由管理器
@@ -189,66 +190,112 @@ export class FileRouter {
     }
     /**
      * 处理文件
+     *
+     * 根据文件类型分发到对应的处理器。
+     *
      * @param filePath - 文件路径
      * @param page - 页面配置
-     * @param pageMapping - 子路由
+     * @param pageMapping - 同路径路由映射
      * @param parent - 父节点
      * @private
      */
     processFile(filePath, page, pageMapping, parent) {
-        // 分离出路由 path 和视图命名
-        const { path, viewName = 'default', options } = parsePageFile(filePath, this.config.pageParser);
-        const fileType = this.getPageType(filePath, path, page);
-        if (fileType === 'ignore')
-            return null;
-        // 处理分组配置文件
-        if (fileType === 'config') {
-            if (!parent)
+        const { fileInfo, fileType } = this.resolveFile(filePath, page);
+        switch (fileType) {
+            case 'ignore':
                 return null;
-            const content = this.readFile(filePath);
-            const pageOptions = parseDefinePage(content, filePath);
-            if (pageOptions) {
-                parent.options = mergePageOptions(parent.options, pageOptions);
-                parent.dirConfigFile = filePath;
-                this.fileMap.set(filePath, parent);
-            }
-            return null;
-        }
-        // 处理分组布局文件
-        if (fileType === 'layout') {
-            if (!parent)
+            case 'config':
+                this.processConfigFile(filePath, parent);
                 return null;
-            const content = this.readFile(filePath);
-            if (checkDefaultExport(content, filePath)) {
-                parent.components ?? (parent.components = {});
-                parent.components[viewName] = filePath;
-            }
+            case 'layout':
+                this.processLayoutFile(filePath, fileInfo, parent);
+                return null;
+            case 'page':
+                return this.processPageFile(filePath, fileInfo, page, pageMapping, parent);
+        }
+    }
+    /**
+     * 解析文件信息与类型
+     *
+     * 统一入口，避免多处重复调用 extractFileInfo + getPageType。
+     *
+     * @param filePath - 文件路径
+     * @param page - 页面配置
+     * @returns 文件信息与类型
+     */
+    resolveFile(filePath, page) {
+        const fileInfo = extractFileInfo(filePath);
+        const fileType = this.getPageType(filePath, fileInfo.rawName, page);
+        return { fileInfo, fileType };
+    }
+    /**
+     * 处理分组配置文件
+     *
+     * 解析 definePage 宏并合并到父路由选项中。
+     *
+     * @param filePath - 文件路径
+     * @param parent - 父节点
+     */
+    processConfigFile(filePath, parent) {
+        if (!parent)
+            return;
+        const content = this.readFile(filePath);
+        const pageOptions = parseDefinePage(content, filePath);
+        if (pageOptions) {
+            parent.options = mergePageOptions(parent.options, pageOptions);
+            parent.dirConfigFile = filePath;
             this.fileMap.set(filePath, parent);
-            return null;
         }
-        // 读取文件内容
+    }
+    /**
+     * 处理分组布局文件
+     *
+     * 将布局组件注册到父路由的 components 中。
+     *
+     * @param filePath - 文件路径
+     * @param fileInfo - 文件信息
+     * @param parent - 父节点
+     */
+    processLayoutFile(filePath, fileInfo, parent) {
+        if (!parent)
+            return;
         const content = this.readFile(filePath);
-        // 处理同名路由
-        const sameRoute = pageMapping.get(path);
+        if (checkDefaultExport(content, filePath)) {
+            parent.components ?? (parent.components = {});
+            parent.components[fileInfo.viewName ?? 'default'] = filePath;
+        }
+        this.fileMap.set(filePath, parent);
+    }
+    /**
+     * 处理页面文件
+     *
+     * 解析路由路径、视图命名和页面选项，创建或合并路由节点。
+     *
+     * @param filePath - 文件路径
+     * @param fileInfo - 文件信息
+     * @param page - 页面配置
+     * @param pageMapping - 同路径路由映射
+     * @param parent - 父节点
+     * @param [precomputedParsed] - 预计算的解析结果，避免重复调用 parsePageFile
+     * @returns 新创建的路由节点，或 null（合并到已有路由时）
+     */
+    processPageFile(filePath, fileInfo, page, pageMapping, parent, precomputedParsed) {
+        const parsed = precomputedParsed ?? parsePageFile(filePath, this.config.pageParser, fileInfo);
+        const viewName = parsed.viewName ?? 'default';
+        const content = this.readFile(filePath);
+        const sameRoute = pageMapping.get(parsed.path);
         if (sameRoute) {
             if (!checkDefaultExport(content, filePath))
                 return null;
-            // 添加命名组件
             sameRoute.components[viewName] = filePath;
-            // 更新文件映射表
             this.fileMap.set(filePath, sameRoute);
             return null;
         }
-        // 解析页面选项
         const definePageOptions = parseDefinePage(content, filePath);
-        // 合并页面选项
-        const pageOptions = mergePageOptions(options, definePageOptions);
-        // 忽略不具备默认导出，且无重定向配置的文件
+        const pageOptions = mergePageOptions(parsed.options, definePageOptions);
         if (!pageOptions.redirect && !checkDefaultExport(content, filePath))
             return null;
-        // 最终 path
-        const finalPath = this.applyPathStrategy((parent ? '' : page.prefix) + (path === 'index' ? '' : path));
-        // 创建路由对象
+        const finalPath = this.applyPathStrategy((parent ? '' : page.prefix) + (parsed.path === 'index' ? '' : parsed.path));
         const route = {
             isGroup: false,
             parent,
@@ -258,13 +305,31 @@ export class FileRouter {
                 [viewName]: filePath
             }
         };
-        // 添加页面选项
         if (Object.keys(pageOptions).length)
             route.options = pageOptions;
-        // 添加到子路由映射中
-        pageMapping.set(path, route);
+        pageMapping.set(parsed.path, route);
         return route;
     }
+    /**
+     * 在已有路由树中查找同路径路由
+     *
+     * 用于 addPage 场景：新增文件时需要检查是否已存在同路径的路由节点，
+     * 以便将命名视图合并到已有路由而非创建重复路由。
+     *
+     * @param pathKey - 标准化后的路由路径
+     * @param prefix - 路径前缀
+     * @param parent - 父节点
+     * @returns 同路径的路由节点，未找到返回 null
+     */
+    findSameRoute(pathKey, prefix, parent) {
+        const newRoutePath = this.applyPathStrategy(prefix + pathKey);
+        const pages = parent ? parent.children : this.nodeTree;
+        for (const route of pages) {
+            if (route.path === newRoutePath)
+                return route;
+        }
+        return null;
+    }
     /**
      * 应用路径策略
      *
@@ -286,15 +351,15 @@ export class FileRouter {
      * 获取文件类型
      *
      * @param file - 文件绝对路径
-     * @param name - 文件名
-     * @param pages - 页面配置，默认为 `config.pages`
-     * @returns {string} - 文件类型，可选值有 `layout`、`config`、`page`、`ignore`
+     * @param rawName - 文件名（不含扩展名和 @视图命名）
+     * @param pages - 页面配置
+     * @returns 文件类型
      */
-    getPageType(file, name, pages) {
-        if (name === this.config.layoutFileName) {
+    getPageType(file, rawName, pages) {
+        if (rawName === this.config.layoutFileName) {
             return 'layout';
         }
-        if (name === this.config.configFileName && (file.endsWith('.ts') || file.endsWith('.js'))) {
+        if (rawName === this.config.configFileName && (file.endsWith('.ts') || file.endsWith('.js'))) {
             return 'config';
         }
         if (this.isPageFile(file, pages)) {
@@ -320,6 +385,29 @@ export class FileRouter {
         }
         return !!isPageFileInDirs(file, this.config.pages);
     }
+    /**
+     * 获取文件的完整路由路径
+     *
+     * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+     * 非页面文件（布局文件、配置文件等）返回 null。
+     *
+     * @param filePath - 文件绝对路径
+     * @returns 完整路由路径，非页面文件返回 null
+     */
+    getRouteFullPath(filePath) {
+        if (!this.isPageFile(filePath))
+            return null;
+        const fileInfo = extractFileInfo(filePath);
+        const fileType = this.getPageType(filePath, fileInfo.rawName);
+        if (fileType !== 'page')
+            return null;
+        return computeRouteFullPath(filePath, fileInfo, {
+            fileMap: this.fileMap,
+            pages: this.config.pages,
+            pageParser: this.config.pageParser,
+            pathStrategy: this.config.pathStrategy
+        });
+    }
     /**
      * 写入类型定义文件
      */
@@ -376,44 +464,49 @@ export class FileRouter {
     /**
      * 添加页面文件
      *
-     * @param filePath
+     * 根据文件类型直接调用对应处理器，避免重复类型判断和文件解析。
+     *
+     * @param filePath - 文件路径
+     * @returns 是否创建了新的路由节点
      */
     addPage(filePath) {
         const page = isPageFileInDirs(filePath, this.config.pages);
         if (!page)
             return false;
-        // 分离出路由 path 和视图命名
-        const { path, viewName } = parsePageFile(filePath, this.config.pageParser);
         const dirPath = nodePath.dirname(filePath);
         const parent = this.fileMap.get(dirPath);
-        const pageMapping = new Map();
         const prefix = parent ? '' : page.prefix;
-        // 如果是命名文件，则先查找是否存在同名路由，存在则添加到同名路由的 children 中
-        if (viewName) {
-            const pages = parent ? parent.children : this.nodeTree;
-            const newRoutePath = this.applyPathStrategy(prefix + path);
-            let sameRoute = null;
-            for (const route of pages) {
-                if (route.path === newRoutePath) {
-                    sameRoute = route;
-                    break;
-                }
-            }
-            if (sameRoute) {
-                pageMapping.set(path, sameRoute);
-            }
-        }
-        const route = this.processFile(filePath, {
+        const { fileInfo, fileType } = this.resolveFile(filePath, page);
+        const pageConfig = {
             dir: dirPath,
             include: page.include,
             exclude: page.exclude,
             prefix
-        }, pageMapping, parent);
-        if (route) {
-            this.fileMap.set(filePath, route);
-            return true;
+        };
+        switch (fileType) {
+            case 'ignore':
+                return false;
+            case 'config':
+                this.processConfigFile(filePath, parent);
+                return false;
+            case 'layout':
+                this.processLayoutFile(filePath, fileInfo, parent);
+                return false;
+            case 'page': {
+                const parsed = parsePageFile(filePath, this.config.pageParser, fileInfo);
+                const pageMapping = new Map();
+                const sameRoute = this.findSameRoute(parsed.path, prefix, parent);
+                if (sameRoute) {
+                    pageMapping.set(parsed.path, sameRoute);
+                }
+                const route = this.processPageFile(filePath, fileInfo, pageConfig, pageMapping, parent, parsed);
+                if (route) {
+                    this.fileMap.set(filePath, route);
+                    return true;
+                }
+                return false;
+            }
         }
-        return false;
     }
     /**
      * 移除指定的文件或目录

package/dist/file-router/parser/filterUtils.js

@@ -20,8 +20,7 @@ export function isPageFile(file, options) {
     const { dir, include, exclude } = options;
     if (!file.startsWith(dir))
         return false;
-    const relativePath = path.relative(dir, file);
-    const normalizedPath = normalizePathSeparator(relativePath);
+    const normalizedPath = normalizePathSeparator(path.relative(dir, file));
     if (include.length === 0)
         return true;
     return micromatch.isMatch(normalizedPath, include, { dot: true, noext: true, ignore: exclude });

package/dist/file-router/parser/parsePage.d.ts

@@ -29,7 +29,31 @@ export declare class PageParseError extends TypeError {
  *
  * @param filePath - 文件路径
  * @param [parser] - 自定义解析器
- * @returns 路由路径和视图名称
+ * @param [precomputed] - 预计算的文件信息，避免重复解析文件路径
+ * @returns 路径解析结果
  * @throws {PageParseError} 当路径解析失败时抛出
  */
-export declare function parsePageFile(filePath: string, parser?: PageParser): PageParseResult;
+export declare function parsePageFile(filePath: string, parser?: PageParser, precomputed?: FileInfo): PageParseResult;
+/**
+ * 文件信息
+ *
+ * 从文件路径中提取的结构化信息，作为文件名解析的唯一来源。
+ */
+export interface FileInfo {
+    /** 文件名（不含扩展名），如 home@sidebar → home@sidebar */
+    basename: string;
+    /** 路由名（@之前的部分），如 home@sidebar → home */
+    rawName: string;
+    /** 视图名称（@之后的部分），如 home@sidebar → sidebar */
+    viewName: string | undefined;
+}
+/**
+ * 提取文件信息
+ *
+ * 从文件路径中提取文件名、路由名和视图名称。
+ * 这是文件名解析的唯一入口，其他模块应复用此函数而非重复实现。
+ *
+ * @param filePath - 文件路径
+ * @returns 文件信息
+ */
+export declare function extractFileInfo(filePath: string): FileInfo;

package/dist/file-router/parser/parsePage.js

@@ -68,41 +68,46 @@ export class PageParseError extends TypeError {
  *
  * @param filePath - 文件路径
  * @param [parser] - 自定义解析器
- * @returns 路由路径和视图名称
+ * @param [precomputed] - 预计算的文件信息，避免重复解析文件路径
+ * @returns 路径解析结果
  * @throws {PageParseError} 当路径解析失败时抛出
  */
-export function parsePageFile(filePath, parser) {
-    const { basename } = extractFileInfo(filePath);
+export function parsePageFile(filePath, parser, precomputed) {
+    const info = precomputed ?? extractFileInfo(filePath);
     if (!parser) {
-        return defaultPageParser(basename);
+        return defaultPageParser(info.rawName, info.viewName);
     }
-    const result = parser(basename, filePath);
+    const result = parser(info.basename, filePath);
     return parseCustomResult(result, filePath);
 }
 /**
  * 提取文件信息
  *
+ * 从文件路径中提取文件名、路由名和视图名称。
+ * 这是文件名解析的唯一入口，其他模块应复用此函数而非重复实现。
+ *
  * @param filePath - 文件路径
- * @returns 文件基本信息
+ * @returns 文件信息
  */
-function extractFileInfo(filePath) {
+export function extractFileInfo(filePath) {
     const ext = path.extname(filePath);
     const basename = path.basename(filePath, ext);
-    return { basename, ext };
+    const [rawName, viewName] = basename.split('@', 2);
+    return { basename, rawName, viewName };
 }
 /**
  * 解析默认路由路径（无自定义解析器）
  *
- * @param basename - 文件基本名称
+ * @param rawName - 路由名（@之前的部分）
+ * @param viewName - 视图名称（@之后的部分）
  * @returns 解析结果
  */
-function defaultPageParser(basename) {
-    const [rawPath, viewName] = basename.split('@', 2);
-    const routePath = normalizeRoutePath(rawPath);
+function defaultPageParser(rawName, viewName) {
+    const routePath = normalizeRoutePath(rawName);
     if (!routePath) {
         throw new PageParseError('PageParser returned empty path', {
-            filePath: basename,
-            originalValue: rawPath,
+            filePath: rawName,
+            originalValue: rawName,
             field: 'path'
         });
     }
@@ -121,7 +126,8 @@ function defaultPageParser(basename) {
  */
 function parseCustomResult(result, filePath) {
     if (typeof result === 'string') {
-        return defaultPageParser(result);
+        const [rawName, viewName] = result.split('@', 2);
+        return defaultPageParser(rawName, viewName);
     }
     if (result && typeof result === 'object' && !Array.isArray(result)) {
         return parseObjectResult(result, filePath);

package/dist/file-router/parser/routePath.d.ts

@@ -0,0 +1,22 @@
+import { type PageDirConfig } from '../config/resolve.js';
+import type { PageParser, PathStrategy, ScanNode } from '../types/index.js';
+import { type FileInfo } from './parsePage.js';
+interface RouteFullPathContext {
+    fileMap: Map<string, ScanNode>;
+    pages: readonly PageDirConfig[];
+    pageParser?: PageParser;
+    pathStrategy: PathStrategy;
+}
+/**
+ * 计算文件的完整路由路径
+ *
+ * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+ * 非页面文件（布局文件、配置文件等）返回 null。
+ *
+ * @param filePath - 文件绝对路径
+ * @param fileInfo - 文件信息
+ * @param context - 路由计算上下文
+ * @returns 完整路由路径，非页面文件返回 null
+ */
+export declare function computeRouteFullPath(filePath: string, fileInfo: FileInfo, context: RouteFullPathContext): string | null;
+export {};

package/dist/file-router/parser/routePath.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview 路由路径计算辅助函数
+ *
+ * 从文件路径计算最终生成的路由 fullPath，
+ * 支持已跟踪（在路由树中）和未跟踪（尚未扫描）两种场景。
+ */
+import nodePath from 'node:path';
+import { applyPathStrategy } from '../utils/pathStrategy.js';
+import { normalizeRoutePath, resolvePathVariable } from '../utils/pathUtils.js';
+import { isPageFileInDirs } from './filterUtils.js';
+import { parsePageFile } from './parsePage.js';
+/**
+ * 应用路径策略（命名转换 + 动态参数转换）
+ *
+ * @param path - 路径
+ * @param strategy - 路径策略
+ * @returns 转换后的路径
+ */
+function applyFullPathStrategy(path, strategy) {
+    return resolvePathVariable(applyPathStrategy(path, strategy));
+}
+/**
+ * 从节点树计算完整路由路径
+ *
+ * 沿 parent 链向上拼接所有节点的 path，与生成阶段 fullPath 的计算逻辑一致。
+ *
+ * @param node - 路由节点
+ * @returns 完整路由路径
+ */
+function computeNodeFullPath(node) {
+    const segments = [];
+    let current = node;
+    while (current) {
+        segments.unshift(current.path);
+        current = current.parent;
+    }
+    return normalizeRoutePath(segments.join('/'));
+}
+/**
+ * 计算文件的完整路由路径
+ *
+ * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+ * 非页面文件（布局文件、配置文件等）返回 null。
+ *
+ * @param filePath - 文件绝对路径
+ * @param fileInfo - 文件信息
+ * @param context - 路由计算上下文
+ * @returns 完整路由路径，非页面文件返回 null
+ */
+export function computeRouteFullPath(filePath, fileInfo, context) {
+    const { fileMap, pages, pageParser, pathStrategy } = context;
+    const node = fileMap.get(filePath);
+    if (node) {
+        return computeNodeFullPath(node);
+    }
+    const page = isPageFileInDirs(filePath, pages);
+    if (!page)
+        return null;
+    const parsed = parsePageFile(filePath, pageParser, fileInfo);
+    const pathSegment = parsed.path === 'index' ? '' : applyFullPathStrategy(parsed.path, pathStrategy);
+    const segments = pathSegment ? [pathSegment] : [];
+    let dirPath = nodePath.dirname(filePath);
+    while (dirPath.length > page.dir.length) {
+        const dirNode = fileMap.get(dirPath);
+        if (dirNode) {
+            const parentFullPath = computeNodeFullPath(dirNode);
+            return normalizeRoutePath(parentFullPath + '/' + segments.join('/'));
+        }
+        segments.unshift(applyFullPathStrategy(nodePath.basename(dirPath), pathStrategy));
+        dirPath = nodePath.dirname(dirPath);
+    }
+    const prefix = page.prefix ? applyFullPathStrategy(page.prefix, pathStrategy) : '';
+    return normalizeRoutePath(prefix + '/' + segments.join('/'));
+}

package/dist/file-router/types/options.d.ts

@@ -54,7 +54,7 @@ export type PageSource = string | PageDirOptions;
 /**
  * 路径解析结果
  */
-export type PageParseResult = {
+export interface PageParseResult {
     /** 解析后的路径 如：home.jsx -> 'home' */
     path: string;
     /**
@@ -63,7 +63,7 @@ export type PageParseResult = {
     options?: PageOptions;
     /** 视图名称 如：home.nav.jsx -> 'nav' */
     viewName?: string;
-};
+}
 /**
  * 路径解析器
  *

package/dist/file-router/utils/findRoute.d.ts

@@ -0,0 +1,8 @@
+import type { RouteNode } from '../types/index.js';
+/**
+ * 查找路由
+ *
+ * @param routes - 路由列表
+ * @param path - 路径
+ */
+export declare function findRoute(routes: RouteNode[], path: string): RouteNode | null;

package/dist/file-router/utils/findRoute.js

@@ -0,0 +1,22 @@
+/**
+ * 查找路由
+ *
+ * @param routes - 路由列表
+ * @param path - 路径
+ */
+export function findRoute(routes, path) {
+    for (const route of routes) {
+        if (!route.isGroup && route.fullPath === path)
+            return route;
+        if (route.isGroup && route.children) {
+            for (const child of route.children) {
+                if (child.fullPath === path)
+                    return route;
+                if (child.isGroup && child.children) {
+                    return findRoute(child.children, path);
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/file-router/utils/index.d.ts

@@ -9,3 +9,4 @@ export * from './logger.js';
 export * from './pathStrategy.js';
 export * from '../config/validate.js';
 export * from './fileReader.js';
+export * from './findRoute.js';

package/dist/file-router/utils/index.js

@@ -9,3 +9,4 @@ export * from './logger.js';
 export * from './pathStrategy.js';
 export * from '../config/validate.js';
 export * from './fileReader.js';
+export * from './findRoute.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.16",
+  "version": "4.0.0-beta.18",
   "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",
@@ -76,13 +76,14 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rimraf dist && vitest run && tsc && pnpm check:circular",
+    "build": "rimraf dist && vitest run && tsc -p tsconfig.build.json && pnpm check:circular",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "check:circular": "madge --extensions js --circular dist --warning --exclude '.*\\.d\\.ts$'",
     "test": "vitest run",
     "test:core": "vitest run --project jsdom",
     "test:plugin-vite": "vitest run --project plugin-vite",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage",
-    "release": "npx release-cli"
+    "release": "pnpm dlx @vitarx/release-cli"
   }
 }