@fchc8/vite-plugin-multi-page 1.1.0 → 1.3.0

package/README.md

@@ -1,518 +1,270 @@
 # vite-plugin-multi-page
 
-> [English Documentation](./README-EN.md) | 中文文档
+> English Documentation | [English Documentation](./README-EN.md)
 
-一个强大的 Vite 插件，用于构建多页面应用程序，支持智能文件路由和多种构建策略。
+一个强大的 Vite 插件，支持多页面应用开发，提供多策略构建、TypeScript 配置支持和命令行工具。
 
-## ✨ 特性
+## 特性
 
-- 🚀 **自动页面发现**：基于文件模式自动扫描和配置入口页面
-- 🎯 **多构建策略**：为不同页面配置不同的构建选项和优化策略
-- 🧩 **灵活配置**：支持对象配置、函数配置和模式匹配
-- 📱 **响应式模板**：不同页面可使用不同的 HTML 模板
-- 🔧 **完整 Vite 集成**：继承所有 Vite 配置选项
-- 🌍 **环境变量支持**：页面级和策略级环境变量定义
-- 🎨 **开发友好**：详细的调试日志和热重载支持
-- ⚡ **开发构建一致性**：确保开发模式与构建模式使用相同的配置逻辑
-- 🔄 **配置同步**：环境变量、模板选择、构建策略在开发和生产环境保持一致
+- 🎯 **多页面支持**: 自动发现页面入口文件
+- 🔧 **多策略构建**: 支持为不同页面配置不同的构建策略
+- 📝 **TypeScript 配置**: 支持 TypeScript 配置文件
+- 🚀 **CLI 工具**: 提供命令行批量构建工具
+- 🔄 **热重载**: 开发服务器支持页面热重载
+- 📦 **智能合并**: 自动合并多策略构建结果
 
-## 📦 安装
+## 安装
 
 ```bash
-npm install @fchc8/vite-plugin-multi-page
-# 或
-yarn add @fchc8/vite-plugin-multi-page
-# 或
-pnpm add @fchc8/vite-plugin-multi-page
+npm install vite-plugin-multi-page --save-dev
 ```
 
-## 🚀 快速开始
+## 快速开始
 
-### 基础用法
+### 1. 创建配置文件
 
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-import viteMultiPage from '@fchc8/vite-plugin-multi-page';
+创建 `multipage.config.ts` 或 `multipage.config.js`:
 
-export default defineConfig({
-  plugins: [
-    viteMultiPage({
-      entry: 'src/pages/**/*.{ts,js}',
-      template: 'index.html',
-      exclude: ['src/main.ts'],
-      debug: true,
-    }),
-  ],
-});
-```
+```typescript
+export default context => {
+  const { mode, command, isCLI } = context;
+  const isProduction = mode === 'production';
 
-### 项目结构示例
+  return {
+    // 页面入口匹配规则
+    entry: 'src/pages/**/*.{ts,js}',
 
-```
-project/
-├── src/
-│   └── pages/
-│       ├── home.ts          → /home.html
-│       ├── about.ts         → /about.html
-│       ├── admin/
-│       │   └── dashboard.ts → /dashboard.html
-│       └── mobile/
-│           └── app.js       → /app.html
-├── index.html
-├── admin.html
-└── mobile.html
-```
+    // HTML 模板
+    template: 'index.html',
 
-## 🎯 高级配置
+    // 模板占位符
+    placeholder: '{{ENTRY_FILE}}',
 
-### 多构建策略
+    // 排除的文件
+    exclude: ['src/shared/**/*.ts'],
 
-```typescript
-import { defineConfig } from 'vite';
-import viteMultiPage from '@fchc8/vite-plugin-multi-page';
+    // 调试模式
+    debug: !isProduction || isCLI,
 
-export default defineConfig({
-  plugins: [
-    viteMultiPage({
-      entry: 'src/pages/**/*.{ts,js}',
-
-      // 定义构建策略
-      buildStrategies: {
-        // 现代浏览器策略
-        default: {
-          viteConfig: {
-            define: {
-              'process.env.BUILD_TYPE': '"modern"',
-            },
-          },
-          output: {
-            format: 'es',
-            entryFileNames: 'assets/[name]-[hash].js',
-          },
-          build: {
-            target: 'es2015',
-            minify: 'esbuild',
-            sourcemap: true,
-          },
+    // 构建策略
+    strategies: {
+      default: {
+        define: {
+          IS_DEFAULT: true,
+          API_BASE: isProduction ? '"https://api.example.com"' : '"http://localhost:3001/api"',
         },
-
-        // 兼容模式策略
-        legacy: {
-          viteConfig: {
-            define: {
-              'process.env.BUILD_TYPE': '"legacy"',
-            },
-          },
-          output: {
-            format: 'iife',
-            entryFileNames: 'legacy/[name].js',
-          },
-          build: {
-            target: 'es5',
-            minify: 'terser',
-            sourcemap: false,
-          },
+        build: {
+          sourcemap: !isProduction,
+          minify: isProduction ? 'esbuild' : false,
         },
+      },
 
-        // 移动端优化策略
-        mobile: {
-          viteConfig: {
-            css: {
-              devSourcemap: true,
-            },
-            optimizeDeps: {
-              include: ['mobile-utils'],
-            },
-          },
-          build: {
-            target: 'es2018',
-            chunkSizeWarningLimit: 300,
-          },
+      mobile: {
+        define: {
+          IS_MOBILE: true,
+          API_BASE: isProduction
+            ? '"https://mobile-api.example.com"'
+            : '"http://localhost:3001/mobile-api"',
+        },
+        build: {
+          target: ['es2015', 'chrome58', 'safari11'],
+          minify: isProduction ? 'terser' : false,
         },
       },
-    }),
-  ],
-});
-```
-
-### 函数配置
-
-```typescript
-viteMultiPage({
-  entry: 'src/pages/**/*.{ts,js}',
+    },
 
-  // 使用函数进行动态配置
-  pageConfigs: context => {
-    const { pageName, filePath, relativePath } = context;
+    // 页面配置函数
+    pageConfigs: context => {
+      // 根据文件路径判断应用的策略
+      if (context.relativePath.includes('/mobile/')) {
+        return {
+          strategy: 'mobile',
+          define: {
+            PAGE_NAME: context.pageName,
+            MOBILE_PAGE: true,
+          },
+        };
+      }
 
-    // 管理后台页面
-    if (pageName.startsWith('admin')) {
+      // 默认策略
       return {
         strategy: 'default',
-        template: 'admin.html',
         define: {
-          'process.env.API_BASE': '"https://admin-api.example.com"',
+          PAGE_NAME: context.pageName,
+          DEFAULT_PAGE: true,
         },
       };
-    }
-
-    // 移动端页面
-    if (relativePath.includes('/mobile/')) {
-      return {
-        strategy: 'mobile',
-        template: 'mobile.html',
-        define: {
-          'process.env.API_BASE': '"https://mobile-api.example.com"',
-        },
-      };
-    }
-
-    // 默认配置
-    return {
-      strategy: 'default',
-    };
-  },
-});
-```
-
-### 对象配置与模式匹配
-
-```typescript
-viteMultiPage({
-  entry: 'src/pages/**/*.{ts,js}',
-
-  pageConfigs: {
-    // 精确匹配
-    home: {
-      strategy: 'default',
-      template: 'home.html',
     },
-
-    // 通配符匹配
-    'admin*': {
-      strategy: 'default',
-      template: 'admin.html',
-    },
-
-    // 模式匹配
-    'mobile-app': {
-      strategy: 'mobile',
-      match: ['**/mobile/**', '*mobile*'],
-      template: 'mobile.html',
-    },
-  },
-});
+  };
+};
 ```
 
-## 📋 配置选项
-
-### MultiPageOptions
+### 2. 配置 Vite
 
-| 选项              | 类型                                               | 默认值                                 | 描述             |
-| ----------------- | -------------------------------------------------- | -------------------------------------- | ---------------- |
-| `entry`           | `string`                                           | `"src/**/*.{ts,js}"`                   | 入口文件匹配模式 |
-| `template`        | `string`                                           | `"index.html"`                         | 默认 HTML 模板   |
-| `exclude`         | `string[]`                                         | `["src/main.ts", "src/vite-env.d.ts"]` | 排除的文件       |
-| `placeholder`     | `string`                                           | `"{{ENTRY_FILE}}"`                     | 模板中的占位符   |
-| `debug`           | `boolean`                                          | `false`                                | 启用调试日志     |
-| `buildStrategies` | `Record<string, BuildStrategy>`                    | `{}`                                   | 构建策略定义     |
-| `pageConfigs`     | `Record<string, PageConfig> \| PageConfigFunction` | `{}`                                   | 页面配置         |
-
-### BuildStrategy
+在 `vite.config.ts` 中添加插件:
 
 ```typescript
-interface BuildStrategy {
-  // 完整的 Vite 配置支持
-  viteConfig?: Omit<UserConfig, 'plugins' | 'build'> & {
-    build?: BuildOptions;
-  };
-
-  // 输出配置
-  output?: {
-    format?: 'es' | 'cjs' | 'umd' | 'iife';
-    dir?: string;
-    entryFileNames?: string;
-    chunkFileNames?: string;
-    assetFileNames?: string;
-    globals?: Record<string, string>;
-    external?: string | string[] | ((id: string) => boolean);
-  };
-
-  // 构建配置
-  build?: {
-    target?: string | string[];
-    minify?: boolean | 'terser' | 'esbuild';
-    sourcemap?: boolean | 'inline' | 'hidden';
-    lib?: boolean | LibraryOptions;
-    cssCodeSplit?: boolean;
-    cssTarget?: string | string[];
-    rollupOptions?: any;
-    // ... 更多 Vite 构建选项
-  };
-
-  // 环境变量
-  define?: Record<string, any>;
+import { defineConfig } from 'vite';
+import viteMultiPage from 'vite-plugin-multi-page';
 
-  // 别名配置
-  alias?: Record<string, string>;
+export default defineConfig({
+  plugins: [viteMultiPage()],
+});
+```
 
-  // 服务器配置
-  server?: ServerOptions;
+### 3. 创建页面文件
 
-  // CSS 配置
-  css?: CSSOptions;
+按照约定创建页面文件:
 
-  // 依赖优化
-  optimizeDeps?: DepOptimizationOptions;
-}
+```
+src/pages/
+├── home.js                    # → /home.html
+├── about.js                   # → /about.html
+├── mobile/
+│   └── main.ts               # → /mobile.html (移动端策略)
+└── admin/
+    └── main.ts               # → /admin.html
 ```
 
-### PageConfig
+## 页面发现规则
 
-```typescript
-interface PageConfig {
-  strategy?: string; // 使用的构建策略
-  template?: string; // 页面模板
-  exclude?: string[]; // 排除规则
-  define?: Record<string, any>; // 环境变量
-  alias?: Record<string, string>; // 别名
-  build?: Partial<BuildStrategy['build']>; // 构建配置
-  match?: string | string[]; // 匹配模式
-}
-```
+插件按照以下规则发现页面入口:
 
-## 🌟 使用场景
+1. **第一级文件** (优先级 1): `src/pages/home.js` → `/home.html`
+2. **目录main文件** (优先级 2): `src/pages/mobile/main.ts` → `/mobile.html`
 
-### 1. 企业级多页应用
+**目录优先原则**: 如果同时存在 `src/pages/about.js` 和 `src/pages/about/main.ts`，将使用 `src/pages/about/main.ts`。
 
-```typescript
-buildStrategies: {
-  admin: {
-    viteConfig: {
-      define: { 'process.env.APP_TYPE': '"admin"' }
-    },
-    build: {
-      target: 'es2015',
-      sourcemap: true
-    }
-  },
+## 构建策略
 
-  public: {
-    viteConfig: {
-      define: { 'process.env.APP_TYPE': '"public"' }
-    },
-    build: {
-      target: 'es5',
-      minify: 'terser'
-    }
-  }
-}
-```
+### 策略配置
 
-### 2. 移动端优化
+策略配置支持所有 Vite 配置选项:
 
 ```typescript
-buildStrategies: {
+strategies: {
   mobile: {
-    viteConfig: {
-      css: { devSourcemap: true },
-      optimizeDeps: { include: ['@mobile/utils'] }
+    define: {
+      IS_MOBILE: true,
     },
     build: {
-      target: 'es2018',
-      chunkSizeWarningLimit: 300,
-      cssCodeSplit: true
-    }
-  }
-}
-```
-
-### 3. 组件库开发
-
-```typescript
-buildStrategies: {
-  library: {
-    build: {
-      lib: {
-        entry: 'src/index.ts',
-        name: 'MyLibrary',
-        formats: ['es', 'umd']
+      target: ['es2015'],
+      minify: 'terser',
+      terserOptions: {
+        compress: {
+          drop_console: true,
+        },
       },
-      minify: false,
-      sourcemap: true
-    }
-  }
+    },
+    // 其他 Vite 配置...
+  },
 }
 ```
 
-## 📱 示例项目
-
-查看 `example/` 目录获取完整的示例项目，包含：
+### 页面策略分配
 
-- 管理后台页面（现代语法）
-- 移动端应用（兼容语法）
-- 组件库文档
-- 不同的 HTML 模板
-- 函数配置示例
+通过 `pageConfigs` 函数为页面分配策略:
 
-### 快速开始
+```typescript
+pageConfigs: context => {
+  const { pageName, relativePath } = context;
 
-```bash
-# 方法一：使用根目录脚本
-npm run example:dev # 开发模式
-npm run example:build # 构建
-npm run example:preview # 预览构建结果
-
-# 方法二：手动设置
-npm run build # 先构建插件
-cd example
-npm install # 安装示例依赖
-npm run dev # 运行开发服务器
-```
+  if (relativePath.includes('/mobile/')) {
+    return { strategy: 'mobile' };
+  }
 
-### 示例页面
+  if (pageName.startsWith('admin')) {
+    return { strategy: 'admin' };
+  }
 
-构建后访问以下页面：
+  return { strategy: 'default' };
+};
+```
 
-- `/home.html` - 首页（默认策略）
-- `/about.html` - 关于页面（默认策略）
-- `/mobile.html` - 移动端页面（移动端模板）
+## 命令行工具
 
-## 🔧 开发
+### 批量构建
 
 ```bash
-# 克隆项目
-git clone https://github.com/fchc7/vite-plugin-multi-page.git
-cd vite-plugin-multi-page
-
-# 项目初始化
-./scripts/setup.sh
-
-# 开发模式
-pnpm dev
-
-# 类型检查
-pnpm type-check
-
-# 代码格式化
-pnpm format
+# 构建所有策略
+npx vite-mp
 
-# 代码检查
-pnpm lint
+# 传递额外的 Vite 参数
+npx vite-mp --host --port 3000
 
-# 构建
-pnpm build
+# 启用调试模式
+npx vite-mp --debug
 ```
 
-## 🤝 贡献
+### 开发服务器
 
-欢迎提交 Issue 和 Pull Request！
-
-## 📄 许可证
-
-MIT License
-
-## 🔗 相关链接
+```bash
+# 启动开发服务器 (所有页面)
+npm run dev
 
-- [Vite 官方文档](https://vitejs.dev/)
-- [TypeScript](https://www.typescriptlang.org/)
-- [ESLint](https://eslint.org/)
-- [Prettier](https://prettier.io/)
-- [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/)
-- [语义化版本](https://semver.org/lang/zh-CN/)
+# 只显示特定策略的页面
+npm run dev -- --strategy mobile
+```
 
-## ⚡ 开发与构建一致性
+## 环境变量
 
-### 配置同步机制
+- `VITE_BUILD_STRATEGY`: 指定单个策略构建
+- `IS_MOBILE`: 移动端标识 (在 define 中配置)
+- `API_BASE`: API 基础地址 (在 define 中配置)
 
-本插件确保开发模式与构建模式使用**完全相同的配置逻辑**，避免开发环境和生产环境的差异问题。
+## TypeScript 支持
 
-#### 1. 页面配置一致性
+插件完全支持 TypeScript 配置文件:
 
 ```typescript
-// 开发和构建都使用相同的页面配置逻辑
-pageConfigs: context => {
-  const { pageName, relativePath } = context;
+// multipage.config.ts
+import type { ConfigFunction } from 'vite-plugin-multi-page';
 
-  // 移动端页面 - 开发和构建都使用 mobile.html 模板
-  if (relativePath.includes('/mobile/')) {
-    return {
-      template: 'mobile.html',
-      define: {
-        'process.env.API_BASE': '"https://mobile-api.com"',
-      },
-    };
-  }
-
-  return { template: 'index.html' };
+const config: ConfigFunction = context => {
+  return {
+    entry: 'src/pages/**/*.{ts,js}',
+    // ... 其他配置
+  };
 };
-```
-
-#### 2. 环境变量同步
-
-**构建时**：注入到 Vite 配置
 
-```typescript
-// 环境变量会被 Vite 编译时替换
-config.define = { 'process.env.API_BASE': '"https://api.com"' };
+export default config;
 ```
 
-**开发时**：动态注入到 HTML
+## API 参考
 
-```html
-<!-- 开发服务器自动注入到页面 -->
-<script>
-  // 页面级环境变量
-  window['process.env.API_BASE'] = 'https://api.com';
-</script>
-```
+### 配置选项
 
-#### 3. 模板选择一致性
+| 选项          | 类型                       | 默认值                     | 描述             |
+| ------------- | -------------------------- | -------------------------- | ---------------- |
+| `entry`       | `string`                   | `'src/pages/**/*.{ts,js}'` | 页面入口匹配规则 |
+| `template`    | `string`                   | `'index.html'`             | HTML 模板文件    |
+| `placeholder` | `string`                   | `'{{ENTRY_FILE}}'`         | 模板占位符       |
+| `exclude`     | `string[]`                 | `[]`                       | 排除的文件模式   |
+| `debug`       | `boolean`                  | `false`                    | 启用调试日志     |
+| `strategies`  | `Record<string, Strategy>` | `{}`                       | 构建策略配置     |
+| `pageConfigs` | `Function \| Object`       | `{}`                       | 页面配置         |
 
-```typescript
-// 开发模式
-if (pageConfig?.template) {
-  const templatePath = path.resolve(pageConfig.template);
-  // 使用指定模板
-}
-
-// 构建模式
-const templateFile = pageConfig?.template || options.template;
-// 使用相同的模板选择逻辑
-```
-
-#### 4. 构建策略应用
+### 工具函数
 
 ```typescript
-// 开发模式：应用策略到开发配置
-if (strategy.viteConfig) {
-  config.css = { ...config.css, ...strategy.viteConfig.css };
-  config.define = { ...config.define, ...strategy.define };
-}
+import { defineConfig, defineConfigTransform } from 'vite-plugin-multi-page';
 
-// 构建模式：应用策略到构建配置
-if (strategy.viteConfig) {
-  applyBuildStrategy(config, strategy);
-}
-```
-
-### 验证一致性
+// 定义配置
+export default defineConfig(context => ({
+  // 配置选项
+}));
 
-运行示例项目验证配置一致性：
+// 配置转换
+const transform = defineConfigTransform((config, context) => {
+  // 修改配置
+  return config;
+});
+```
 
-```bash
-# 开发模式
-cd example
-npm run dev
-# 访问 http://localhost:5173/mobile.html
+## 示例项目
 
-# 构建模式
-npm run build
-npm run preview
-# 访问 http://localhost:4173/mobile.html
+查看 [example](./example) 目录获取完整的示例项目。
 
-# 对比两种模式下的页面表现应该完全一致
-```
+## 许可证
 
-## 🌟 使用场景
+MIT License