vite-plugin-virtual-mpa ⚡

开箱即用的 Vite MPA插件 📦，支持HTML模板引擎和虚拟文件功能，能够使用一份模板生成多个文件。

English | 中文

主要功能

• 💡 EJS 模板渲染
• 💡 完备的 TypeScript 类型提示支持，是一款小而美的插件
• 🛠️ 自定义模板HTML文件的输出路径, 使用一份模板生成多份文件
• 🛠️ 支持 MPA 多页面应用，为开发和预览服务器提供 History Fallback 支持.

使用方式

1pnpm add -D vite-plugin-virtual-mpa # or npm/yarn

1// vite.config.ts
2import { createMpaPlugin, createPages } from 'vite-plugin-virtual-mpa'
3
4// @see https://vitejs.dev/config/
5export default defineConfig({
6  plugins: [
7    createMpaPlugin({
8      pages: [
9        // 你可以直接在这里书写页面配置，也可以单独使用 `createPages` 函数并将结果传递到这里。
10      ]
11    }),
12  ],
13})
14
15/**
16 * 该函数仅仅是将参数转换为一个 pages 数组。
17 * 它帮助你在插件之外创建页面配置，主要是为了能够拥有类型提示。
18 * 同时在别处统一管理配置的方式可能也能帮助你简化 vite 的配置文件。
19 */
20const pages = createPages([
21  // 你可以传递一个 page 对象或一个 pages 数组。
22])
23
24// @see https://vitejs.dev/config/
25export default defineConfig({
26  plugins: [
27    createMpaPlugin({
28      pages,
29    }),
30  ],
31})

Options

1type FilterPattern = string | RegExp | (string | RegExp)[]
2type RewriteRule = false | Rewrite[]
3interface WatchHandler {
4  (ctx: {
5    server: ViteDevServer,
6    file: string,
7    type: Event
8    /**
9     * 可以调用这个方法更新页面配置
10     * @params pages MPA 页面核心配置，这将会替换默认的 `pages`
11     */
12    reloadPages: (pages: Page[]) => void
13  }): void
14}
15
16interface MpaOptions {
17  /**
18   * 是否在控制台打印log
19   * @default true
20   */
21  verbose?: boolean,
22  /**
23   * 默认模板文件
24   * @default index.html
25   */
26  template?: `${string}.html`,
27  /**
28   * 为开发服务器配置 fallback rewrite rules，只会处理 accept=text/html 的文件请求。
29   * @see https://github.com/bripkens/connect-history-api-fallback
30   */
31  rewrites?: RewriteRule,
32  /**
33   * 为预览服务器配置重定向规则，配置方式同 rewrites。
34   * @see https://github.com/bripkens/connect-history-api-fallback
35   */
36  previewRewrites?: RewriteRule,
37  /**
38   * 处理模版 HTML 文件，继承自 `transformIndexHtml`。
39   * @see https://vitejs.dev/guide/api-plugin#transformindexhtml
40   */
41  transformHtml?: (
42    html: string,
43    ctx: IndexHtmlTransformContext & { page: Page },
44  ) => IndexHtmlTransformResult;
45  /**
46   * 用于扫描相似的目录结构，自动生成 pages 配置。
47   * 扫描到的配置会追加到 `pages` 中，具有相同 name 的 page 将被忽略
48   */
49  scanOptions?: {
50    /**
51     * 要扫描的目录，子目录名称将作为唯一的 page name。
52     */
53    scanDirs: string | string[];
54    /**
55     * 相对于扫描目录的入口文件路径
56     */
57    entryFile?: string;
58    /**
59     * 自定义虚拟文件的名称（输入文件名）
60     * @param name 子目录名称
61     */
62    filename?: (name: string) => string;
63  };
64  /**
65   * 当项目目录下有一些文件触发相应的事件如添加、删除、修改时，你可能想要重新加载 `pages` 配置 或 重启 ViteDevServer。
66   * 你可以通过设置 `watchOptions` 来实现这一目的。
67   */
68  watchOptions?: WatchHandler | {
69    /**
70     * 指定需要**包含**的文件，基于 `Rollup.createFilter` 过滤
71     * @see https://vitejs.dev/guide/api-plugin.html#filtering-include-exclude-pattern
72     */
73    include?: Exclude<FilterPattern, null>,
74    /**
75     * 指定需要**排除**的文件，基于 `Rollup.createFilter` 过滤
76     * @see https://vitejs.dev/guide/api-plugin.html#filtering-include-exclude-pattern
77     */
78    excluded?: Exclude<FilterPattern, null>,
79    /**
80     * 想要监听的文件事件
81     * @default ['add', 'unlink', 'change', 'unlinkDir', 'addDir']
82     */
83    events?: Event[],
84    /**
85     * 定义的文件事件触发后，执行自定义逻辑
86     */
87    handler: WatchHandler
88  },
89  pages: Array<{
90    /**
91     * 必填。该名称是一个不包含'/'的普通字符串，它用于生成默认的重定向规则。
92     * 如果你想自定义生成文件的路径，请使用filename选项，而不是name选项。
93     */
94    name: string;
95    /**
96     * 相对于`build.outDir`的路径，应该以html结尾
97     * @default `${name}.html`
98     */
99    filename?: `${string}.html`;
100    /**
101     * 更高优先级的模板文件，将会覆盖默认模板
102     */
103    template?: string;
104    /**
105     * 自动注入入口文件，如果设置了entry，需要移除模板文件中的entry
106     */
107    entry?: string;
108    /**
109     * 注入到模板文件的数据
110     */
111    data?: Record<string, any>,
112  }>,
113  /**
114   * 是否使用 html-minify-terser 压缩 html 文件
115   * @default false
116   * @see https://github.com/terser/html-minifier-terser
117   */
118  htmlMinify?: Options | boolean,
119}

Examples

点击链接 codesandbox 快速体验

1// vite.config.ts
2import { normalizePath } from "vite";
3import { createMpaPlugin } from "vite-plugin-virtual-mpa"
4
5const base = "/sites/"
6
7// @see https://vitejs.dev/config/
8export default defineConfig({
9  base,
10  plugins: [
11    createMpaPlugin({
12      htmlMinify: false,
13      pages: [
14        {
15          name: "apple",
16          /**
17           * 文件名是可选的，默认将会是`${name}.html`，这个路径是相对于`build.outDir`
18           */
19          filename: "fruits/apple.html", // 将会在编译时输出到sites/fruits/apple.html
20          entry: "/src/fruits/apple/index.js",
21          data: {
22            title: "This is Apple page"
23          }
24        },
25        {
26          name: "banana",
27          filename: "fruits/banana.html",
28          entry: "/src/fruits/banana/index.js",
29          data: {
30            title: "This is Banana page"
31          }
32        },
33        {
34          name: "strawberries",
35          filename: "fruits/strawberries.html",
36          entry: "/src/fruits/strawberries/index.js",
37          data: {
38            title: "This is Strawberries page"
39          }
40        }
41      ],
42      /**
43       * 以下示例的 scanOptions 配置可以替换上面的 pages 配置，除了 data 的注入。
44       */
45      scanOptions: {
46        scanDirs: 'src/fruits',
47        entryFile: 'index.js',
48        filename: name => `fruits/${name}.html`,
49        template: '../../template.html',
50      }
51      /**
52       * 通过该选项来配置 history fallback rewrite rules
53       * 如果你像上面这样配置页面的话，那下面的这份配置将会自动生成。
54       * 否则你需要自己编写重定向规则。
55       */
56      rewrites: [
57        {
58          from: new RegExp(normalizePath(`/${base}/(apple|banana|strawberries)`)),
59          to: (ctx) => normalizePath(`/fruits/${ctx.match[1]}.html`),
60        }
61      ],
62      /**
63       * 配置预览服务器的重定向规则，配置方式同 rewrites
64       */
65      previewRewrites: [
66        // 如果产物目录没有 index.html，你需要手动配置规则，以便服务器能正确找到入口文件。
67        { from: /.*/, to: '/home.html' },
68      ],
69      /** 自定义处理模板内容 */
70      transformHtml(html, ctx) {
71        return {
72          html,
73          tags: [
74            {
75              tag: 'div',
76              injectTo: 'body-prepend',
77              children: `[Auto Injected] Page name: ${ctx.page.name}`,
78            },
79          ],
80        };
81      },
82    }),
83  ],
84})

插件对比

使用vite开发构建 多页面应用(MPA) 的时候，我们通常需要一个具备以下能力的插件：

1. 具备模板引擎如ejs，能够使用一个模板生成多份文件，且能自定义构建时生成文件的路径。

2. 自动配置 rollupOptions.input，并提供能力配置开发服务器的代理（主要是history fallback api）。

市面上有非常多的关于vite的MPA插件，但他们却几乎没有能同时做到以上两点的。根据名称匹配度和下载量，我筛选到以下插件:

1. vite-plugin-mpa：可以自动配置入口，并提供开发服务器代理配置入口（fallback rule），但必须按照约定调整目录结构，且不支持模板引擎和虚拟入口，也无法定义生成文件的路径。

2. vite-plugin-html-template：这个插件的作者和vite-plugin-mpa是同一个人，算是作者推荐的配套插件，主要是和mpa插件组合使用以提供模板引擎功能，同样不支持虚拟入口。

3. vite-plugin-html：只支持模板引擎，且不支持虚拟入口。

4. vite-plugin-virtual-html：支持虚拟入口，提供了渲染接口，可以定制模板引擎。但没有内置模板引擎，用起来有点麻烦还是。

其中，"虚拟入口" 的意思是，通过一个模板文件，渲染出多个入口html文件。

其他插件大同小异，他们各有所长，但用起来总不趁手。要么需要搭配使用，要么对现有项目结构的改动较多。有时候我也好奇，既然实现了模板引擎，却又需要多个模板文件，这样做岂不是失去了模板的优势。

而这个插件便是为了解决这些问题，它同时具备上面提到的所有能力。通过结合虚拟入口和模板引擎，使得用户只需要一份模板就可以生成不同的入口html，且能自定义入口文件的输出路径（再也不用手动写脚本移动了！）。同时也提供了接口为开发服务器配置rewrite rules，以便开发时能够正确地请求到入口文件。

如果你的项目正在使用vite工作流且为MPA应用，不妨尝试一下这个插件，它不限制技术栈，与你是否使用vue还是react或其他技术无关。

默认重定向规则

正如上面提到的👆🏻，如果你的配置遵循约定，插件将会自动生成一份重定向规则，这份配置会同时应用到开发和预览服务器，如下：

1{
2  from: new RegExp(normalizePath(`/${base}/(${Object.keys(inputMap).join('|')})`)),
3  to: ctx => normalizePath(`/${base}/${inputMap[ctx.match[1]]}`),
4}

其中, inputMap 是一个name到对应虚拟文件的映射，结构如下:

1{
2  apple: 'fruits/apple.html',
3  banana: 'fruits/banana.html',
4  strawberries: 'fruits/strawberries.html',
5}

请求Url/sites/apple/xxx将会被默认重定向规则处理并重定向到对应的url，也就是/fruits/apple.html(name 'apple' 对应 'fruits/apple.html', 其他同理)，重定向后的路径将会基于viteConfig.base(这里是'/sites/')去寻找目标文件，所以最终的Url会变成/sites/fruits/apple.html.

关于虚拟入口文件

通常在开发时，我们的文件都是写在本地的，我们通过DevServer的代理能够通过url访问到本地对应的文件。虚拟文件也是如此，只不过对应的文件没有写到文件系统中，而是保存在内存中而已。

该插件通过模板系统生成了对应的虚拟文件，让你可以在开发时通过代理访问到内存中的虚拟文件，并在构建时生成到对应的目录下。

你完全可以认为这些虚拟文件是真实存在的，这将有助于你在脑海中构建关于虚拟文件的直觉，以便能够正确地编写代理配置。

关于 EJS 模板引擎

插件使用 ejs 模板引擎进行数据注入，除页面配置中提供的 data 外，插件默认会将以 'VITE_' 开头的环境变量注入所有的页面配置中，更多信息可以查看官网 —— envprefix。