@ggcv/vite-plugin-mpa

v1.0.0

Published

2 months ago

Vite 多页应用插件

0High
0Medium
0Low

ggchivalrous

mpa vite vite-plugin vue

vite-plugin-mpa

一款强大且灵活的 Vite 多页应用（MPA）构建与入口生成插件。它可以根据简单配置，自动为你生成各类页面的 HTML、入口 main.ts 及其对应的挂载应用组件 app.vue，并将虚拟文件映射给本地服务器，极大地简化了 Vite MPA 的繁琐配置。

特性

🚀 自动生成 HTML 与多页入口，内置美观默认模板。
🔍 强大的目录扫描规则，支持按文件夹分散配置。
⚙️ 支持自定义全局 HTML、入口与应用模板，提供丰富的占位符宏。
🛠️ 支持页面独立的 Title, Meta 标签与 Favicon 定制。
⚡ 完美融入 Vite dev-server 路由代理与生产环境 Rollup 产物归类。

安装

无需手动安装第三方依赖，直接装在你的项目中：

npm i @ggcv/vite-plugin-mpa -D
# 或是 pnpm
pnpm i @ggcv/vite-plugin-mpa -D

使用方法

在你的 vite.config.ts 中引入插件并配置：

import { defineConfig } from "vite";
import { mpaPlugin } from "@ggcv/vite-plugin-mpa";

export default defineConfig({
  plugins: [
    mpaPlugin({
      // 你可以在这里直接传入配置数组
      config: [
        { page: "home", title: "首页", output: "index" },
        { page: "admin", title: "后台系统" },
      ],
    }),
  ],
});

有了以上配置后，访问 http://localhost:5173/ （根路径）将自动加载 src/pages/home/index.vue。访问 http://localhost:5173/admin 会自动加载 src/pages/admin/index.vue。

动态参数宏 (Macros)

插件允许你提供自己的模板文件（通过 options.template、options.appTemplate 配置）。在模板解析过程中，系统会替换特定的参数宏。

1. HTML 模板支持的宏 (`options.template`)

如果你在根目录下编写了自己的 .html 模板，可在模板中使用以下占位符：

HTML 模板示例：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="%FAVICON%" />
    %META%
    <title>%TITLE%</title>
  </head>
  <body>
    <div id="app"></div>
    <!-- 这里必须要有，否则 Vite 没法加载入口 -->
    <script type="module" src="%ENTRY%"></script>
  </body>
</html>

2. Vue 应用入口层支持的宏 (`options.appTemplate`)

在覆盖应用挂载的模板时（生成最终的 app.vue 外壳）：

| 宏占位符 | 说明 | | :--------- | :--------------------------------------------------------------------------------------- | | // @Page | 会被准确替换为经过解析的（如绝对路径的）视图层组件 import Page from '...' 的引入语句。 |

配置与扫描规则

本插件在读取 MPA 页面配置时非常灵活，支持多种配置组合或分散管理方式。它的读取优先级规则按照以下流转：

1. 直接传递配置数组 (Direct Config Array)

如果你希望所有的多页入口能集中管理，这可以直接传给 options.config 数组：

mpaPlugin({
  config: [
    { page: "page1", title: "页面1" },
    { page: "page2", title: "页面2", appEntry: ["index", "detail"] },
  ],
});

2. 传递指定的配置文件路径 (Config File Path)

如果你希望把配置与 vite.config.ts 分开，你可以用字符串告诉插件去哪里加载配置：

mpaPlugin({
  config: "./config/mpa.config.ts",
});

该文件必须 export default 一个 Config 数组或单个对象。推荐使用插件自带的 defineMpaConfig 包裹，它自带类型推导。

3. 指定目录树的递归扫描 (Scan Directory)

（大型 MPA 项目推荐的方案）如果你没有传递 options.config，而是想让不同的页面各自管理自己的配置：你可以配置 options.scanDir。

mpaPlugin({
  scanDir: "src/pages", // 默认从这个目录开始寻找
});

扫描规则：

插件会深度递归遍历你指定的 scanDir。
在该目录下，只要匹配到目标文件名（可通过 options.scanFile 参数指定，也可以是数组），就会解析并收集这些文件的配置。
如果未手动指定 options.scanFile，默认将匹配以下四种文件名：
- mpa.config.ts
- mpa.config.js
- mpa.config.mjs
- mpa.config.cjs
将所有扫描到的文件内容执行合并。

参考目录结构：

src/pages/
├── home/
│   ├── index.vue
│   └── mpa.config.ts   // 配置导出：{ page: 'home', title: '首页' }
└── auth/
    ├── index.vue
    └── mpa.config.ts   // 配置导出：{ page: 'auth', title: '鉴权页' }

通过开启 scanDir 服务，各目录的独立页面配置互不打扰而且一目了然。

4. 根目录兜底自动查找 (Fallback)

如果以上三种（config 直接传递、config 字符串路径、scanDir）你一样都没有配置，插件会默默在你提供的 baseDir（如果不传就是所在项目的根目录）去尝试寻找默认配置入口文件（也就是上面列举出的四个 mpa.config.[ext]）。

页面配置详解 (`Config`)

每一个页面的单独入口配置具备极高的定制上限：

`defineMpaConfig` 的使用

插件内导出该函数可提供极佳的 IDE 编写体验：

// src/pages/user/mpa.config.ts
import { defineMpaConfig } from "@ggcv/vite-plugin-mpa";

export default defineMpaConfig({
  page: "user",
  title: "个人中心",
  metas: [{ name: "description", content: "个人账号配置模块" }],
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme