@minar-kotonoha/vite-plugin-miko 0.2.0

package/README.md

@@ -0,0 +1,181 @@
+# @minar-kotonoha/vite-plugin-miko
+
+Miko 总控插件 — 一行搞定 Vue 3 SSG 项目的全部 Vite 配置。**零配置即可运行。**
+
+## 内置
+
+| 类别 | 插件 | 说明 |
+|------|------|------|
+| Vue 生态 | Vue / Vue JSX / Vue Macros / Vue Router | 文件系统路由、TSX 支持 |
+| 布局 | vite-plugin-vue-layouts-next | 默认布局 + 项目布局 |
+| 组件 | unplugin-vue-components | Vant 4 / Element Plus 自动导入 |
+| 样式 | UnoCSS | 原子化 CSS |
+| 兼容 | @vitejs/plugin-legacy | chrome 49, ios 10 |
+| 检查 | @minar-kotonoha/linter | 构建时 Oxlint + ESLint |
+| 启动 | vite-plugin-bootstrap | virtual:bootstrap 自动发现入口 |
+| 外部化 | vite-plugin-external | 生产环境 CDN 加载 |
+| 入口 | vite-plugin-index-html | dev/prod root 分离 |
+| SSG | vite-ssg | beasties + flat 目录 |
+| 可选 | Janus | 接口拦截器，安装后自动发现 |
+
+## 用法
+
+```ts
+// vite.config.ts
+import { defineMikoConfig } from '@minar-kotonoha/vite-plugin-miko'
+export default await defineMikoConfig()
+```
+
+可选创建 `miko.config.ts` 覆盖默认值：
+
+```ts
+import type { MikoUserConfig } from '@minar-kotonoha/vite-plugin-miko'
+
+export default {
+  uiLibrary: 'vant',
+  proxy: [
+    { context: ['/api/**'], target: 'https://dev.example.com', changeOrigin: true },
+  ],
+} satisfies MikoUserConfig
+```
+
+## 配置参考
+
+以下所有字段均为可选，包含完整默认值。
+
+### 基础路径
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `template` | `string` | 自动探测 | 模板目录（含 App.vue, main.ts, index.html, layouts/） |
+| `entry` | `string` | `<template>/main.ts` | 应用入口文件路径 |
+| `outDir` | `string` | `'./dist'` | 构建输出目录 |
+| `pagesDir` | `string` | `'./pages'` | 文件系统路由的页面目录 |
+
+### UI 框架
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `uiLibrary` | `'vant' \| 'element-plus'` | `'vant'` | UI 组件库 |
+
+### 布局
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `layout` | `string` | `'flexible'` | 默认布局名（`layouts.defaultLayout` 的快捷方式） |
+| `layouts.defaultLayout` | `string` | `'flexible'` | 默认布局名（与 `layout` 等效，优先级更高） |
+| `layouts.layoutsDirs` | `string \| string[]` | `['<template>/layouts', '<cwd>/layouts']` | 布局文件目录 |
+| `layouts.pagesDirs` | `string \| string[]` | `'<cwd>/pages'` | 页面文件目录 |
+
+### 开发服务器
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `proxy` | `ProxyConfig[]` | `[]` | 开发服务器代理规则 |
+| `dev.bundledDev` | `boolean` | `true` | 启用 Rolldown bundledDev |
+| `dev.port` | `number` | 自动分配 | 开发服务器端口 |
+| `dev.open` | `boolean \| string` | `false` | 自动打开浏览器 |
+
+### Vue 核心
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `vue` | `VuePluginOptions` | `{}` | `@vitejs/plugin-vue` 选项透传 |
+| `vueJsx` | `VueJsxPluginOptions` | `{}` | `@vitejs/plugin-vue-jsx` 选项透传 |
+
+### 路由
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `vueRouter.extensions` | `string[]` | `['.vue', '.setup.tsx']` | 路由文件扩展名 |
+| `vueRouter.routesFolder` | `string` | `<pagesDir>` | 路由扫描目录 |
+| `vueRouter.dts` | `string` | `'<cwd>/types/routes.d.ts'` | 路由类型声明路径 |
+
+### 组件自动导入
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `components.dirs` | `string \| string[]` | `['./components']` | 组件扫描目录 |
+| `components.extensions` | `string[]` | `['vue', 'tsx', 'ts']` | 组件文件扩展名 |
+| `components.dts` | `string \| boolean` | `'<cwd>/types/components.d.ts'` | 组件类型声明路径 |
+
+### UnoCSS
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `unoCSS` | `UnoCSSOptions \| false` | `{ configFile: false }` | 设为 `false` 禁用。`configFile: false` 使用默认预设 |
+
+### 浏览器兼容
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `legacy` | `LegacyOptions \| false` | `{ targets: ['chrome 49', 'ios 10'] }` | 设为 `false` 禁用 legacy |
+
+### SSG
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `ssg` | `SSGConfig \| false` | — | 设为 `false` 禁用 SSG（降级为纯 SPA） |
+| `ssg.beastiesOptions` | `object` | `{ external: false }` | 资源内联与压缩 |
+| `ssg.dirStyle` | `'flat' \| 'nested'` | `'flat'` | 输出目录结构 |
+| `ssg.formatting` | `'none' \| 'prettier'` | `'none'` | HTML 格式化 |
+
+### 代码检查
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `linter` | `LinterOptions \| false` | `{ oxlint: true, eslint: true }` | 设为 `false` 禁用 linter |
+
+### CDN 外部化
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `external.frameworkCDN` | `string` | `unpkg` 自动地址 | Framework CDN 地址，覆盖 `.env` 中的 `VITE_FRAMEWORK_CDN` |
+
+### Bootstrap
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `bootstrap.entryFile` | `string` | `'index.ts'` | 启动入口文件名（相对于 cwd） |
+
+### Janus
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `janus` | `JanusOptions \| false` | 自动发现 | 设为 `false` 禁用。安装 `@janus/unplugin` 后自动启用 |
+
+### 库模式
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `lib.entry` | `string` | — | 库入口文件 |
+| `lib.formats` | `('es' \| 'cjs' \| 'umd')[]` | `['es', 'cjs']` | 输出格式 |
+| `lib.name` | `string` | — | 全局变量名（UMD） |
+| `lib.fileName` | `string` | — | 输出文件名 |
+
+## 导出
+
+```ts
+import {
+  defineMikoConfig,    // 统一入口 — await defineMikoConfig()
+  loadMikoConfig,      // 加载 miko.config.ts
+  createLibConfig,     // 库模式配置工厂
+  // 类型
+  type MikoUserConfig,
+  type ProxyConfig,
+  type LibConfig,
+  type SSGConfig,
+  type VueOptions,
+  type VueJsxOptions,
+  type VueRouterOptions,
+  type LayoutsUserOptions,
+  type LegacyOptions,
+  type ComponentsOptions,
+  type UnoCSSVitePluginConfig,
+  type LinterOptions,
+  type BootstrapOptions,
+  type ExternalOptions,
+  type DevOptions,
+  type JanusOptions,
+} from '@minar-kotonoha/vite-plugin-miko'
+```

package/index.ts

@@ -0,0 +1,523 @@
+/**
+ * # @minar-kotonoha/vite-plugin-miko
+ *
+ * `defineMikoConfig` — 一行搞定 Vue 3 SSG 项目的全部 Vite 配置。
+ *
+ * 所有插件直接展开在 defineConfig 中（不嵌套），兼容 vite-ssg。
+ *
+ * ===== 用法 =====
+ *
+ * vite.config.ts:
+ *   import { defineMikoConfig } from '@minar-kotonoha/vite-plugin-miko'
+ *   export default await defineMikoConfig()
+ *
+ * miko.config.ts（可选，零配置即可运行）:
+ *   export default {
+ *     uiLibrary: 'vant',
+ *     proxy: [{ context: ['/api/**'], target: 'https://dev.example.com' }],
+ *   } satisfies import('@minar-kotonoha/vite-plugin-miko').MikoUserConfig
+ */
+
+import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { remove } from 'fs-extra'
+import { defineConfig, mergeConfig } from 'vite'
+import type { PluginOption, ProxyOptions, UserConfig } from 'vite'
+
+// Vue 生态
+import vue from '@vitejs/plugin-vue'
+import vueJsx from '@vitejs/plugin-vue-jsx'
+import VueRouter from 'vue-router/vite'
+import VueMacros from 'vue-macros/vite'
+
+// Layouts
+import Layouts from 'vite-plugin-vue-layouts-next'
+
+// Linter
+import linterPlugin from '@minar-kotonoha/linter/vite'
+
+// Legacy
+import legacy from '@vitejs/plugin-legacy'
+
+// Components auto-import
+import Components from 'unplugin-vue-components/vite'
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+import { VantResolver } from '@vant/auto-import-resolver'
+
+// UnoCSS
+import UnoCSS from 'unocss/vite'
+
+// Miko 子插件
+import { bootstrapPlugin } from '@minar-kotonoha/vite-plugin-bootstrap'
+import { externalPlugin } from '@minar-kotonoha/vite-plugin-external'
+import { indexHTMLPlugin } from '@minar-kotonoha/vite-plugin-index-html'
+
+// 类型
+import type {
+  MikoUserConfig,
+  ProxyConfig,
+  LibConfig,
+  SSGConfig,
+  VueOptions,
+  VueJsxOptions,
+  VueRouterOptions,
+  LayoutsUserOptions,
+  LegacyOptions,
+  ComponentsOptions,
+  UnoCSSVitePluginConfig,
+  LinterOptions,
+  BootstrapOptions,
+  ExternalOptions,
+  DevOptions,
+  JanusOptions,
+} from './types'
+
+// 重新导出类型供外部使用
+export type {
+  MikoUserConfig,
+  ProxyConfig,
+  LibConfig,
+  SSGConfig,
+  VueOptions,
+  VueJsxOptions,
+  VueRouterOptions,
+  LayoutsUserOptions,
+  LegacyOptions,
+  ComponentsOptions,
+  UnoCSSVitePluginConfig,
+  LinterOptions,
+  BootstrapOptions,
+  ExternalOptions,
+  DevOptions,
+  JanusOptions,
+}
+
+const cwd = process.cwd()
+
+// ===================================================================
+// 默认值常量
+// ===================================================================
+
+const DEFAULTS = {
+  uiLibrary: 'vant' as const,
+  layout: 'flexible',
+  outDir: './dist',
+  pagesDir: './pages',
+  componentsDir: './components',
+  entryFile: 'index.ts',
+  extensionsRoute: ['.vue', '.setup.tsx'] as string[],
+  extensionsComponent: ['vue', 'tsx', 'ts'] as string[],
+  legacyTargets: ['chrome 49', 'ios 10'] as string[],
+  bundledDev: true,
+} as const
+
+// ===================================================================
+// 路径探测
+// ===================================================================
+
+function detectTemplate(): string {
+  const local = resolve(cwd, 'template')
+  if (existsSync(local)) return local
+  const pkgRelative = fileURLToPath(new URL('../../template', import.meta.url))
+  if (existsSync(pkgRelative)) return pkgRelative
+  return local
+}
+
+function detectEntry(template: string): string {
+  return resolve(template, 'main.ts')
+}
+
+// ===================================================================
+// 配置加载
+// ===================================================================
+
+/**
+ * 从 `miko.config.ts` 加载用户配置。
+ * 文件不存在或解析失败时返回空对象。
+ */
+export async function loadMikoConfig(): Promise<MikoUserConfig> {
+  const configPath = resolve(cwd, 'miko.config.ts')
+  if (!existsSync(configPath)) return {}
+  try {
+    const mod = await import(configPath)
+    return (mod.default || mod) as MikoUserConfig
+  } catch {
+    return {}
+  }
+}
+
+// ===================================================================
+// 配置解析 —— 将用户配置与默认值合并
+// ===================================================================
+
+interface ResolvedConfig {
+  template: string
+  entry: string
+  outDir: string
+  pagesDir: string
+  uiLibrary: 'vant' | 'element-plus'
+  layout: string
+  layoutsDirs: string[]
+  proxy: ProxyConfig[] | undefined
+  lib: LibConfig | undefined
+
+  // 插件深度配置
+  vue: VueOptions
+  vueJsx: VueJsxOptions
+  vueRouter: VueRouterOptions
+  layouts: LayoutsUserOptions
+  components: ComponentsOptions
+  unoCSS: UnoCSSVitePluginConfig | false
+  legacy: LegacyOptions | false
+  ssg: SSGConfig | false
+  linter: LinterOptions | false
+  bootstrap: BootstrapOptions
+  external: ExternalOptions
+  dev: DevOptions
+  janus: JanusOptions | false
+}
+
+function resolveConfig(cfg: MikoUserConfig): ResolvedConfig {
+  const template = cfg.template || detectTemplate()
+  const entry = cfg.entry || detectEntry(template)
+  const outDir = cfg.outDir ? resolve(cwd, cfg.outDir) : resolve(cwd, DEFAULTS.outDir)
+  const pagesDir = cfg.pagesDir ? resolve(cwd, cfg.pagesDir) : resolve(cwd, DEFAULTS.pagesDir)
+
+  // === 布局 ===
+  const layout = cfg.layouts?.defaultLayout ?? cfg.layout ?? process.env.VITE_LAYOUT ?? DEFAULTS.layout
+  const layoutsDirs = cfg.layouts?.layoutsDirs
+    ? (Array.isArray(cfg.layouts.layoutsDirs) ? cfg.layouts.layoutsDirs : [cfg.layouts.layoutsDirs])
+    : [resolve(template, 'layouts'), resolve(cwd, './layouts')]
+
+  // === Vue Router ===
+  const vueRouter: VueRouterOptions = {
+    extensions: cfg.vueRouter?.extensions ?? DEFAULTS.extensionsRoute,
+    routesFolder: cfg.vueRouter?.routesFolder ?? pagesDir,
+    dts: cfg.vueRouter?.dts ?? resolve(cwd, 'types', 'routes.d.ts'),
+  }
+
+  // === 组件 ===
+  const components: ComponentsOptions = {
+    dirs: cfg.components?.dirs ?? [resolve(cwd, DEFAULTS.componentsDir)],
+    extensions: cfg.components?.extensions ?? DEFAULTS.extensionsComponent,
+    dts: cfg.components?.dts ?? resolve(cwd, 'types', 'components.d.ts'),
+    resolvers: cfg.components?.resolvers ?? undefined,
+  }
+
+  // === UnoCSS ===
+  const unoCSS: UnoCSSVitePluginConfig | false =
+    cfg.unoCSS === false
+      ? false
+      : { configFile: false, ...cfg.unoCSS }
+
+  // === Legacy ===
+  const legacyResolved: LegacyOptions | false =
+    cfg.legacy === false
+      ? false
+      : {
+          targets: DEFAULTS.legacyTargets,
+          ...cfg.legacy,
+        }
+
+  // === SSG ===
+  const ssg: SSGConfig | false =
+    cfg.ssg === false
+      ? false
+      : (mergeConfig(
+          {
+            beastiesOptions: { external: false },
+            dirStyle: 'flat',
+            formatting: 'none',
+            includedRoutes(paths: string[]) {
+              return paths.filter((p) => !p.includes('node_modules'))
+            },
+            onPageRendered(_route: string, renderedHTML: string) {
+              return renderedHTML
+            },
+            async onFinished() {
+              await remove(resolve(outDir, '.vite'))
+            },
+          } as UserConfig,
+          cfg.ssg as UserConfig,
+        ) as unknown as SSGConfig)
+
+  // === Linter ===
+  const linter: LinterOptions | false =
+    cfg.linter === false
+      ? false
+      : { oxlint: true, eslint: true, ...cfg.linter }
+
+  // === Bootstrap ===
+  const bootstrap: BootstrapOptions = {
+    entryFile: DEFAULTS.entryFile,
+    ...cfg.bootstrap,
+  }
+
+  // === External ===
+  const external: ExternalOptions = {
+    ...cfg.external,
+  }
+
+  // === Dev ===
+  const dev: DevOptions = {
+    bundledDev: DEFAULTS.bundledDev,
+    ...cfg.dev,
+  }
+
+  // === Janus ===
+  const janus: JanusOptions | false =
+    cfg.janus === false ? false : { ...cfg.janus }
+
+  return {
+    template,
+    entry,
+    outDir,
+    pagesDir,
+    uiLibrary: cfg.uiLibrary || DEFAULTS.uiLibrary,
+    layout,
+    layoutsDirs,
+    proxy: cfg.proxy,
+    lib: cfg.lib,
+    vue: cfg.vue ?? {},
+    vueJsx: cfg.vueJsx ?? {},
+    vueRouter,
+    layouts: cfg.layouts ?? {},
+    components,
+    unoCSS,
+    legacy: legacyResolved,
+    ssg,
+    linter,
+    bootstrap,
+    external,
+    dev,
+    janus,
+  }
+}
+
+// ===================================================================
+// 工具
+// ===================================================================
+
+function normalizeProxy(proxy: ProxyConfig[] | Record<string, string | ProxyOptions>): Record<string, string | ProxyOptions> {
+  if (Array.isArray(proxy)) {
+    const result: Record<string, string | ProxyOptions> = {}
+    for (const rule of proxy) {
+      const { context, ...options } = rule
+      for (const path of context) {
+        result[path.replace(/\/\*+$/, '')] = options as string | ProxyOptions
+      }
+    }
+    return result
+  }
+  return proxy
+}
+
+function loadJanus(opts: JanusOptions | false): PluginOption | null {
+  if (opts === false) return null
+  try {
+    const janusEntry = resolve(cwd, 'node_modules/@janus/unplugin/dist/unplugin.cjs')
+    if (!existsSync(janusEntry)) return null
+    const _require = createRequire(import.meta.url)
+    const mod = _require(janusEntry)
+    const janusOpts = Object.keys(opts).length > 0 ? opts : {}
+    const plugin = mod?.vite?.(janusOpts) || mod?.default?.vite?.(janusOpts)
+    if (plugin) console.log('[miko] Janus 接口拦截器已启用')
+    return plugin
+  } catch (e: unknown) {
+    console.warn('[miko] Janus 加载失败:', (e as Error)?.message)
+    return null
+  }
+}
+
+// ===================================================================
+// 库模式配置工厂
+// ===================================================================
+
+export function createLibConfig(libOptions: {
+  entry: string
+  formats?: ('es' | 'cjs' | 'umd')[]
+  name?: string
+  fileName?: string
+}) {
+  const { entry, formats = ['es', 'cjs'], name, fileName } = libOptions
+
+  return defineConfig({
+    build: {
+      outDir: resolve(cwd, './dist'),
+      emptyOutDir: true,
+      lib: { entry, formats, name, fileName },
+      rollupOptions: { external: ['vue', 'vue-router', 'pinia', 'axios', '@unhead/vue'] },
+    },
+    resolve: { alias: [{ find: '@', replacement: cwd }], tsconfigPaths: true },
+    plugins: [
+      VueMacros({ plugins: { vue: vue(), vueJsx: vueJsx() } }),
+      UnoCSS({ configFile: false }),
+    ],
+  })
+}
+
+// ===================================================================
+// 主入口
+// ===================================================================
+
+/**
+ * 统一配置入口 —— 直接展开所有插件和配置，不嵌套。
+ *
+ * 返回 sync defineConfig 工厂，兼容 viteSsgBuild。
+ *
+ * 配置读取优先级：`miko.config.ts`（项目根目录） > 默认值。
+ * 所有字段均可选，零配置即可运行。
+ *
+ * @example
+ *   // vite.config.ts
+ *   import { defineMikoConfig } from '@minar-kotonoha/vite-plugin-miko'
+ *   export default await defineMikoConfig()
+ */
+export async function defineMikoConfig() {
+  const raw = await loadMikoConfig()
+  const cfg = resolveConfig(raw)
+
+  // 解构已解析的配置
+  const {
+    template,
+    entry,
+    outDir,
+    pagesDir,
+    uiLibrary,
+    layout,
+    layoutsDirs,
+    proxy,
+    vue: vueOpts,
+    vueJsx: vueJsxOpts,
+    vueRouter: vueRouterOpts,
+    layouts: layoutsOpts,
+    components: componentsOpts,
+    unoCSS: unoCSSOpts,
+    legacy: legacyOpts,
+    ssg: ssgOpts,
+    linter: linterOpts,
+    bootstrap: bootstrapOpts,
+    external: externalOpts,
+    dev: devOpts,
+    janus: janusOpts,
+  } = cfg
+
+  // 设置环境变量（external 插件和 template/App.vue 通过 env 读取）
+  if (externalOpts.frameworkCDN) {
+    process.env.VITE_FRAMEWORK_CDN = externalOpts.frameworkCDN
+  }
+
+  // 设置环境变量（自定义 bootstrap 入口文件）
+  if (bootstrapOpts.entryFile !== DEFAULTS.entryFile) {
+    process.env.MIKO_BOOTSTRAP_ENTRY = bootstrapOpts.entryFile
+  }
+
+  console.log(`[miko] UI 组件库: ${uiLibrary}`)
+  console.log(`[miko] 布局: ${layout}`)
+  console.log(`[miko] 模板目录: ${template}`)
+  console.log(`[miko] 入口文件: ${entry}`)
+
+  // ===== 构建 PluginOption 数组 =====
+
+  const plugins: PluginOption[] = []
+
+  // 1. Vue 生态
+  plugins.push(
+    VueMacros({
+      plugins: {
+        vue: vue(vueOpts),
+        vueJsx: vueJsx(vueJsxOpts),
+        vueRouter: VueRouter({
+          extensions: vueRouterOpts.extensions,
+          routesFolder: vueRouterOpts.routesFolder,
+          dts: vueRouterOpts.dts,
+          extendRoute(route: { path?: string; addAlias: (a: string[]) => void }) {
+            if (route.path) route.addAlias([route.path === '/' ? 'index.html' : `${route.path}.html`])
+          },
+        }),
+      },
+    }),
+  )
+
+  // 2. 布局
+  plugins.push(
+    Layouts({
+      defaultLayout: layout,
+      layoutsDirs,
+      pagesDirs: layoutsOpts.pagesDirs ?? pagesDir,
+    }),
+  )
+
+  // 3. 代码检查
+  if (linterOpts !== false) {
+    // linterPlugin 内部已处理 oxlint/eslint 开关，直接传入
+    plugins.push(linterPlugin)
+  }
+
+  // 4. Legacy 浏览器兼容
+  if (legacyOpts !== false) {
+    plugins.push(legacy({ targets: DEFAULTS.legacyTargets, ...legacyOpts }))
+  }
+
+  // 5. 组件自动导入
+  const componentResolvers = cfg.components.resolvers
+    ? cfg.components.resolvers
+    : uiLibrary === 'vant'
+      ? [VantResolver()]
+      : [ElementPlusResolver()]
+
+  plugins.push(
+    Components({
+      dirs: Array.isArray(componentsOpts.dirs) ? componentsOpts.dirs : [componentsOpts.dirs],
+      extensions: componentsOpts.extensions,
+      dts: componentsOpts.dts,
+      resolvers: componentResolvers,
+    }),
+  )
+
+  // 6. UnoCSS
+  if (unoCSSOpts !== false) {
+    plugins.push(UnoCSS({ configFile: false, ...unoCSSOpts } as Parameters<typeof UnoCSS>[0]))
+  }
+
+  // 7. Bootstrap（virtual:bootstrap）
+  plugins.push(bootstrapPlugin(bootstrapOpts.entryFile))
+
+  // 8. External（CDN 外部化）
+  plugins.push(...externalPlugin())
+
+  // 9. IndexHTML
+  plugins.push(await indexHTMLPlugin(entry, template))
+
+  // 10. Janus（可选）
+  const janusPlugin = loadJanus(janusOpts)
+  if (janusPlugin) plugins.push(janusPlugin)
+
+  // ===== 组装 defineConfig =====
+
+  return defineConfig(() => ({
+    server: {
+      host: devOpts.host ?? true,
+      port: devOpts.port,
+      proxy: proxy ? normalizeProxy(proxy) : undefined,
+    },
+    build: { outDir, emptyOutDir: true },
+    cacheDir: resolve(cwd, './node_modules/.vite'),
+    resolve: { alias: [{ find: '@', replacement: cwd }], tsconfigPaths: true },
+    experimental: { bundledDev: devOpts.bundledDev ?? DEFAULTS.bundledDev },
+    ssgOptions: ssgOpts === false
+      ? undefined
+      : {
+          beastiesOptions: ssgOpts.beastiesOptions ?? { external: false },
+          dirStyle: ssgOpts.dirStyle ?? 'flat',
+          entry,
+          formatting: ssgOpts.formatting ?? 'none',
+          includedRoutes: ssgOpts.includedRoutes ?? ((paths: string[]) => paths.filter((p) => !p.includes('node_modules'))),
+          onPageRendered: ssgOpts.onPageRendered ?? ((_route: string, renderedHTML: string) => renderedHTML),
+          onFinished: ssgOpts.onFinished ?? (async () => { await remove(resolve(outDir, '.vite')) }),
+        },
+    plugins,
+  }))
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@minar-kotonoha/vite-plugin-miko",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "vite": "catalog:"
+  },
+  "dependencies": {
+    "@minar-kotonoha/linter": "workspace:^",
+    "@minar-kotonoha/vite-plugin-bootstrap": "workspace:^",
+    "@minar-kotonoha/vite-plugin-external": "workspace:^",
+    "@minar-kotonoha/vite-plugin-index-html": "workspace:^",
+    "@vant/auto-import-resolver": "^1.0.0",
+    "@vitejs/plugin-legacy": "^8.2.0",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vitejs/plugin-vue-jsx": "^5.1.6",
+    "fs-extra": "^11.3.6",
+    "unocss": "^66.7.0",
+    "unplugin-vue-components": "^32.1.0",
+    "vite-plugin-vue-layouts-next": "^2.1.0",
+    "vue-macros": "^3.1.4",
+    "vue-router": "^5.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "lib": ["esnext", "dom"],
+    "strict": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["index.ts", "types.ts"]
+}

package/types.ts

@@ -0,0 +1,437 @@
+/**
+ * # @minar-kotonoha/vite-plugin-miko 类型定义
+ *
+ * `MikoUserConfig` 为 `miko.config.ts` 的完整配置类型。
+ * 所有字段均为可选，默认值在 JSDoc 中标注。
+ *
+ * 插件子类型直接引用底层插件的 Options 类型，保证类型始终准确。
+ */
+
+// ===== 直接引用底层插件类型（保证与插件版本同步） =====
+
+import type { Options as VueOptions } from '@vitejs/plugin-vue'
+import type { Options as VueJsxOptions } from '@vitejs/plugin-vue-jsx'
+import type { Options as LegacyOptions } from '@vitejs/plugin-legacy'
+import type { UserOptions as LayoutsUserOptions } from 'vite-plugin-vue-layouts-next'
+import type { VitePluginConfig as UnoCSSVitePluginConfig } from '@unocss/vite'
+
+// ===================================================================
+// 重新导出底层插件类型（方便用户直接在 miko.config.ts 中使用）
+// ===================================================================
+
+export type { VueOptions, VueJsxOptions, LegacyOptions, LayoutsUserOptions, UnoCSSVitePluginConfig }
+
+// ===== 基础配置 =====
+
+/** 开发服务器代理规则 */
+export interface ProxyConfig {
+  /** 要代理的路径模式，如 `['/api/**']` */
+  context: string[]
+  /** 代理目标地址 */
+  target: string
+  /** 是否修改请求头 origin */
+  changeOrigin?: boolean
+  /** 代理日志级别 */
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  /** 自定义代理事件 */
+  configure?: (proxy: unknown) => void
+}
+
+// ===== 库模式 =====
+
+export interface LibConfig {
+  /** 库入口文件 */
+  entry?: string
+  /** 输出格式 */
+  formats?: ('es' | 'cjs' | 'umd')[]
+  /** 全局变量名（UMD 模式） */
+  name?: string
+  /** 输出文件名 */
+  fileName?: string
+}
+
+// ===== Vue Router =====
+
+export interface VueRouterOptions {
+  /**
+   * 路由文件扩展名
+   * @default ['.vue', '.setup.tsx']
+   */
+  extensions?: string[]
+  /**
+   * 页面文件目录（文件系统路由扫描根目录）
+   * @default '<cwd>/pages'
+   */
+  routesFolder?: string
+  /**
+   * 路由类型声明输出路径
+   * @default '<cwd>/types/routes.d.ts'
+   */
+  dts?: string
+}
+
+// ===== 组件自动导入 =====
+
+export interface ComponentsOptions {
+  /**
+   * 组件文件目录
+   * @default ['<cwd>/components']
+   */
+  dirs?: string | string[]
+  /**
+   * 组件文件扩展名
+   * @default ['vue', 'tsx', 'ts']
+   */
+  extensions?: string[]
+  /**
+   * 类型声明输出路径，false 表示不生成
+   * @default '<cwd>/types/components.d.ts'
+   */
+  dts?: string | boolean
+  /** 额外自定义 resolvers（会替换 uiLibrary 的默认 resolver） */
+  resolvers?: unknown[]
+}
+
+// ===== SSG =====
+
+/**
+ * vite-ssg 配置。
+ * 设为 `false` 禁用 SSG（降级为纯 SPA）。
+ */
+export interface SSGConfig {
+  /** beasties 配置（控制资源内联与压缩） */
+  beastiesOptions?: {
+    /** 是否外部化资源，默认 false（所有 CSS/JS 内联到 HTML） */
+    external?: boolean
+    /** 压缩配置 */
+    compress?: boolean | Record<string, unknown>
+    [key: string]: unknown
+  }
+  /**
+   * 输出目录结构
+   * - `'flat'`：/about.html
+   * - `'nested'`：/about/index.html
+   * @default 'flat'
+   */
+  dirStyle?: 'flat' | 'nested'
+  /**
+   * HTML 格式化
+   * @default 'none'
+   */
+  formatting?: 'none' | 'prettier'
+  /** 需要被包含的路由过滤函数 */
+  includedRoutes?: (paths: string[]) => string[]
+  /** 页面渲染完成钩子（可在此注入脚本、修改 HTML） */
+  onPageRendered?: (route: string, renderedHTML: string) => string
+  /** SSG 构建完成钩子（可在此做清理工作） */
+  onFinished?: () => Promise<void>
+}
+
+// ===== 代码检查 =====
+
+export interface LinterOptions {
+  /**
+   * 是否启用 oxlint
+   * @default true
+   */
+  oxlint?: boolean
+  /**
+   * 是否启用 ESLint
+   * @default true
+   */
+  eslint?: boolean
+}
+
+// ===== Bootstrap 启动器 =====
+
+export interface BootstrapOptions {
+  /**
+   * 项目入口文件路径（相对于 cwd）
+   * @default 'index.ts'
+   */
+  entryFile?: string
+}
+
+// ===== 外部化 / CDN =====
+
+export interface ExternalOptions {
+  /**
+   * Framework CDN 地址，覆盖 .env 中的 VITE_FRAMEWORK_CDN
+   * @default 'https://unpkg.com/@minar-kotonoha/framework@<version>/dist/framework_v<version>.umd.js'
+   */
+  frameworkCDN?: string
+  /** 额外需要外部化的包名 */
+  additionalExternals?: string[]
+}
+
+// ===== 开发 / 构建调优 =====
+
+export interface DevOptions {
+  /**
+   * 是否启用 bundledDev（Rolldown 原生 dev 模式）
+   * @default true
+   */
+  bundledDev?: boolean
+  /**
+   * 开发服务器主机名（Vite server.host）
+   * @default 'localhost'
+   */
+  host?: string | boolean
+  /**
+   * 开发服务器端口（Vite server.port）
+   * @default 5173
+   */
+  port?: number
+  /**
+   * 是否自动打开浏览器
+   * @default false
+   */
+  open?: boolean | string
+}
+
+// ===== Janus 接口拦截器 =====
+
+export interface JanusOptions {
+  /** Janus schema 目录 */
+  schemasDir?: string
+}
+
+// ===================================================================
+// 主配置类型
+// ===================================================================
+
+/**
+ * miko 项目配置文件（`miko.config.ts`）的类型定义。
+ *
+ * **所有字段均为可选**，默认值已在每个字段的 JSDoc 中标注。
+ *
+ * ## 插件配置分类
+ *
+ * | 分类 | 字段 | 类型来源 |
+ * |------|------|----------|
+ * | Vue SFC 编译 | `vue` | `@vitejs/plugin-vue` Options |
+ * | JSX / TSX | `vueJsx` | `@vitejs/plugin-vue-jsx` Options |
+ * | 文件系统路由 | `vueRouter` | 自定义（vue-router/vite 参数） |
+ * | 布局系统 | `layouts` | `vite-plugin-vue-layouts-next` UserOptions |
+ * | 组件自动导入 | `components` | 自定义（unplugin-vue-components 参数） |
+ * | 原子 CSS | `unoCSS` | `@unocss/vite` VitePluginConfig（`false` 禁用） |
+ * | 浏览器兼容 | `legacy` | `@vitejs/plugin-legacy` Options（`false` 禁用） |
+ * | 静态生成 | `ssg` | 自定义（vite-ssg 参数）（`false` 禁用） |
+ * | 代码检查 | `linter` | 自定义（`false` 禁用） |
+ * | 入口启动 | `bootstrap` | 自定义 |
+ * | CDN 外部化 | `external` | 自定义 |
+ * | 接口拦截 | `janus` | 自定义（`false` 禁用） |
+ * | 开发调优 | `dev` | 自定义 |
+ *
+ * @example 最小配置
+ * ```ts
+ * // miko.config.ts
+ * import type { MikoUserConfig } from '@minar-kotonoha/vite-plugin-miko'
+ * export default { uiLibrary: 'vant' } satisfies MikoUserConfig
+ * ```
+ *
+ * @example 完整配置
+ * ```ts
+ * import type { MikoUserConfig } from '@minar-kotonoha/vite-plugin-miko'
+ * export default {
+ *   // 基础
+ *   uiLibrary: 'element-plus',
+ *   layout: 'default',
+ *   pagesDir: 'src/pages',
+ *
+ *   // 代理
+ *   proxy: [{ context: ['/api/**'], target: 'https://api.example.com', changeOrigin: true }],
+ *
+ *   // 插件透传（直接使用底层插件 Options）
+ *   vue: { features: { optionsAPI: false } },           // @vitejs/plugin-vue Options
+ *   vueJsx: { tsTransform: 'built-in' },                // @vitejs/plugin-vue-jsx Options
+ *   layouts: { extensions: ['vue', 'tsx'] },            // vite-plugin-vue-layouts-next UserOptions
+ *   legacy: { targets: ['chrome 80', 'ios 13'] },       // @vitejs/plugin-legacy Options
+ *   unoCSS: { configFile: 'uno.config.ts' },            // @unocss/vite VitePluginConfig
+ *   ssg: { dirStyle: 'nested' },                        // false 禁用 SSG
+ * } satisfies MikoUserConfig
+ * ```
+ */
+export interface MikoUserConfig {
+  // === 基础路径 ===
+
+  /**
+   * 模板目录路径。
+   * 包含 App.vue、main.ts、index.html、layouts/ 等 Vite 入口模板文件。
+   * @default 自动探测（优先项目根 `template/` → 回退包内 `template/`）
+   */
+  template?: string
+
+  /**
+   * 应用入口文件路径（传给 vite-ssg 的 entry）。
+   * @default `<template>/main.ts`
+   */
+  entry?: string
+
+  /**
+   * 构建输出目录。
+   * @default `'./dist'`
+   */
+  outDir?: string
+
+  /**
+   * 页面目录（文件系统路由的扫描根目录）。
+   * @default `'./pages'`
+   */
+  pagesDir?: string
+
+  // === UI 框架 ===
+
+  /**
+   * UI 组件库，控制自动导入 resolver 的选择。
+   * @default `'vant'`
+   */
+  uiLibrary?: 'vant' | 'element-plus'
+
+  /**
+   * 默认布局名（`layouts.defaultLayout` 的快捷方式，向后兼容）。
+   * 当同时设置了 `layout` 和 `layouts.defaultLayout` 时，后者优先。
+   * @default `'flexible'`
+   */
+  layout?: string
+
+  // === 开发服务器 ===
+
+  /**
+   * 开发服务器代理规则。
+   * 数组格式（webpack-dev-server 风格），支持将多个路径映射到同一目标。
+   *
+   * @example
+   * ```ts
+   * proxy: [
+   *   { context: ['/api/**'], target: 'https://dev.example.com', changeOrigin: true },
+   * ]
+   * ```
+   * @default `[]`（无代理）
+   */
+  proxy?: ProxyConfig[]
+
+  // === 库模式 ===
+
+  /**
+   * 库模式配置（供 `miko build --lib` 使用）。
+   * @default `undefined`（应用模式）
+   */
+  lib?: LibConfig
+
+  // === 开发调优 ===
+
+  /**
+   * 开发与构建行为微调。
+   * @default `{ bundledDev: true }`
+   */
+  dev?: DevOptions
+
+  // ===================================================================
+  // 以下为各插件的独立配置分组
+  // 类型直接引自底层插件 Options，保证与 npm 包版本同步
+  // ===================================================================
+
+  /**
+   * `@vitejs/plugin-vue` 的完整 Options。
+   *
+   * 透传给 `vue()` 函数，支持 include/exclude/script/template/style/features/compiler 等。
+   *
+   * @see https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue
+   * @default `{}`
+   */
+  vue?: VueOptions
+
+  /**
+   * `@vitejs/plugin-vue-jsx` 的完整 Options。
+   *
+   * 透传给 `vueJsx()` 函数，支持 include/exclude/babelPlugins/tsTransform 等。
+   *
+   * @see https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx
+   * @default `{}`
+   */
+  vueJsx?: VueJsxOptions
+
+  /**
+   * vue-router 文件系统路由选项。
+   * @default `{ extensions: ['.vue', '.setup.tsx'], routesFolder: '<pagesDir>', dts: '<cwd>/types/routes.d.ts' }`
+   */
+  vueRouter?: VueRouterOptions
+
+  /**
+   * `vite-plugin-vue-layouts-next` 的完整 UserOptions。
+   *
+   * 透传给 `Layouts()` 函数。
+   * 注意：`layoutsDirs`、`pagesDirs`、`defaultLayout` 均有 miko 默认值，
+   * 未设置时不会使用插件自身的默认值（`src/layouts` / `src/pages` / `default`）。
+   *
+   * @see https://github.com/JohnCampionJr/vite-plugin-vue-layouts-next
+   * @default `{ defaultLayout: 'flexible', layoutsDirs: ['<template>/layouts', '<cwd>/layouts'], pagesDirs: '<pagesDir>' }`
+   */
+  layouts?: LayoutsUserOptions
+
+  /**
+   * unplugin-vue-components 选项。
+   * @default `{ dirs: ['<cwd>/components'], extensions: ['vue', 'tsx', 'ts'], dts: '<cwd>/types/components.d.ts' }`
+   */
+  components?: ComponentsOptions
+
+  /**
+   * `@unocss/vite` 的完整 VitePluginConfig + UserConfig。
+   *
+   * 透传给 `UnoCSS()` 函数。设为 `false` 禁用 UnoCSS。
+   *
+   * 常用：`{ configFile: 'uno.config.ts' }` 加载自定义配置，
+   * 或 `{ configFile: false }`（默认）使用默认预设。
+   *
+   * @see https://unocss.dev/integrations/vite
+   * @default `{ configFile: false }`
+   */
+  unoCSS?: UnoCSSVitePluginConfig | false
+
+  /**
+   * `@vitejs/plugin-legacy` 的完整 Options。
+   *
+   * 透传给 `legacy()` 函数。设为 `false` 禁用（不生成 `-legacy` 产物）。
+   *
+   * @see https://github.com/vitejs/vite/tree/main/packages/plugin-legacy
+   * @default `{ targets: ['chrome 49', 'ios 10'] }`
+   */
+  legacy?: LegacyOptions | false
+
+  /**
+   * vite-ssg 选项。
+   * 设为 `false` 禁用 SSG（降级为纯 SPA）。
+   *
+   * @default `{ beastiesOptions: { external: false }, dirStyle: 'flat', formatting: 'none' }`
+   */
+  ssg?: SSGConfig | false
+
+  /**
+   * 构建时代码检查选项。
+   * 设为 `false` 禁用所有 linter（oxlint + ESLint 均跳过）。
+   *
+   * @default `{ oxlint: true, eslint: true }`
+   */
+  linter?: LinterOptions | false
+
+  /**
+   * virtual:bootstrap 入口启动器选项。
+   * @default `{ entryFile: 'index.ts' }`
+   */
+  bootstrap?: BootstrapOptions
+
+  /**
+   * CDN 外部化选项。
+   * @default `{}`
+   */
+  external?: ExternalOptions
+
+  /**
+   * Janus 接口拦截器选项。
+   * 设为 `false` 禁用（即使安装了 `@janus/unplugin` 也不加载）。
+   *
+   * @default 自动发现（安装了 `@janus/unplugin` 则自动启用）
+   */
+  janus?: JanusOptions | false
+}