mock-switch-webpack-plugin 1.2.0 → 1.3.0

package/README.md

@@ -1,82 +1,47 @@
-# Mock Switch Webpack Plugin README
+<div align="center">
 
+[![npm version](https://img.shields.io/npm/v/mock-switch-webpack-plugin)](https://www.npmjs.com/package/mock-switch-webpack-plugin)
+![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 
+**基于 webpack 的开发环境 API Mock 与代理管理插件**
 
-**前端开发环境 API Mock 与代理管理插件**
+</div>
 
-一键切换 Mock / 开发 / 生产环境，Mock 数据热更新，无需重启服务
+在前端开发中，频繁切换接口环境（Mock/开发/生产）往往需要修改代码或重启服务。本插件通过 Webpack 与中间件技术，实现了一键可视化环境切换，让开发调试变得前所未有的流畅与高效。
 
-\[特性\]\(\#\-核心特性\) • \[安装\]\(\#\-安装\) • \[快速开始\]\(\#\-快速开始\) • \[配置说明\]\(\#\-配置说明\) • \[Mock 规范\]\(\#\-mock\-文件规范\)
+## 核心特性
 
+- **浏览器端一键切换**：页面右下角悬浮控制面板，支持 Mock / 开发 / 生产环境无缝切换，无需修改代码或重启服务；
+- **Mock 数据热更新**：修改 Mock 文件立即生效，无需重启服务；
+- **自动路径匹配**：根据接口路径自动查找对应的 Mock 文件；
+- **智能请求处理**：支持 POST/PUT/PATCH 请求 body 自动解析与转发；
+- **热重载友好**：全局单例模式，防止 CRA 热重载时重复创建实例，并且热重载不会丢失当前的环境状态，实现状态持久化；
+- **全平台兼容**：
+  - 支持 **CRA (Create React App)**、**Vue CLI** 及所有基于 Webpack 的项目；
+  - 兼容 Webpack 3/4/5 的 DevServer API 差异；
+- **开箱即用**：自动注入 UI 代码，自动配置路由，零配置即可体验；
 
+## 与其他方案VS对比
 
-## 🎯 核心特性
+| 功能 | mock-switch-webpack-plugin | mocker-api | 其他 |
+|------|---------------------------|------------|-------------------|
+| 浏览器可视化一键切换    | ✅ | ❌      | ❌        |
+| Mock数据热更新         | ✅ | ✅      | ❌需重启   |
+| 环境持久化             | ✅ | ❌      | ❌        |
+| POST Body 自动解析转发 | ✅ | ❌需手动 | ❌ 需手动 |
+| CRA 完美支持           | ✅ | ❌      | ❌        |
 
-### ✨ 浏览器端一键环境切换
-
-- 右下角悬浮控制面板，可视化切换环境
-
-- 实时状态显示，不同环境对应不同颜色标识
-
-- 无需修改代码或重启服务
-
-### 🔥 Mock 数据热更新
-
-- 修改 Mock 文件立即生效，无需重启 Webpack DevServer
-
-- 自动清除 require 缓存，实时加载最新数据
-
-- 支持开发过程中快速调试接口
-
-### 📦 开箱即用，零配置
-
-- 支持 **CRA \(Create React App\)**、**Vue CLI**、**原生 Webpack** 等所有项目
-
-- 兼容 Webpack 3/4/5 全版本
-
-- 兼容 Webpack 打包发布模式
-
-### 🔌 智能请求处理
-
-- POST/PUT/PATCH 请求 body 自动解析与转发
-
-- 支持 JSON 和表单格式请求
-
-- 自动移除 API 前缀，无缝代理转发
-
-### 🛡️ 热重载友好
-
-- 全局单例模式，防止 CRA 热重载时重复创建实例
-
-- 环境状态跨热重载持久化
-
-- 解决全局状态隔离问题
-
-## 🆚 方案对比
-
-|特性|Mock Switch|mockjs|http\-proxy\-middleware|
-|---|---|---|---|
-|浏览器可视化切换|✅|❌|❌|
-|Mock 数据热更新|✅|❌|\-|
-|无需重启服务|✅|❌|❌|
-|多环境一键切换|✅|❌|✅|
-|POST Body 自动解析|✅|❌|⚠️ 需手动|
-|CRA 友好支持|✅|⚠️|⚠️|
-|打包兼容|✅|✅|✅|
-
-## 📦 安装
+## 安装
 
 ```bash
 npm install mock-switch-webpack-plugin --save-dev
 # or
 yarn add mock-switch-webpack-plugin -D
-# or
-pnpm add mock-switch-webpack-plugin -D
 ```
 
-## 🚀 快速开始
+## 使用
 
-### 方式一：原生 Webpack 项目（推荐）
+### 方式一：原生 Webpack 项目
 
 **webpack\.config\.js**
 
@@ -110,9 +75,8 @@ CRA 项目需要同时配置 **webpack\.config\.js** 和 **setupProxy\.js** 两
 
 #### 步骤 1：配置 webpack\.config\.js
 
-使用 `craco` 或 `react-app-rewired` 覆盖 Webpack 配置：
 
-**craco\.config\.js** 或 **config\-overrides\.js**
+**webpack\.config\.js**
 
 ```javascript
 const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');
@@ -121,8 +85,7 @@ module.exports = {
   webpack: {
     plugins: [
       new MockSwitchWebpackPlugin({
-        autoRegisterMiddleware: false,  // CRA 必须设为 false
-        hotReload: true
+        autoRegisterMiddleware: false, // CRA 必须设为 false
       })
     ]
   }
@@ -135,7 +98,7 @@ module.exports = {
 
 #### 步骤 2：配置 src/setupProxy\.js
 
-**src/setupProxy\.js**（CRA 官方约定的代理配置文件）
+**src/setupProxy\.js**
 
 ```javascript
 const { createMockMiddleware } = require('mock-switch-webpack-plugin');
@@ -160,13 +123,13 @@ module.exports = function(app) {
 
 > 💡 **setupProxy\.js 作用说明**：
 > 
-> - CRA 开发服务器启动时自动加载此文件
+> - CRA 开发服务器启动时自动加载此文件;
 > 
-> - 用于注册 Express 中间件，接管 API 请求
+> - 用于注册 Express 中间件，接管 API 请求;
 > 
-> - 实现 Mock 数据返回与代理转发逻辑
+> - 实现 Mock 数据返回与代理转发逻辑;
 > 
-> - 使用单例模式，解决 CRA 热重载导致的重复实例问题
+> - 使用单例模式，解决 CRA 热重载导致的重复实例问题;
 > 
 > 
 
@@ -188,8 +151,16 @@ module.exports = {
 };
 ```
 
-## ⚙️ 配置说明
+### 启动开发服务
+
+```bash
+npm run start
+```
 
+- 打开浏览器，你会看到右下角的悬浮切换按钮 
+- 点击按钮展开控制面板，实现环境实时切换 🎉
+
+## 配置说明
 ### 完整配置项
 
 ```javascript
@@ -240,42 +211,30 @@ new MockSwitchWebpackPlugin({
 })
 ```
 
-### environments 详解
+### environments 配置详解
 
 每个环境配置包含：
 
 |参数|类型|说明|
 |---|---|---|
-|`name`|string|环境显示名称，支持 emoji|
+|`name`|string|环境名称|
 |`target`|string \| null|代理目标地址，null 表示使用 Mock|
 
 **示例：自定义环境**
 
 ```javascript
 environments: {
-  mock: { name: '🟢 Mock环境', target: null },
-  test: { name: '🔵 测试环境', target: 'http://test-api.example.com' },
-  pre: { name: '🟡 预发环境', target: 'http://pre-api.example.com' },
+  mock: { name: 'Mock环境', target: null },
+  dev: { name: '开发环境', target: 'http://dev-api.example.com' },
   prod: { name: '🔴 生产环境', target: 'https://api.example.com' }
 }
 ```
-
----
-
 ### setupProxy\.js 配置详解（CRA 专用）
 
 #### 什么是 setupProxy\.js？
 
 `setupProxy.js` 是 **Create React App** 官方约定的代理配置文件，位于 `src/` 目录下，CRA 开发服务器启动时会**自动加载**此文件。
 
-#### 为什么 CRA 需要 setupProxy\.js？
-
-1. **CRA 隐藏了 webpack\.config\.js**，无法直接修改 DevServer 配置
-
-2. **HTTP 代理中间件**必须在 Express 应用层注册
-
-3. **Mock 逻辑**需要在请求到达 React 之前拦截处理
-
 #### createMockMiddleware 函数参数
 
 ```javascript
@@ -287,37 +246,7 @@ createMockMiddleware(app, options)
 |`app`|Express|Express 应用实例，由 CRA 传入|
 |`options`|Object|配置选项，与插件构造函数参数一致|
 
-#### 内部工作原理
-
-```javascript
-function createMockMiddleware(app, options) {
-  // 1. 单例模式：热重载复用已有实例
-  if (_pluginSingleton) return _pluginSingleton;
-  
-  // 2. 创建插件实例（关闭自动注册中间件）
-  _pluginSingleton = new MockSwitchWebpackPlugin({
-    ...options,
-    autoRegisterMiddleware: false
-  });
-  
-  // 3. 手动注册路由和中间件
-  _pluginSingleton.registerRoutesWithBodyParser(app);
-  
-  return _pluginSingleton;
-}
-```
-
-#### ✅ 关键配置要点
-
-- **必须**设置 `autoRegisterMiddleware: false`
-
-- **必须**使用 `createMockMiddleware` 而非直接 `new MockSwitchWebpackPlugin()`
-
-- **支持**热重载：全局单例 \+ 状态持久化
-
-- **自动**注册 express\.json \(\) 和 urlencoded 中间件
-
-## 📝 Mock 文件规范
+## Mock 文件规范
 
 ### 目录结构
 
@@ -399,78 +328,62 @@ module.exports = function(req, res) {
 }
 ```
 
-## 🎨 控制面板预览
 
-启动项目后，浏览器右下角会出现悬浮按钮：
 
-- 🟢 **绿色** \- Mock 环境
 
-- 🟡 **黄色** \- 开发环境
 
-- 🔴 **红色** \- 生产环境
 
-点击按钮展开面板，点击对应环境即可实时切换。
+### 2. 创建 Mock 文件
 
-## 🔧 API 接口
+在项目根目录创建 `mock` 文件夹，按以下命名规则创建文件：
 
-插件自动注册以下控制接口，可用于编程式切换：
-
-### 获取当前环境
-
-```Plain Text
-GET /__mock_switch__/env
+```
+mock/
+├── GET_user_list.json          # GET /api/user/list
+├── POST_user_login.js          # POST /api/user/login
+├── GET_user_1_detail.json      # GET /api/user/1/detail
+└── config.js                   # 其他配置
 ```
 
-**响应：**
+#### 静态 Mock (JSON)
 
 ```json
+// mock/GET_user_list.json
 {
-  "currentEnv": "mock",
-  "environments": [
-    { "key": "mock", "name": "Mock环境", "target": null },
-    { "key": "dev", "name": "开发环境", "target": "http://localhost:8080" },
-    { "key": "prod", "name": "生产环境", "target": "https://api.example.com" }
-  ]
+  "code": 0,
+  "message": "success",
+  "data": {
+    "list": [
+      { "id": 1, "name": "张三" },
+      { "id": 2, "name": "李四" }
+    ]
+  },
+  "_delay": 500
 }
 ```
 
-### 切换环境
-
-```Plain Text
-POST /__mock_switch__/env
-Content-Type: application/json
+#### 动态 Mock (JS)
 
-{
-  "env": "dev"
-}
+```javascript
+// mock/POST_user_login.js
+module.exports = function(req, res) {
+  const { username, password } = req.body;
+  
+  if (username === 'admin' && password === '123456') {
+    return {
+      code: 0,
+      message: '登录成功',
+      data: { token: 'mock_' + Date.now() }
+    };
+  }
+  
+  return {
+    code: 401,
+    message: '用户名或密码错误'
+  };
+};
 ```
 
-## ❓ 常见问题
-
-### Q: CRA 热重载后环境状态丢失？
-
-A: 插件已内置全局状态持久化机制，使用 `createMockMiddleware` 即可自动处理。
-
-### Q: Mock 文件修改后不生效？
-
-A: 确保 `hotReload: true`（默认开启），插件会自动清除 require 缓存。
-
-### Q: POST 请求 body 为空？
-
-A: 插件已内置 express\.json \(\) 和 urlencoded 解析中间件，无需额外配置。
-
-### Q: 代理请求 404？
-
-A: 插件会自动移除 `apiPrefix` 前缀，如 `/api/users` → `/users`，确保后端接口路径正确。
-
-## 📄 License
-
-MIT © [lebron\_shi](https://github.com/shilimingY)
-
----
-
-
-
-**如果这个插件对你有帮助，欢迎给个 ⭐ Star**
+**如果这个插件对你有帮助，欢迎给个 ⭐ Star 哦！！！**
 
 [GitHub](https://github.com/shilimingY/mock-switch-webpack-plugin) • [Issues](https://github.com/shilimingY/mock-switch-webpack-plugin/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mock-switch-webpack-plugin",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "前端Mock神器！浏览器一键切换Mock/开发/生产环境的Webpack插件，支持接口代理、Mock数据热更新、POST请求自动转发等特性，零配置接入React/Vue等所有Webpack项目，彻底告别需手动修改代码来切换环境的低效开发方式。",
   "main": "dist/index.js",
   "scripts": {