在 MPA 项目里，页面数量一多，入口维护很快会变成一件重复又容易出错的事。

新增一个页面，通常不只是新建一个 React 组件。你还要补 vite.config.ts 里的 rollupOptions.input，维护客户端入口、服务端入口、HTML 模板，有些页面还要注册路由、区分 SSR/CSR/Streaming。页面少的时候这些都能接受，到了二十多个页面以后，问题就开始变得明显：每个入口文件长得差不多，差别只是 import 的页面不同；配置散在几个地方，漏改一个就可能导致本地能跑、构建不对，或者路由挂不上。

这篇文章记录的是我们在 BFF 页面系统里做的一次插件化改造：页面只声明一个 config.toml，剩下的页面发现、模板匹配、虚拟入口生成、路由挂载和开发时重载，都交给 Vite 插件完成。

问题从哪里来

// 传统 MPA：每次新增页面都要记得维护 input
export default {
  build: {
    rollupOptions: {
      input: {
        cart: 'src/pages/cart/index.html',
        checkout: 'src/pages/checkout/index.html',
        account: 'src/pages/my-account/index.html',
        // ... 第 21 个页面，你还记得加吗？
      }
    }
  }
}

这段配置本身不复杂，真正麻烦的是它背后代表的维护方式：页面注册依赖人工约定，入口文件重复，SSR 和 CSR 还要各自维护一套入口逻辑。如果页面还有多种渲染模式，重复代码会继续膨胀。

我们希望页面目录自己能说明它是谁、用什么模板、挂到哪个域名和路径上。开发者只需要关心页面业务代码，构建系统根据这些声明生成需要的入口。

核心思路

核心链路并不绕：先扫描页面配置，得到一组页面元信息；再根据页面类型找到模板；然后把模板注册成虚拟模块；最后让 Vite 在 Dev 和 Build 两种模式下消费这些虚拟模块。

这里没有生成 .next/ 或 .nuxt/ 那样的临时目录。中间文件都放在内存里的 Map<string, () => string>，等 Vite 真正请求某个模块时再生成代码。这样工作目录保持干净，开发时也不需要提前处理所有页面。

先看虚拟模块

Vite 虚拟模块本身不神秘，本质上是插件在编译阶段“认出一个不存在于磁盘上的模块”，再返回一段代码。最小实现通常只需要两个 Hook：

const PREFIX = '@virtual:my-plugin';
 
export default function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    
    // 拦截 import 请求
    resolveId(id) {
      if (id.startsWith(PREFIX)) return '\0' + id;
    },
    
    // 返回动态生成的模块代码
    load(id) {
      if (id.startsWith('\0' + PREFIX)) {
        return `export const data = "generated at compile time";`;
      }
    },
  };
}

\0 前缀是 Rollup 的约定，用来标记这个 ID 已经被插件解析过，后续插件不要再当成普通文件路径处理。

	Dev (serve)	Build
模块路径	`/@virtual:...`（走 HTTP）	`@virtual:...`（内存解析）
加载时机	按需（浏览器请求时）	全量（Rollup 遍历依赖图）
HMR	必须支持	无需

Dev 和 Build 的路径差异是后面很多实现细节的来源。开发环境里，浏览器通过 HTTP 请求模块，所以虚拟模块要能被 Vite dev server 的中间件识别；构建时走 Rollup 的模块图，不需要 HTTP 路径。

页面从 `config.toml` 开始

每个页面用一个 TOML 文件声明身份：

# src/pages/cart/config.toml
[page]
type = "react-ssr"
 
[router]
domain = "<%=SERVER_OFFICIAL_DOMAIN%>"
# path 省略 → 默认取目录名 "/cart"

type = "react-ssr" 决定这个页面使用哪套模板，router 决定页面挂到哪里。如果没有显式声明 path，就默认使用页面目录名。

扫描阶段会做几件事：找到所有 config.toml，解析页面配置，确认页面入口文件存在，再解析模板。这里的代码可以简化成下面这样：

import fg from 'fast-glob';
import * as toml from 'smol-toml';
 
async function scanPages(root: string): Promise<Map<string, IPage>> {
  const pages = new Map();
  const configs = await fg('src/pages/**/config.toml', { cwd: root });
  configs.sort(); // 确保注册顺序确定性
 
  for (const configPath of configs) {
    const raw = await fs.promises.readFile(path.join(root, configPath), 'utf-8');
    const config = toml.parse(raw);
    
    const dir = path.dirname(configPath);
    const pageId = encodeURIComponent(dir.replace('src/pages/', ''));
    
    // 入口文件必须存在
    const entries = await fg(path.join(root, dir, '+Page.ts'));
    if (!entries.length) continue;
    
    // 解析模板（自定义 > 默认）
    const template = await resolveTemplate(root, dir, config.page.type);
    if (!template) continue;
    
    pages.set(pageId, {
      id: pageId, dir, entry: entries[0],
      type: config.page.type,
      router: {
        domain: config.router.domain,
        path: config.router.path ?? [`/${dir.replace('src/pages/', '')}`],
      },
      template,
    });
  }
  return pages;
}

模板解析也留了一个覆盖入口：页面自己的 templates/ 优先于全局 templates/{page.type}/。大多数页面可以复用默认模板，少数特殊页面也能单独接管，不需要把特殊逻辑塞回公共模板里。

虚拟模块的 ID 怎么设计

const PLUGIN_NAME = 'vite-plugin-mpa-virtual-ssr';
 
// Build: Rollup 内存解析
const BUILD_PREFIX  = `@virtual:${PLUGIN_NAME}`;
// Dev: HTTP 路径拦截
const DEV_PREFIX    = `/@virtual:${PLUGIN_NAME}`;
// 系统模块（环境注入等）
const SYS_PREFIX    = `/@virtual-sys:${PLUGIN_NAME}`;

模块 ID 格式：{prefix}/{pageId}/{fileName}

/@virtual:vite-plugin-mpa-virtual-ssr/cart/entry-client.tsx
/@virtual:vite-plugin-mpa-virtual-ssr/cart/entry-server.tsx
/@virtual:vite-plugin-mpa-virtual-ssr/cart/index.html

ID 设计看起来只是命名问题，但它会影响后面的解析、HMR 和构建产物。我们把页面 ID、文件名和环境前缀都放进模块 ID 里，这样 entry-client.tsx、entry-server.tsx、index.html 都能被当成同一个页面下的虚拟文件处理。

用模板生成入口

每个页面会注册 3 到 4 个虚拟文件。内容不是提前写死，而是在加载时读取模板，再替换页面入口路径。

function registerVirtualFiles(ctx: PluginContext, pageId: string, page: IPage) {
  const p = prefix(); // Dev or Build prefix
  
  // 客户端入口：模板 + 替换动态 import 路径
  ctx.virtualFiles.set(`${p}/${pageId}/entry-client.tsx`, () => {
    const tpl = fs.readFileSync(
      path.join(page.template.page.dir, 'entry-client.tsx'), 'utf-8'
    );
    return tpl.replace('$DYNAMIC_ENTRY_IMPORT$', page.entry);
  });
  
  // 服务端入口：同理
  ctx.virtualFiles.set(`${p}/${pageId}/entry-server.tsx`, () => {
    const tpl = fs.readFileSync(
      path.join(page.template.page.dir, 'entry-server.tsx'), 'utf-8'
    );
    return tpl.replace('$DYNAMIC_ENTRY_IMPORT$', page.entry);
  });
  
  // HTML 模板
  ctx.virtualFiles.set(`${p}/${pageId}/index.html`, () => {
    const tpl = fs.readFileSync(
      path.join(page.template.page.dir, 'index.html'), 'utf-8'
    );
    return tpl.replace('$DYNAMIC_ENTRY_IMPORT$', `${p}/${pageId}/entry-client.tsx`);
  });
}

这里的 virtualFiles 存的是函数，而不是字符串。原因很简单：开发模式下不是所有页面都会被访问，没必要启动时就读取所有模板、替换所有入口。等 Vite 真正加载某个虚拟模块时，再执行对应的生成函数就够了。

模板里会出现几类占位符。 $DYNAMIC_ENTRY_IMPORT$ 在虚拟模块加载时替换成真实页面入口；<%=ENV_VAR%> 这类环境变量在扫描配置时处理；"$DEFINE_{__isCSR__}$" 这类宏交给构建阶段替换。

客户端入口模板大概长这样：

// templates/react-ssr/page/entry-client.tsx
import ReactDOM from 'react-dom/client';
import React from 'react';
// @ts-expect-error - 构建时替换为实际路径
import App from '$DYNAMIC_ENTRY_IMPORT$';
import * as $Template from '#/src/shared/template';
 
async function renderPage(): Promise<void> {
  const Page = $Template.getPageEntry(App);
  const meta = $Template.getSSRPageMeta(App);
  const SSR_RENDER_DATA = await $Template.requestTransformData(
    $Template.getDataFromDom<$Template.IRenderContext<{}>>('ssr-render-data', '__SSR_RENDER_DATA__') 
      ?? { fetchState: {} },
    meta.transform,
  );
 
  ReactDOM.hydrateRoot(
    document.getElementById('root')!,
    <React.StrictMode>
      <Page ctx={SSR_RENDER_DATA} />
    </React.StrictMode>,
  );
}
 
renderPage().catch(console.error);

@ts-expect-error 是有意保留的。模板文件里的 $DYNAMIC_ENTRY_IMPORT$ 不是合法路径，但运行时已经被插件替换成真实页面入口。这样一套 entry-client.tsx 模板可以服务所有同类型页面，差异只在 import 的页面模块。

插件骨架

export function createMpaVirtualSsrPlugin(options: PluginOptions): Plugin {
  const ctx: PluginContext = { pages: new Map(), virtualFiles: new Map() };
  let resolvedConfig: ResolvedConfig;
 
  return {
    name: PLUGIN_NAME,
 
    // ── 配置阶段 ──────────────────────────────
    async configResolved(config) {
      resolvedConfig = config;
      ctx.pages = await scanPages(config.root);
      for (const [id, page] of ctx.pages) {
        registerVirtualFiles(ctx, id, page);
      }
    },
 
    // 构建模式：自动注入 Rollup input entries
    config() {
      if (resolvedConfig?.command === 'build') {
        const input: Record<string, string> = {};
        for (const [pageId] of ctx.pages) {
          input[`${pageId}/index.html`] = `${BUILD_PREFIX}/${pageId}/index.html`;
        }
        return { build: { rollupOptions: { input } } };
      }
    },
 
    // ── 解析阶段 ──────────────────────────────
    resolveId(source, importer) {
      const p = prefix();
      if (source.startsWith(p)) return '\0' + source;
      
      // 虚拟模块间的相对 import
      if (importer?.startsWith('\0' + p) && source.startsWith('.')) {
        const resolved = path.posix.join(path.posix.dirname(importer.slice(1)), source);
        for (const ext of ['.ts', '.tsx', '.js', '.jsx', '']) {
          if (ctx.virtualFiles.has(resolved + ext)) return '\0' + resolved + ext;
        }
      }
    },
 
    // ── 加载阶段 ──────────────────────────────
    async load(id) {
      const p = prefix();
      if (!id.startsWith('\0' + p)) return;
      
      const generator = ctx.virtualFiles.get(id.slice(1));
      if (!generator) return;
      
      const code = await generator();
      const ext = path.extname(id);
      
      // TSX/TS → SWC 编译
      if (ext === '.tsx' || ext === '.ts') {
        const result = transformSync(code, {
          jsc: { parser: { syntax: 'typescript', tsx: ext === '.tsx' }, target: 'es2020' },
          sourceMaps: true,
          filename: id,
        });
        return { code: result.code, map: result.map };
      }
      return code;
    },
 
    // ── HMR ──────────────────────────────────
    configureServer(server) {
      server.watcher.on('change', handleFileChange);
      server.watcher.on('add', handleFileChange);
    },
  };
}

这段骨架里有两个点比较关键。

第一个是 resolveId 里要处理虚拟模块之间的相对引用。虚拟模块不是磁盘文件，Vite 不知道 ./foo 应该落到哪里，所以插件要自己根据 importer 补齐路径并匹配扩展名。

第二个是 load 阶段要对 TS/TSX 做一次编译。模板最终交给 Vite 消费时，仍然需要返回可执行的 JavaScript 和 sourcemap。

服务端怎么消费虚拟模块

SSR 模板里还有一个服务端 Handle。它不直接关心页面文件在磁盘上的路径，而是通过 ctx.loadFileModule('entry-server.tsx') 加载当前页面的服务端入口：

// templates/react-ssr/server/index.ts（生产代码）
import { Page, Utils, Flags, type Types } from '@reolink-web/bff-pages-server-core';
import serialize from 'serialize-javascript';
import * as $Template from '#/src/shared/template';
 
interface ServerModule<T = unknown> {
  render: (ctx: $Template.IRenderContext<T>, url: string) => Types.PromiseOrValue<string>;
  default: $Template.IEntrySSRModule<T>;
}
 
export default Page.defineHandle({
  htmlBuildInSlots: async (ctx) => {
    const module = await ctx.loadFileModule<ServerModule>('entry-server.tsx');
    const meta = $Template.getSSRPageMeta(module.default);
    return {
      '<!--meta-build-in-->': Utils.serializeTags(await meta.metaBuildIn?.()),
    };
  },
 
  htmlRuntimeSlots: async (ctx) => {
    const module = await ctx.loadFileModule<ServerModule>('entry-server.tsx');
    const meta = $Template.getSSRPageMeta(module.default);
 
    return Flags.createFlagsChainTask(
      async () => (await meta.fetch?.(Page.extraHandleRuntimeInnerContext(ctx))) ?? null,
    )
      .chain(async (fetchState) => {
        const renderContext: $Template.IRenderContext = { fetchState };
        const pageMeta = Utils.serializeTags(await meta.meta?.(renderContext, ctx));
        return [pageMeta, renderContext] as const;
      })
      .chain(async ([meta, context]) => ({
        '<!--meta-runtime-->': meta,
        '<!--app-head-->': `<script id="ssr-render-data">window.__SSR_RENDER_DATA__=${serialize(context)};</script>`,
        '<!--app-html-->': await module.render(context, ctx.routerContext.originalUrl),
        '<!--lang-->': ctx.handleContext.lang || 'en',
      }));
  },
});

这一步把前面的链路串起来了：config.toml 声明页面，插件生成虚拟入口，Handle 加载 entry-server.tsx，再执行页面自己的 fetch、meta 和 render。

HMR 不能只做 full reload

页面入口变了、配置变了、新页面加进来了、页面被删了，这几类变更对系统的影响不一样。如果全部做 full reload，逻辑最简单，但开发体验会比较粗糙；如果全部走模块热替换，又处理不了路由和模板变化。

所以这里按文件类型做了分层监听：

+Page.ts 内容更新时，可以走虚拟模块 HMR。config.toml 更新时，就不能只替换模块了，因为它可能改了路由、页面类型或模板，需要卸载旧页面、重新注册，再重建路由。删除配置时要移除页面；新增配置时还要解决一个额外问题：这个文件之前并不在任何已注册的监听范围里。

新增页面靠 Dynamic Matcher 兜住：

triggerScope.addTriggerDynamicMatcher(
  async (filePath, event) => {
    if (event !== 'create') return false;
    // 确认是 pages 目录下的 config.toml
    const allConfigs = await fg('src/pages/**/config.toml');
    if (!allConfigs.includes(filePath)) return false;
    // TOML 格式必须合法才触发（开发者可能还在敲）
    try {
      toml.parse(await fs.promises.readFile(filePath, 'utf-8'));
      return true;
    } catch {
      return false; // 格式不对，等 update 事件再说
    }
  },
  [(event, hooks) => hooks.reload()]
);

这里刻意等 TOML 能被正常解析后再触发 reload。开发者刚创建文件时，内容可能还没写完，如果每次保存半截配置都重建一次页面，开发服务器很容易报一堆没有意义的错误。

SSR 下的 CSS 依赖

SSR 还有一个容易被忽略的点：React 组件里会正常 import './style.css'，但服务端渲染时并不需要真正执行 CSS。我们需要的是记录它依赖了哪些 CSS，最后在 HTML 里注入对应的 <link>。

load(id, options) {
  if (options?.ssr && isCSSRequest(id)) {
    ctx.ssrCssImportIds.add(id);        // 记录依赖
    if (cssModuleRE.test(id)) {
      ctx.ssrCssModuleImportIds.add(id); // CSS Modules 额外追踪
    }
  }
  // ...
}

构建产物中根据收集结果自动注入：

<link rel="stylesheet" href="/assets/cart-a1b2c3.css">
<link rel="stylesheet" href="/assets/shared-d4e5f6.css">

这样页面开发者不需要手动维护样式清单，还是按照组件自己的方式 import CSS。插件只是在 SSR 编译阶段把这些依赖收集起来。

Dev 和 Build 的分叉

if (envMode === 'dev') {
  // 包一层 async wrapper，支持 HMR + 环境标识
  systemVirtualFiles[fileId] = () => `
    globalThis.__isServerSide__ = false;
    globalThis.__isClientSide__ = true;
    async function main() { return import('${escapedPageEntry}'); }
    main().catch(console.error);
  `;
}
 
if (envMode === 'build') {
  // 直接收集为 Rollup input
  const input = {};
  for (const [pageId] of ctx.pages) {
    input[`${pageId}/index.html`] = `${BUILD_PREFIX}/${pageId}/index.html`;
  }
  rollupOptions.input = input;
}

同一套页面元信息，在 Dev 和 Build 下消费方式不一样。

Dev 模式更关注“按需”和“可重载”，所以入口外面会包一层 async wrapper，用来设置环境标识并承接 HMR。Build 模式更关注静态依赖图，插件要把所有页面的 HTML 虚拟入口收集成 Rollup input，让构建阶段能完整遍历。

和框架生成目录的区别

Next.js、Nuxt 这类框架也会做页面扫描、入口生成和路由注册，只是它们通常会把中间产物落到 .next/、.nuxt/ 这类目录里。

我们的场景更偏项目内部的 BFF 页面系统，不需要做成一个完整框架，所以选择了虚拟模块。它的好处是改造面小，工作目录不会多出一堆 generated 文件；代价是插件要自己处理 ID 设计、相对 import、HMR、CSS 依赖这些工程细节。

一个最小版本

如果只看核心机制，可以从这个小插件开始：

import fg from 'fast-glob';
import type { Plugin } from 'vite';
 
export function miniMpaPlugin(): Plugin {
  const pages = new Map<string, string>();
 
  return {
    name: 'mini-mpa',
    async configResolved(config) {
      const configs = await fg('src/pages/*/config.toml', { cwd: config.root });
      for (const f of configs) {
        const id = path.basename(path.dirname(f));
        pages.set(id, path.join(config.root, path.dirname(f), 'index.tsx'));
      }
    },
    resolveId(id) {
      if (id.startsWith('virtual:page/')) return '\0' + id;
    },
    load(id) {
      if (!id.startsWith('\0virtual:page/')) return;
      const pageId = id.replace('\0virtual:page/', '');
      const entry = pages.get(pageId);
      if (!entry) return;
      return `
        import { createRoot } from 'react-dom/client';
        import App from '${entry}';
        createRoot(document.getElementById('root')).render(<App />);
      `;
    }
  };
}

它只做了三件事：扫描页面、识别虚拟模块、返回入口代码。真实项目里再逐步补上 SSR 模板、占位符替换、HMR Watch、CSS 追踪和多渲染模式。

小结

虚拟模块本身并不复杂，核心就是 resolveId 负责认出模块，load 负责把代码交给 Vite。真正需要花时间设计的是后面的工程问题：模块 ID 如何稳定命名，虚拟模块之间的相对路径怎么解析，配置变更如何触发合适粒度的重载，SSR 下的 CSS 依赖怎么收集。

当这些问题都收拢到插件里以后，页面开发就会轻很多。新增页面只需要放一个 config.toml 和业务入口，构建系统会根据声明补齐入口、模板、路由和运行时加载逻辑。这也是虚拟模块在 MPA 项目里最实用的地方：它把重复的入口维护从页面代码里拿走，集中放到一个可演进的插件里。

0 条评论

发表评论