@infly/vue2-vite 1.0.0

package/src/compat/html.mjs

@@ -0,0 +1,244 @@
+/**
+ * HTML 模板兼容层
+ *
+ * 从项目 public/index.html 生成 Vite 临时入口 HTML，
+ * 替换 Webpack EJS 标记，注入 Vite module script。
+ * 输出到 node_modules/.cache/infly-vue2-vite/[mode]/[target]/index.html。
+ *
+ * 从 compat/html.js 迁移（60% 可复用）。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 已知的 EJS 标记 → 替换函数映射
+ */
+export const KNOWN_EJS_TOKENS = {
+  'BASE_URL': (ctx) => ctx.base || '/',
+  'webpackConfig.name': (ctx) => ctx.title || 'App',
+  'htmlWebpackPlugin.options.buildTimestamp': () => new Date().toLocaleString(),
+  'htmlWebpackPlugin.options.buildVersion': (ctx) => ctx.buildVersion || '0.0.0',
+  'htmlWebpackPlugin.options.buildEnv': (ctx) => ctx.buildEnv || 'development',
+  'htmlWebpackPlugin.options.faviconPath': (ctx) => ctx.favicon || 'favicon.ico',
+};
+
+const EJS_PATTERN = /<%=\s*([^%]+)\s*%>/g;
+
+function resolveBuildVersion(projectRoot) {
+  if (process.env.INFLY_VITE_APP_VERSION) {
+    return process.env.INFLY_VITE_APP_VERSION;
+  }
+  try {
+    const packageJson = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'),
+    );
+    if (typeof packageJson.version === 'string' && packageJson.version.length > 0) {
+      return packageJson.version;
+    }
+  } catch (_) {
+    // Missing or invalid package metadata falls back to the compatibility default.
+  }
+  return '0.0.0';
+}
+
+/**
+ * 替换 HTML 中的 EJS 标记
+ *
+ * @param {string} html - 原始 HTML
+ * @param {object} ctx - 上下文 { title, favicon, buildVersion, buildEnv, base }
+ * @returns {{ html: string, errors: string[] }}
+ */
+export function replaceEjsTokens(html, ctx = {}) {
+  const errors = [];
+  let result = html;
+
+  result = result.replace(EJS_PATTERN, (match, token) => {
+    const trimmed = token.trim();
+    if (KNOWN_EJS_TOKENS[trimmed]) {
+      return KNOWN_EJS_TOKENS[trimmed](ctx);
+    }
+    errors.push(`未识别的 EJS 标记: ${trimmed} (完整表达式: ${match})`);
+    return match;
+  });
+
+  return { html: result, errors };
+}
+
+/**
+ * 注入 Vite 入口 script 标签
+ *
+ * @param {string} html
+ * @param {string} mainEntry - 如 'src/main.js'
+ * @returns {string}
+ */
+export function injectViteEntry(html, mainEntry) {
+  const entryScript = `  <script type="module" src="/${mainEntry.replace(/\\/g, '/')}"></script>`;
+  const bodyCloseIndex = html.lastIndexOf('</body>');
+
+  if (bodyCloseIndex === -1) {
+    return html + '\n' + entryScript + '\n';
+  }
+
+  return html.slice(0, bodyCloseIndex) + '\n' + entryScript + '\n' + html.slice(bodyCloseIndex);
+}
+
+/**
+ * 注入 window.BUILD_INFO
+ *
+ * @param {string} html
+ * @param {object} ctx - { buildVersion, buildEnv }
+ * @returns {string}
+ */
+export function injectBuildInfo(html, ctx = {}) {
+  const buildInfoScript = [
+    '<script>',
+    '  window.BUILD_INFO = {',
+    `    timestamp: '${new Date().toLocaleString()}',`,
+    `    version: '${ctx.buildVersion || '0.0.0'}',`,
+    `    env: '${ctx.buildEnv || 'development'}',`,
+    '  };',
+    '</script>',
+  ].join('\n');
+
+  const headCloseIndex = html.indexOf('</head>');
+  if (headCloseIndex === -1) return buildInfoScript + '\n' + html;
+  return html.slice(0, headCloseIndex) + '\n' + buildInfoScript + '\n' + html.slice(headCloseIndex);
+}
+
+/**
+ * 从项目 public/index.html 生成 Vite 入口 HTML
+ *
+ * @param {object} options
+ * @param {string} options.projectRoot - 项目根目录
+ * @param {string} [options.htmlTemplate] - HTML 模板路径（默认 public/index.html）
+ * @param {string} [options.mainEntry] - 入口文件（默认 src/main.js）
+ * @param {string} [options.title] - 页面标题
+ * @param {string} [options.favicon] - favicon 路径
+ * @param {string} [options.mode] - 构建模式
+ * @param {string} [options.target] - 构建 target
+ * @returns {{ html: string, cacheDir: string, indexPath: string }}
+ */
+export function generateViteHtml(options = {}) {
+  const {
+    projectRoot,
+    htmlTemplate = 'public/index.html',
+    mainEntry = 'src/main.js',
+    title,
+    favicon = 'favicon.ico',
+    mode = 'development',
+    target = 'DEFAULT',
+    base = '/',
+  } = options;
+
+  const templatePath = path.resolve(projectRoot, htmlTemplate);
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`HTML 模板不存在: ${templatePath}`);
+  }
+
+  const normalizedFavicon = favicon.replace(/^\//, '');
+
+  const ctx = {
+    title: title || path.basename(projectRoot),
+    favicon: normalizedFavicon,
+    buildVersion: resolveBuildVersion(projectRoot),
+    buildEnv: mode,
+    base,
+  };
+
+  let html = fs.readFileSync(templatePath, 'utf8');
+
+  // 替换 EJS 标记
+  const { html: replaced, errors } = replaceEjsTokens(html, ctx);
+  if (errors.length > 0) {
+    throw new Error(
+      `HTML 模板 "${templatePath}" 包含未识别的 EJS 标记：\n` +
+      errors.map((e) => `  - ${e}`).join('\n')
+    );
+  }
+
+  html = replaced;
+
+  // 添加 favicon link
+  if (!/<link\s+rel="icon"/i.test(html) && !/<link\s+rel="shortcut icon"/i.test(html)) {
+    const faviconLink = `  <link rel="icon" href="${base}${normalizedFavicon}">`;
+    const headCloseIdx = html.indexOf('</head>');
+    if (headCloseIdx !== -1) {
+      html = html.slice(0, headCloseIdx) + faviconLink + '\n' + html.slice(headCloseIdx);
+    }
+  }
+
+  // 注入 Vite module script 入口
+  html = injectViteEntry(html, mainEntry);
+
+  // 注入 build 信息
+  if (!/window\.BUILD_INFO\s*=/.test(html)) {
+    html = injectBuildInfo(html, ctx);
+  }
+
+  // 写入临时缓存目录
+  const cacheDir = path.resolve(
+    projectRoot, 'node_modules', '.cache', 'infly-vue2-vite', mode, target
+  );
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const indexPath = path.join(cacheDir, 'index.html');
+  fs.writeFileSync(indexPath, html, 'utf8');
+
+  // 复制 public/ 中的静态资源到缓存目录
+  const publicDir = path.join(projectRoot, 'public');
+  if (fs.existsSync(publicDir)) {
+    copyPublicAssets(publicDir, cacheDir);
+  }
+
+  return { html, cacheDir, indexPath };
+}
+
+/**
+ * 递归复制 public 目录中的静态资源（跳过 index.html）
+ */
+function copyPublicAssets(srcDir, destDir) {
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyPublicAssets(srcPath, destPath);
+    } else if (entry.name !== 'index.html') {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * 检查 HTML 中是否存在未识别的 EJS 标记
+ *
+ * @param {object} options - { projectRoot, htmlTemplate }
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateEjsTemplate(options = {}) {
+  const { projectRoot, htmlTemplate = 'public/index.html' } = options;
+  const templatePath = path.resolve(projectRoot, htmlTemplate);
+
+  if (!fs.existsSync(templatePath)) {
+    return { valid: false, errors: [`HTML 模板不存在: ${templatePath}`] };
+  }
+
+  const html = fs.readFileSync(templatePath, 'utf8');
+  const errors = [];
+  let match;
+  const seen = new Set();
+
+  while ((match = EJS_PATTERN.exec(html)) !== null) {
+    const trimmed = match[1].trim();
+    if (!KNOWN_EJS_TOKENS[trimmed] && !seen.has(trimmed)) {
+      seen.add(trimmed);
+      errors.push(`未识别的 EJS 标记 "${trimmed}" 在 ${templatePath}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/compat/import-interop.mjs

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function resolveTargetFile(projectRoot, importerId, importPath) {
+  const cleanPath = importPath.replace(/[?#].*$/, '');
+  const basePath = cleanPath.startsWith('@/')
+    ? path.resolve(projectRoot, 'src', cleanPath.slice(2))
+    : path.resolve(path.dirname(importerId.replace(/[?#].*$/, '')), cleanPath);
+
+  for (const suffix of ['', '.js', '.vue', '/index.js', '/index.vue', '.cjs']) {
+    const candidate = basePath + suffix;
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch (_) {
+      // Continue through the supported resolution suffixes.
+    }
+  }
+  return null;
+}
+
+function readTarget(projectRoot, importerId, importPath) {
+  const target = resolveTargetFile(projectRoot, importerId, importPath);
+  if (!target) return null;
+  try {
+    return fs.readFileSync(target, 'utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+function isCommonJsTarget(projectRoot, importerId, importPath) {
+  return readTarget(projectRoot, importerId, importPath)?.includes('module.exports') === true;
+}
+
+function isReExportTarget(projectRoot, importerId, importPath) {
+  const source = readTarget(projectRoot, importerId, importPath);
+  if (!source) return false;
+  const lines = source
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('//'));
+  const isReExport = (line) => (
+    /^export\s*\{[^}]*\}\s*from\s*['"]/.test(line)
+    || /^export\s+\*\s+from\s*['"]/.test(line)
+  );
+  return lines.length > 0 && (
+    lines.every(isReExport)
+    || (lines.length <= 20 && lines.slice(0, 5).every(isReExport))
+  );
+}
+
+function stripJavaScriptComments(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/.*$/gm, '');
+}
+
+function parseNamedImportSpecifiers(names) {
+  const cleaned = stripJavaScriptComments(names).trim();
+  if (!cleaned) return null;
+
+  const specifiers = cleaned
+    .split(',')
+    .map((specifier) => specifier.trim())
+    .filter(Boolean)
+    .map((specifier) => {
+      const match = specifier.match(
+        /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/,
+      );
+      if (!match) return null;
+      return { imported: match[1], local: match[2] || match[1] };
+    });
+
+  return specifiers.length > 0 && specifiers.every(Boolean) ? specifiers : null;
+}
+
+function collectNamedExports(source) {
+  const cleanSource = stripJavaScriptComments(source);
+  if (/\bexport\s+\*\s+from\s*['"]/.test(cleanSource)) return null;
+
+  const namedExports = new Set();
+  if (/\bexport\s+default\b/.test(cleanSource)) namedExports.add('default');
+
+  for (const match of cleanSource.matchAll(
+    /\bexport\s+(?:async\s+)?(?:function|class)\s+([A-Za-z_$][\w$]*)/g,
+  )) {
+    namedExports.add(match[1]);
+  }
+
+  for (const match of cleanSource.matchAll(
+    /\bexport\s+(?:const|let|var)\s+([^;\n]+)/g,
+  )) {
+    for (const declaration of match[1].split(',')) {
+      const name = declaration.trim().match(/^([A-Za-z_$][\w$]*)/);
+      if (name) namedExports.add(name[1]);
+    }
+  }
+
+  for (const match of cleanSource.matchAll(/\bexport\s*\{([^}]+)\}/g)) {
+    for (const specifier of match[1].split(',')) {
+      const parts = specifier.trim().split(/\s+as\s+/);
+      const exportedName = (parts[1] || parts[0]).trim();
+      if (exportedName) namedExports.add(exportedName);
+    }
+  }
+
+  for (const match of cleanSource.matchAll(
+    /\bexport\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*['"]/g,
+  )) {
+    namedExports.add(match[1]);
+  }
+
+  return namedExports;
+}
+
+function findMissingNamedImports(names, projectRoot, importerId, importPath) {
+  const specifiers = parseNamedImportSpecifiers(names);
+  if (!specifiers) return null;
+
+  const target = resolveTargetFile(projectRoot, importerId, importPath);
+  if (!target || path.extname(target) === '.vue') return null;
+
+  const source = readTarget(projectRoot, importerId, importPath);
+  if (source === null || isCommonJsTarget(projectRoot, importerId, importPath)) {
+    return null;
+  }
+
+  const namedExports = collectNamedExports(source);
+  if (!namedExports) return null;
+
+  const missing = specifiers.filter(({ imported }) => !namedExports.has(imported));
+  return missing.length > 0 ? { missing, specifiers } : null;
+}
+
+export function transformImportInterop(code, id, projectRoot, warn) {
+  if (id.includes('node_modules') || id.includes('.vite') || id.includes('.cache')) return null;
+  if (/\.(ts|tsx)(?:[?#].*)?$/.test(id)) return null;
+
+  let counter = 0;
+  let changed = false;
+  let result = code.replace(
+    /import\s+\{([^}]+)\}\s+from\s+['"](\.\/[^'"]+|\.\.\/[^'"]+|@\/[^'"]+)['"]/g,
+    (match, names, importPath) => {
+      if (importPath.includes('.vue')) return match;
+      if (!isCommonJsTarget(projectRoot, id, importPath)) {
+        const missingImports = findMissingNamedImports(names, projectRoot, id, importPath);
+        if (!missingImports) return match;
+
+        const variable = `__infly_named_import_${counter++}`;
+        const destructuring = missingImports.specifiers
+          .map(({ imported, local }) => imported === local ? imported : `${imported}: ${local}`)
+          .join(', ');
+        const missingNames = missingImports.missing.map(({ imported }) => imported).join(', ');
+        warn?.(
+          `[infly-vue2] Missing named export(s) "${missingNames}" from "${importPath}" in "${id}"; using undefined fallback.`,
+        );
+        changed = true;
+        return `import * as ${variable} from '${importPath}';\nconst { ${destructuring} } = ${variable};`;
+      }
+      const variable = `__infly_interop_${counter++}`;
+      changed = true;
+      return `import ${variable} from '${importPath}';\nconst { ${names.trim()} } = ${variable}.default || ${variable};`;
+    },
+  );
+
+  result = result.replace(
+    /import\s+(\w+)\s+from\s+['"](\.\/[^'"]+|\.\.\/[^'"]+|@\/[^'"]+)['"]/g,
+    (match, variableName, importPath) => {
+      if (variableName.startsWith('__infly_interop_')) return match;
+      if (importPath.includes('.vue')) return match;
+      if (isReExportTarget(projectRoot, id, importPath)) {
+        changed = true;
+        return `import * as ${variableName} from '${importPath}';`;
+      }
+      if (isCommonJsTarget(projectRoot, id, importPath)) {
+        const variable = `__infly_interop_${counter++}`;
+        changed = true;
+        return `import ${variable} from '${importPath}';\nconst ${variableName} = ${variable}.default || ${variable};`;
+      }
+      return match;
+    },
+  );
+
+  return changed ? { code: result, map: null } : null;
+}
+
+export function importInteropPlugin(projectRoot) {
+  return {
+    name: 'infly-vue2:import-interop',
+    enforce: 'pre',
+    transform(code, id) {
+      return transformImportInterop(
+        code,
+        id,
+        projectRoot,
+        (message) => this.warn(message),
+      );
+    },
+  };
+}

package/src/compat/jsx.mjs

@@ -0,0 +1,142 @@
+/**
+ * Vue 2 JSX 兼容
+ *
+ * 使用 Babel + @vue/babel-preset-jsx 将 JSX 语法转换为 h() 调用。
+ * 同时处理 .js 文件和 .vue 文件的 script 块。
+ * 回退方案：Vite 内置 esbuild。
+ *
+ * 从 factory.js transformJsx 和相关插件提取。
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+/**
+ * 将 JSX 代码转换为 JS
+ *
+ * @param {string} code - 源代码
+ * @param {string} id - 文件路径
+ * @param {string} projectRoot - 项目根目录
+ * @returns {{ code: string } | null}
+ */
+export function transformJsx(code, id, projectRoot) {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+
+  // 优先使用 Babel + @vue/babel-preset-jsx
+  try {
+    const babel = projectRequire('@babel/core');
+    const jsxPreset = (() => {
+      try {
+        return projectRequire('@vue/babel-preset-jsx');
+      } catch (_) {
+        return null;
+      }
+    })();
+
+    if (jsxPreset) {
+      const r = babel.transformSync(code, {
+        presets: [[jsxPreset, { injectH: true }]],
+        filename: id,
+        babelrc: false,
+        configFile: false,
+        compact: false,
+        shouldPrintComment: () => false,
+        minified: false,
+      });
+      return { code: r.code };
+    }
+  } catch (_) {
+    // 回退到 esbuild
+  }
+
+  // 回退：Vite 内置 esbuild
+  try {
+    const viteReq = createRequire(import.meta.resolve('vite'));
+    const esbuild = viteReq('esbuild');
+    const r = esbuild.transformSync(code, {
+      loader: 'jsx',
+      jsxFactory: 'h',
+      jsxFragment: 'Fragment',
+    });
+    return { code: r.code };
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 判断文件是否为 .vue 且包含 JSX script
+ */
+function isJsxCode(code) {
+  return code.includes('</') || code.includes('/>');
+}
+
+/**
+ * 创建 JSX 预处理插件（enforce: pre，在 @vitejs/plugin-vue2 之前运行）
+ *
+ * @param {string} projectRoot
+ * @returns {import('vite').Plugin}
+ */
+export function jsxPrePlugin(projectRoot) {
+  return {
+    name: 'infly-vue2:jsx-pre',
+    enforce: 'pre',
+    transform(code, id) {
+      // 仅处理项目源码中的 .js 文件
+      if (!id.endsWith('.js')) return null;
+      if (id.includes('node_modules') || id.includes('.cache') || id.includes('.vite')) return null;
+      if (!isJsxCode(code)) return null;
+      return transformJsx(code, id, projectRoot);
+    },
+  };
+}
+
+/**
+ * 创建 .vue script 块 JSX 预处理插件
+ *
+ * @param {string} projectRoot
+ * @returns {import('vite').Plugin}
+ */
+export function vueJsxPrePlugin(projectRoot) {
+  return {
+    name: 'infly-vue2:vue-jsx-pre',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!id.endsWith('.vue') || id.includes('node_modules')) return null;
+      if (!code.includes('<script')) return null;
+
+      let transformed = false;
+      const result = code.replace(
+        /<script\b([^>]*)>([\s\S]*?)<\/script>/g,
+        (match, attrs, content) => {
+          if (isJsxCode(content)) {
+            const r = transformJsx(content, id, projectRoot);
+            if (r) {
+              transformed = true;
+              return `<script${attrs}>${r.code}</script>`;
+            }
+          }
+          return match;
+        }
+      );
+      return transformed ? { code: result, map: null } : null;
+    },
+  };
+}
+
+/**
+ * 创建 JSX 清理插件（在 @vitejs/plugin-vue2 后捕获残留 JSX）
+ *
+ * @param {string} projectRoot
+ * @returns {import('vite').Plugin}
+ */
+export function jsxCleanupPlugin(projectRoot) {
+  return {
+    name: 'infly-vue2:jsx-cleanup',
+    transform(code, id) {
+      if (id.includes('node_modules') || id.includes('.vite')) return null;
+      if (!isJsxCode(code)) return null;
+      return transformJsx(code, id, projectRoot);
+    },
+  };
+}

package/src/compat/mock.mjs

@@ -0,0 +1,125 @@
+/**
+ * Mock 服务器兼容层
+ *
+ * 将项目的 Express mock-server.js 作为中间件挂载到 Vite dev server。
+ * 保留 chokidar 热重载功能。
+ *
+ * 从 compat/mock.js 迁移（70% 可复用）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import Module, { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../..',
+);
+const packageRequire = createRequire(import.meta.url);
+
+/**
+ * 在 Babel 转译下运行回调函数（兼容 CJS mock 代码）
+ */
+function withMockCommonJsTranspilation(projectRoot, callback) {
+  let register;
+  try {
+    register = packageRequire('@babel/register');
+  } catch (_) {
+    throw new Error(
+      '@infly/vue2-vite 安装不完整：缺少 @babel/register'
+    );
+  }
+  register({
+    babelrc: false,
+    configFile: false,
+    extensions: ['.js'],
+    ignore: [/node_modules/],
+    only: [projectRoot],
+    presets: [[
+      packageRequire.resolve('@babel/preset-env'),
+      { targets: { node: 'current' }, modules: 'commonjs' },
+    ]],
+  });
+  return callback();
+}
+
+function loadMockModule(mockServerPath, projectRoot) {
+  const mockModule = new Module(mockServerPath);
+  mockModule.filename = mockServerPath;
+  mockModule.paths = [
+    ...Module._nodeModulePaths(projectRoot),
+    ...Module._nodeModulePaths(PACKAGE_ROOT),
+  ];
+  mockModule._compile(fs.readFileSync(mockServerPath, 'utf8'), mockServerPath);
+  return mockModule.exports;
+}
+
+/**
+ * 创建 Vite configureServer 钩子，挂载 Express mock 子应用
+ */
+export function createMockMiddleware(options = {}) {
+  const { projectRoot, mockEntry = 'mock/mock-server.js', enabled = true } = options;
+
+  if (!enabled) return undefined;
+
+  const mockServerPath = path.resolve(projectRoot, mockEntry);
+
+  if (!fs.existsSync(mockServerPath)) {
+    console.warn(`[infly-vue2] mock 已启用但文件不存在: ${mockServerPath}`);
+    return undefined;
+  }
+
+  return function configureMockServer(server) {
+    try {
+      // 用包自身的 createRequire 加载 express（@infly/vue2-vite 的依赖）
+      const express = packageRequire('express');
+      const mockApp = express();
+
+      // 切换 cwd 到项目目录，使 mock-server 中相对路径正确
+      const originalCwd = process.cwd();
+      process.chdir(projectRoot);
+
+      try {
+        // mock 入口属于应用，但它的运行依赖由本包提供。组合两侧的
+        // node_modules 搜索路径，避免要求业务子仓重复声明构建适配依赖。
+        const mockServer = withMockCommonJsTranspilation(
+          projectRoot,
+          () => loadMockModule(mockServerPath, projectRoot),
+        );
+        mockServer(mockApp);
+
+        // 挂载到 Vite dev server
+        server.middlewares.use(mockApp);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    } catch (error) {
+      console.warn(
+        `[infly-vue2] 警告：无法加载 mock 服务器 (${mockServerPath}): ${error.message}`
+      );
+      console.warn(`[infly-vue2] mock 加载失败，dev server 仍可正常使用。`);
+    }
+  };
+}
+
+export function hasMockServer(options = {}) {
+  const {
+    projectRoot,
+    mockEntry = 'mock/mock-server.js',
+    enabled = true,
+  } = options;
+  return enabled && fs.existsSync(path.resolve(projectRoot, mockEntry));
+}
+
+/**
+ * 创建 mock 兼容 Vite 插件（含 configureServer 钩子）
+ */
+export function mockPlugin(options = {}) {
+  const configureServer = createMockMiddleware(options);
+
+  return {
+    name: 'infly-vue2:mock',
+    configureServer,
+  };
+}