vitarx-router 4.0.0-beta.3 → 4.0.0-beta.5

package/README.md

@@ -423,17 +423,18 @@ export const router = createRouter({ routes })
 
 ### 文件路由配置选项
 
-| 选项               | 类型                                    | 默认值           | 说明       |
-|------------------|---------------------------------------|---------------|----------|
-| `pages`          | `PageSource \| readonly PageSource[]` | `'src/pages'` | 页面来源配置   |
-| `pathStrategy`   | `'kebab' \| 'lowercase' \| 'raw'`     | `'kebab'`     | 路径命名策略   |
-| `importMode`     | `'lazy' \| 'sync'`                    | `'lazy'`      | 组件导入模式   |
-| `injectImports`  | `readonly string[]`                   | -             | 自定义导入语句  |
-| `dts`            | `boolean \| string`                   | `false`       | 类型声明文件配置 |
-| `layoutFileName` | `string`                              | `'_layout'`   | 布局文件名    |
-| `configFileName` | `string`                              | `'_config'`   | 分组配置文件名  |
-| `transform`      | `CodeTransformHook`                   | -             | 代码转换钩子   |
-| `extendRoute`    | `ExtendRouteHook`                     | -             | 路由扩展钩子   |
+| 选项               | 类型                                         | 默认值           | 说明       |
+|------------------|--------------------------------------------|---------------|----------|
+| `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)。
 

package/dist/core/shared/route.js

@@ -20,8 +20,7 @@ export function useRoute(global = false) {
         return route;
     }
     const record = route.matched[depth];
-    if (!record) {
+    if (!record)
         return route;
-    }
     return createRouteProxy(route, record);
 }

package/dist/file-router/config/resolve.d.ts

@@ -1,4 +1,4 @@
-import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PathStrategy } from '../types/index.js';
+import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PageSource, PathParser, PathStrategy } from '../types/index.js';
 export type PageDirConfig = Required<PageDirOptions>;
 /**
  * 规范化后的配置
@@ -14,7 +14,22 @@ export interface ResolvedConfig {
     configFileName: string;
     transform?: CodeTransformHook;
     extendRoute?: ExtendRouteHook;
+    pathParser?: PathParser;
 }
+/**
+ * 将 pages 配置规范化为 PageConfig 数组
+ *
+ * 支持四种输入格式：
+ * 1. 字符串：单个目录路径
+ * 2. 对象：单个目录配置
+ * 3. 字符串数组：多个目录路径
+ * 4. 对象数组：每个目录独立配置
+ *
+ * @param pages - 用户配置的 pages
+ * @param root - 项目根目录路径（用于解析相对路径）
+ * @returns - 规范化后的目录配置数组
+ */
+export declare function resolvePageConfigs(pages: PageSource | readonly PageSource[], root: string): PageDirConfig[];
 /**
  * 规范化文件路由配置
  *

package/dist/file-router/config/resolve.js

@@ -4,7 +4,6 @@
  * 提供页面目录配置的处理和文件检查功能。
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
-import { accessSync, constants } from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_CONFIG_FILE, DEFAULT_DTS_FILE, DEFAULT_EXCLUDE, DEFAULT_INCLUDE, DEFAULT_LAYOUT_FILE, DEFAULT_PAGES_DIR } from '../constants.js';
 const DEFAULT_PAGE_CONFIG = {
@@ -26,7 +25,7 @@ const DEFAULT_PAGE_CONFIG = {
  * @param root - 项目根目录路径（用于解析相对路径）
  * @returns - 规范化后的目录配置数组
  */
-function resolvePageConfigs(pages, root) {
+export function resolvePageConfigs(pages, root) {
     const list = Array.isArray(pages) ? pages : [pages];
     return list.map(page => {
         const config = typeof page === 'string' ? { dir: page } : page;
@@ -38,12 +37,6 @@ function resolvePageConfigs(pages, root) {
         if (resolved.prefix !== '/' && !resolved.prefix.startsWith('/')) {
             resolved.prefix = '/' + resolved.prefix;
         }
-        try {
-            accessSync(resolved.dir, constants.R_OK | constants.W_OK);
-        }
-        catch (error) {
-            throw new Error(`File router: Pages directory "${resolved.dir}" does not exist or is not accessible`);
-        }
         return resolved;
     });
 }
@@ -56,7 +49,7 @@ function resolvePageConfigs(pages, root) {
  * @returns - 规范化后的配置对象
  */
 export function resolveConfig(options) {
-    const { dts = false, root = process.cwd(), pages = DEFAULT_PAGES_DIR, importMode = 'lazy', injectImports = [], pathStrategy = 'kebab', layoutFileName = DEFAULT_LAYOUT_FILE, configFileName = DEFAULT_CONFIG_FILE, transform, extendRoute } = options;
+    const { dts = false, root = process.cwd(), pages = DEFAULT_PAGES_DIR, importMode = 'lazy', injectImports = [], pathStrategy = 'kebab', layoutFileName = DEFAULT_LAYOUT_FILE, configFileName = DEFAULT_CONFIG_FILE, transform, extendRoute, pathParser } = options;
     const resolvedPages = resolvePageConfigs(pages, root);
     return {
         dts: typeof dts === 'string' ? dts : dts ? DEFAULT_DTS_FILE : false,
@@ -68,6 +61,7 @@ export function resolveConfig(options) {
         layoutFileName,
         configFileName,
         transform,
-        extendRoute
+        extendRoute,
+        pathParser
     };
 }

package/dist/file-router/config/validate.d.ts

@@ -19,6 +19,7 @@ import type { FileRouterOptions } from '../types/index.js';
  * 8. configFileName 配置
  * 9. transform 配置
  * 10. extendRoute 配置
+ * 11. pathParser 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误

package/dist/file-router/config/validate.js

@@ -84,9 +84,11 @@ function validateRoot(opts) {
 function validateImportMode(opts) {
     if (opts.importMode === undefined)
         return;
+    if (typeof opts.importMode === 'function')
+        return;
     const validModes = ['lazy', 'sync'];
     if (!validModes.includes(opts.importMode)) {
-        throw new Error(`options.importMode 必须是 'lazy' 或 'sync'`);
+        throw new Error(`options.importMode 必须是 'lazy'、'sync' 或函数`);
     }
 }
 /**
@@ -198,6 +200,19 @@ function validateExtendRoute(opts) {
         throw new Error('options.extendRoute 必须是函数');
     }
 }
+/**
+ * 验证 pathParser 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validatePathParser(opts) {
+    if (opts.pathParser === undefined)
+        return;
+    if (typeof opts.pathParser !== 'function') {
+        throw new Error('options.pathParser 必须是函数');
+    }
+}
 /**
  * 验证插件配置选项
  *
@@ -212,6 +227,7 @@ function validateExtendRoute(opts) {
  * 8. configFileName 配置
  * 9. transform 配置
  * 10. extendRoute 配置
+ * 11. pathParser 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误
@@ -227,4 +243,5 @@ export function validateOptions(opts) {
     validateConfigFileName(opts);
     validateTransform(opts);
     validateExtendRoute(opts);
+    validatePathParser(opts);
 }

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

@@ -115,7 +115,6 @@ function buildRoutes(pages, extendRoute, parent) {
  * @returns 格式化后的组件表达式代码
  */
 function formatComponent(component, importMode, importLines) {
-    // 处理命名视图
     const entries = Object.entries(component).map(([name, file]) => {
         const importPath = JSON.stringify(file);
         let expr;
@@ -123,10 +122,17 @@ function formatComponent(component, importMode, importLines) {
             expr = pathToUniqueName(file);
             importLines.add(`import ${expr} from ${importPath}`);
         }
-        else {
+        else if (importMode === 'lazy') {
             expr = `lazy(() => import(${importPath}))`;
         }
-        return `${name}: ${expr}`;
+        else {
+            expr = importMode({
+                importPath,
+                filePath: file,
+                addImport: statement => importLines.add(statement)
+            });
+        }
+        return `${JSON.stringify(name)}: ${expr}`;
     });
     return `{ ${entries.join(', ')} }`;
 }
@@ -215,26 +221,23 @@ function generateRouteCode(route, indent, isLast, importMode, importLines) {
 function generateRoutesCode(routes, importMode = 'lazy', customImports, indent = '  ') {
     const importLines = new Set();
     const codeLines = [];
-    // 添加 lazy 导入（如果需要）
     if (importMode === 'lazy') {
         importLines.add(`import { lazy } from 'vitarx'`);
     }
-    // 添加自定义导入语句
     if (customImports && customImports.length > 0) {
         customImports.forEach(imp => importLines.add(imp));
     }
-    // 添加空行
-    if (importMode === 'lazy' || (customImports && customImports.length > 0)) {
-        codeLines.push('');
-    }
-    // 生成路由数组
     codeLines.push('export default [');
     for (let i = 0; i < routes.length; i++) {
         const route = routes[i];
         codeLines.push(...generateRouteCode(route, indent, i === routes.length - 1, importMode, importLines));
     }
     codeLines.push(']');
-    return Array.from(importLines.values()).concat(codeLines).join('\n');
+    const allImports = Array.from(importLines.values());
+    if (allImports.length > 0) {
+        allImports.push('');
+    }
+    return allImports.concat(codeLines).join('\n');
 }
 /**
  * 生成路由配置代码

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

@@ -7,9 +7,11 @@
 import type { GeneratorResult } from '@babel/generator';
 import { ResolvedConfig } from './config/index.js';
 import { type GenerateResult } from './generator/index.js';
+import { type FilterOptions } from './parser/index.js';
 import type { FileRouterOptions, ParsedNode } from './types/index.js';
 export type * from './types/index.js';
 export * from './utils/logger.js';
+export { resolvePageConfigs } from './config/resolve.js';
 /**
  * 文件路由管理器
  */
@@ -66,7 +68,6 @@ export declare class FileRouter {
     /**
      * 处理文件
      * @param filePath - 文件路径
-     * @param fileName - 文件名
      * @param page - 页面配置
      * @param pageMapping - 子路由
      * @param parent - 父节点
@@ -91,7 +92,6 @@ export declare class FileRouter {
      *
      * @param file - 文件绝对路径
      * @param name - 文件名
-     * @param ext - 文件扩展名
      * @param pages - 页面配置，默认为 `config.pages`
      * @returns {string} - 文件类型，可选值有 `layout`、`config`、`page`、`ignore`
      */
@@ -100,10 +100,10 @@ export declare class FileRouter {
      * 检查文件是否为页面文件
      *
      * @param file - 文件绝对路径
-     * @param pages - 页面配置，默认为 `config.pages`
+     * @param filter - 过滤配置，默认为 `config.pages`
      * @returns {boolean} - 是否为页面文件
      */
-    private isPageFile;
+    isPageFile(file: string, filter?: FilterOptions | readonly FilterOptions[]): boolean;
     /**
      * 写入类型定义文件
      */

package/dist/file-router/index.js

@@ -17,8 +17,9 @@ import { generateRoutes } from './generator/index.js';
 import { isEqualPageOptions, mergePageOptions, parseDefinePage, removeDefinePage } from './macros/index.js';
 import { checkDefaultExport, isPageFile, isPageFileInDirs } from './parser/index.js';
 import { parseRoutePath } from './parser/parsePage.js';
-import { applyPathStrategy, info, normalizePathSeparator, readFileContent, resolvePathVariable, validateOptions } from './utils/index.js';
+import { applyPathStrategy, info, normalizePathSeparator, readFileContent, resolvePathVariable, validateOptions, warn } from './utils/index.js';
 export * from './utils/logger.js';
+export { resolvePageConfigs } from './config/resolve.js';
 /**
  * 文件路由管理器
  */
@@ -98,6 +99,10 @@ export class FileRouter {
     scanPages() {
         const pages = [];
         for (const page of this.config.pages) {
+            if (!existsSync(page.dir)) {
+                warn(`Directory ${page.dir} does not exist, please check your configuration.`);
+                continue;
+            }
             if (page.group && page.prefix) {
                 const route = {
                     filePath: page.dir,
@@ -137,7 +142,7 @@ export class FileRouter {
             }
             else {
                 // 处理文件
-                route = this.processFile(filePath, dirent.name, page, pageMapping, parent);
+                route = this.processFile(filePath, page, pageMapping, parent);
             }
             if (route) {
                 children.add(route);
@@ -169,18 +174,15 @@ export class FileRouter {
     /**
      * 处理文件
      * @param filePath - 文件路径
-     * @param fileName - 文件名
      * @param page - 页面配置
      * @param pageMapping - 子路由
      * @param parent - 父节点
      * @private
      */
-    processFile(filePath, fileName, page, pageMapping, parent) {
-        // 获取扩展名称
-        const ext = nodePath.extname(fileName);
-        // 获取文件名
-        const baseName = nodePath.basename(fileName, ext);
-        const fileType = this.getPageType(filePath, baseName, ext, page);
+    processFile(filePath, page, pageMapping, parent) {
+        // 分离出路由 path 和视图命名
+        const { routePath, viewName = 'default' } = parseRoutePath(filePath, this.config.pathParser);
+        const fileType = this.getPageType(filePath, routePath, page);
         if (fileType === 'ignore')
             return null;
         // 处理分组配置文件
@@ -201,8 +203,6 @@ export class FileRouter {
             }
             return null;
         }
-        // 分离出路由 path 和视图命名
-        const { routePath, viewName } = parseRoutePath(baseName);
         // 处理分组布局文件
         if (fileType === 'layout') {
             if (!parent)
@@ -273,15 +273,14 @@ export class FileRouter {
      *
      * @param file - 文件绝对路径
      * @param name - 文件名
-     * @param ext - 文件扩展名
      * @param pages - 页面配置，默认为 `config.pages`
      * @returns {string} - 文件类型，可选值有 `layout`、`config`、`page`、`ignore`
      */
-    getPageType(file, name, ext, pages) {
-        if (name === this.config.layoutFileName || name.startsWith(`${this.config.configFileName}@`)) {
+    getPageType(file, name, pages) {
+        if (name === this.config.layoutFileName) {
             return 'layout';
         }
-        if (name === this.config.configFileName && (ext === '.ts' || ext === '.js')) {
+        if (name === this.config.configFileName && (file.endsWith('.ts') || file.endsWith('.js'))) {
             return 'config';
         }
         if (this.isPageFile(file, pages)) {
@@ -293,16 +292,16 @@ export class FileRouter {
      * 检查文件是否为页面文件
      *
      * @param file - 文件绝对路径
-     * @param pages - 页面配置，默认为 `config.pages`
+     * @param filter - 过滤配置，默认为 `config.pages`
      * @returns {boolean} - 是否为页面文件
      */
-    isPageFile(file, pages) {
-        if (pages) {
-            if (Array.isArray(pages)) {
-                return !!isPageFileInDirs(file, pages);
+    isPageFile(file, filter) {
+        if (filter) {
+            if (Array.isArray(filter)) {
+                return !!isPageFileInDirs(file, filter);
             }
             else {
-                return isPageFile(file, pages);
+                return isPageFile(file, filter);
             }
         }
         return !!isPageFileInDirs(file, this.config.pages);
@@ -376,16 +375,16 @@ export class FileRouter {
         const page = isPageFileInDirs(filePath, this.config.pages);
         if (!page)
             return false;
+        // 分离出路由 path 和视图命名
+        const { routePath, viewName } = parseRoutePath(filePath, this.config.pathParser);
         const dirPath = nodePath.dirname(filePath);
-        const filename = nodePath.basename(filePath);
         const parent = this.fileMap.get(dirPath);
         const pageMapping = new Map();
         const prefix = parent ? '' : page.prefix;
         // 如果是命名文件，则先查找是否存在同名路由，存在则添加到同名路由的 children 中
-        if (filename.includes('@')) {
-            const baseName = filename.split('@')[0];
+        if (viewName) {
             const pages = parent ? parent.children : this.nodeTree;
-            const newRoutePath = this.applyPathStrategy(prefix + baseName);
+            const newRoutePath = this.applyPathStrategy(prefix + routePath);
             let sameRoute = null;
             for (const route of pages) {
                 if (route.path === newRoutePath) {
@@ -394,10 +393,10 @@ export class FileRouter {
                 }
             }
             if (sameRoute) {
-                pageMapping.set(baseName, sameRoute);
+                pageMapping.set(routePath, sameRoute);
             }
         }
-        const route = this.processFile(filePath, filename, {
+        const route = this.processFile(filePath, {
             dir: dirPath,
             include: page.include,
             exclude: page.exclude,

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

@@ -1,23 +1,35 @@
+import type { PathParser, PathParseResult } from '../types/index.js';
 /**
- * @fileoverview 页面解析模块
+ * 路径解析错误类
  *
- * 负责解析页面文件路径，提取路由信息，包括：
- * - 路由路径转换
- *
- * 与构建工具无关，可在任何 Node.js 环境中使用。
+ * 提供详细的错误上下文信息，包括文件路径、错误类型和原始值。
  */
-type PathParseResult = {
-    viewName: string;
-    routePath: string;
-};
+export declare class PathParseError extends TypeError {
+    /** 文件路径上下文 */
+    readonly filePath?: string;
+    /** 错误字段名称 */
+    readonly field?: string;
+    /** 原始值 */
+    readonly originalValue?: unknown;
+    constructor(message: string, options?: {
+        filePath?: string;
+        field?: string;
+        originalValue?: unknown;
+        cause?: Error;
+    });
+    /**
+     * 生成详细的错误信息
+     */
+    toString(): string;
+}
 /**
- * 解析视图名称
+ * 解析路由路径和视图名称
  *
- * 从文件名中提取命名视图名称。
+ * 从文件名中提取路由路径和命名视图名称。
  *
- * @param baseName - 文件基础名，不包含后缀
- * @param defaultName - 默认视图名称
- * @returns 视图名称和去除视图名的基础名
+ * @param filePath - 文件路径
+ * @param [parser] - 路径解析器
+ * @returns 路由路径和视图名称
+ * @throws {PathParseError} 当路径解析失败时抛出
  */
-export declare function parseRoutePath(baseName: string, defaultName?: string): PathParseResult;
-export {};
+export declare function parseRoutePath(filePath: string, parser?: PathParser): Exclude<PathParseResult, string>;

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

@@ -6,16 +6,215 @@
  *
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
+import path from 'node:path';
 /**
- * 解析视图名称
+ * 路径解析错误类
  *
- * 从文件名中提取命名视图名称。
+ * 提供详细的错误上下文信息，包括文件路径、错误类型和原始值。
+ */
+export class PathParseError extends TypeError {
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        /** 文件路径上下文 */
+        Object.defineProperty(this, "filePath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 错误字段名称 */
+        Object.defineProperty(this, "field", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 原始值 */
+        Object.defineProperty(this, "originalValue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'PathParseError';
+        this.filePath = options?.filePath;
+        this.field = options?.field;
+        this.originalValue = options?.originalValue;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PathParseError);
+        }
+    }
+    /**
+     * 生成详细的错误信息
+     */
+    toString() {
+        let details = `${this.name}: ${this.message}`;
+        if (this.filePath) {
+            details += `\n  File: ${this.filePath}`;
+        }
+        if (this.field) {
+            details += `\n  Field: ${this.field}`;
+        }
+        if (this.originalValue !== undefined) {
+            details += `\n  Value: ${String(this.originalValue)}`;
+        }
+        return details;
+    }
+}
+/**
+ * 解析路由路径和视图名称
+ *
+ * 从文件名中提取路由路径和命名视图名称。
+ *
+ * @param filePath - 文件路径
+ * @param [parser] - 路径解析器
+ * @returns 路由路径和视图名称
+ * @throws {PathParseError} 当路径解析失败时抛出
+ */
+export function parseRoutePath(filePath, parser) {
+    const { basename } = extractFileInfo(filePath);
+    if (!parser) {
+        return parseDefaultRoutePath(basename);
+    }
+    const result = parser(basename, filePath);
+    return parseCustomRouteResult(result, filePath);
+}
+/**
+ * 提取文件信息
+ *
+ * @param filePath - 文件路径
+ * @returns 文件基本信息
+ */
+function extractFileInfo(filePath) {
+    const ext = path.extname(filePath);
+    const basename = path.basename(filePath, ext);
+    return { basename, ext };
+}
+/**
+ * 解析默认路由路径（无自定义解析器）
+ *
+ * @param basename - 文件基本名称
+ * @returns 解析结果
+ */
+function parseDefaultRoutePath(basename) {
+    const [routePath, viewName] = basename.split('@', 2);
+    return {
+        routePath,
+        viewName: viewName || 'default'
+    };
+}
+/**
+ * 解析自定义路由结果
+ *
+ * @param result - 解析器返回的结果
+ * @param filePath - 文件路径（用于错误上下文）
+ * @returns 解析结果
+ * @throws {PathParseError} 当结果无效时抛出
+ */
+function parseCustomRouteResult(result, filePath) {
+    if (typeof result === 'string') {
+        return parseStringResult(result, filePath);
+    }
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        return parseObjectResult(result, filePath);
+    }
+    throw new PathParseError('pathParser returned invalid result type', {
+        filePath,
+        originalValue: result,
+        field: 'result'
+    });
+}
+/**
+ * 解析字符串类型的结果
+ *
+ * @param result - 字符串结果
+ * @param filePath - 文件路径
+ * @returns 解析结果
+ * @throws {PathParseError} 当路径无效时抛出
+ */
+function parseStringResult(result, filePath) {
+    const routePath = normalizeRoutePath(result);
+    if (!routePath) {
+        throw new PathParseError('pathParser returned empty routePath', {
+            filePath,
+            originalValue: result,
+            field: 'routePath'
+        });
+    }
+    return { routePath, viewName: 'default' };
+}
+/**
+ * 解析对象类型的结果
+ *
+ * @param result - 对象结果
+ * @param filePath - 文件路径
+ * @returns 解析结果
+ * @throws {PathParseError} 当结果无效时抛出
+ */
+function parseObjectResult(result, filePath) {
+    const { routePath: rawRoutePath, viewName } = result;
+    validateRoutePathType(rawRoutePath, filePath);
+    const routePath = normalizeRoutePath(rawRoutePath);
+    if (!routePath) {
+        throw new PathParseError('pathParser returned empty routePath after normalization', {
+            filePath,
+            originalValue: rawRoutePath,
+            field: 'routePath'
+        });
+    }
+    validateViewName(viewName, filePath);
+    return {
+        routePath,
+        viewName: viewName || 'default'
+    };
+}
+/**
+ * 验证路由路径类型
+ *
+ * @param routePath - 路由路径
+ * @param filePath - 文件路径（用于错误上下文）
+ * @throws {PathParseError} 当类型无效时抛出
+ */
+function validateRoutePathType(routePath, filePath) {
+    if (typeof routePath !== 'string') {
+        throw new PathParseError('pathParser returned non-string routePath', {
+            filePath,
+            originalValue: routePath,
+            field: 'routePath'
+        });
+    }
+    if (!routePath.trim()) {
+        throw new PathParseError('pathParser returned empty or whitespace-only routePath', {
+            filePath,
+            originalValue: routePath,
+            field: 'routePath'
+        });
+    }
+}
+/**
+ * 验证视图名称
+ *
+ * @param viewName - 视图名称
+ * @param filePath - 文件路径（用于错误上下文）
+ * @throws {PathParseError} 当视图名称无效时抛出
+ */
+function validateViewName(viewName, filePath) {
+    if (viewName !== undefined && typeof viewName !== 'string') {
+        throw new PathParseError('pathParser returned non-string viewName', {
+            filePath,
+            originalValue: viewName,
+            field: 'viewName'
+        });
+    }
+}
+/**
+ * 标准化路由路径
+ *
+ * 去除路径首尾空白和开头的斜杠。
  *
- * @param baseName - 文件基础名，不包含后缀
- * @param defaultName - 默认视图名称
- * @returns 视图名称和去除视图名的基础名
+ * @param routePath - 原始路由路径
+ * @returns 标准化后的路由路径
  */
-export function parseRoutePath(baseName, defaultName = 'default') {
-    let [routePath, viewName] = baseName.split('@');
-    return { viewName: viewName || defaultName, routePath };
+function normalizeRoutePath(routePath) {
+    return routePath.trim().replace(/^\/+/, '');
 }

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

@@ -1,16 +1,68 @@
 import type { CodeTransformHook, ExtendRouteHook } from './hooks.js';
+/**
+ * 自定义导入模式函数的上下文
+ */
+export interface ImportModeContext {
+    /**
+     * 组件文件路径（已 JSON.stringify）
+     */
+    importPath: string;
+    /**
+     * 组件文件原始路径
+     */
+    filePath: string;
+    /**
+     * 添加导入语句
+     * 用于向生成的代码顶部添加 import 语句
+     */
+    addImport: (statement: string) => void;
+}
+/**
+ * 自定义导入模式函数
+ *
+ * @param context - 导入上下文
+ * @returns 组件表达式代码
+ *
+ * @example
+ * ```ts
+ * // 自定义导入模式：使用 React.lazy
+ * (context) => {
+ *   context.addImport(`import { lazy } from 'react'`)
+ *   return `lazy(() => import(${context.importPath}))`
+ * }
+ * ```
+ */
+export type ImportModeFunction = (context: ImportModeContext) => string;
 /**
  * 组件导入模式。
  *
- * - 'lazy': 生成懒加载表达式
- * - 'sync': 同步加载组件
+ * - 'lazy': 生成懒加载表达式 `lazy(() => import(path))`
+ * - 'sync': 同步加载组件，生成 `import` 语句
+ * - 函数: 自定义导入逻辑
  */
-export type ImportMode = 'lazy' | 'sync';
+export type ImportMode = 'lazy' | 'sync' | ImportModeFunction;
 /**
  * 生成路径的策略。
  */
 export type PathStrategy = 'kebab' | 'lowercase' | 'raw';
 export type PageSource = string | PageDirOptions;
+/**
+ * 路径解析结果
+ */
+export type PathParseResult = string | {
+    /** 解析后的路径 */
+    routePath: string;
+    /** 视图名称 */
+    viewName?: string;
+};
+/**
+ * 路径解析器
+ *
+ * @param basename - 文件名称（不包含扩展名)
+ * @param filePath - 完整的文件路径
+ * @returns {PathParseResult} 路径解析结果包含路径和视图名称
+ */
+export type PathParser = (basename: string, filePath: string) => PathParseResult;
 /**
  * 页面目录选项
  */
@@ -60,12 +112,33 @@ export interface FileRouterOptions {
     /**
      * 路径转换策略
      *
+     * - 'kebab': 转换为 kebab-case
+     * - 'lowercase': 转换为 lowercase
+     * - 'raw': 不转换
+     *
+     * @values 'kebab' | 'lowercase' | 'raw'
      * @default 'kebab'
      */
     pathStrategy?: PathStrategy;
     /**
      * 组件导入模式
      *
+     * - 'lazy': 生成懒加载表达式 `lazy(() => import(path))`
+     * - 'sync': 同步加载组件，生成 `import` 语句
+     * - 函数: 自定义导入逻辑
+     *
+     * @example
+     * ```ts
+     * // 使用预设模式
+     * importMode: 'lazy'
+     *
+     * // 使用自定义函数
+     * importMode: (context) => {
+     *   context.addImport(`import { lazy } from 'react'`)
+     *   return `lazy(() => import(${context.importPath}))`
+     * }
+     * ```
+     *
      * @default 'lazy'
      */
     importMode?: ImportMode;
@@ -135,4 +208,12 @@ export interface FileRouterOptions {
      * ```
      */
     extendRoute?: ExtendRouteHook;
+    /**
+     * 路径解析器
+     *
+     * @param basename - 文件名称（不包含扩展名）或目录名称
+     * @param filePath - 完整的文件路径
+     * @returns {PathParseResult} 返回字符串path，或包含path和viewName的对象
+     */
+    pathParser?: PathParser;
 }

package/dist/plugin-vite/index.js

@@ -14,7 +14,6 @@ export default function VitarxRouter(options = {}) {
     let isPreview = false;
     return {
         name: 'vite-plugin-vitarx-router',
-        enforce: 'pre',
         config(_, env) {
             isPreview = !!env.isPreview;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0-beta.5",
   "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",