基于 webpack 的开发环境 API Mock 与代理管理插件

在前端开发中，频繁切换接口环境（Mock/开发/生产）往往需要修改代码或重启服务。本插件通过 Webpack 与中间件技术，实现了一键可视化环境切换，让开发调试变得前所未有的流畅与高效。

核心特性

• 浏览器端一键切换：页面右下角悬浮控制面板，支持 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 完美支持 | ✅ | ❌ | ❌ |

安装

npm install mock-switch-webpack-plugin --save-dev
# or
yarn add mock-switch-webpack-plugin -D

使用

方式一：原生 Webpack 项目

webpack.config.js

const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');

module.exports = {
  // ... 其他配置
  plugins: [
    new MockSwitchWebpackPlugin({
      mockDir: './mock',
      apiPrefix: '/api',
      environments: {
        dev: {
          name: '开发环境',
          target: 'http://localhost:8080'
        },
        prod: {
          name: '生产环境',
          target: 'https://api.example.com'
        }
      }
    })
  ]
};

方式二：CRA (Create React App) 项目

CRA 项目需要同时配置 webpack.config.js 和 setupProxy.js 两个文件。

步骤 1：配置 webpack.config.js

webpack.config.js

const MockSwitchWebpackPlugin = require('mock-switch-webpack-plugin');

module.exports = {
  webpack: {
    plugins: [
      new MockSwitchWebpackPlugin({
        autoRegisterMiddleware: false, // CRA 必须设为 false
      })
    ]
  }
};

💡 作用：向打包输出注入客户端 UI 代码，实现浏览器右下角的环境切换悬浮面板。

步骤 2：配置 src/setupProxy.js

src/setupProxy.js

const { createMockMiddleware } = require('mock-switch-webpack-plugin');

module.exports = function(app) {
  createMockMiddleware(app, {
    mockDir: './mock',
    apiPrefix: '/api',
    environments: {
      dev: {
        name: '开发环境',
        target: 'http://localhost:8080'
      },
      prod: {
        name: '生产环境',
        target: 'https://api.example.com'
      }
    }
  });
};

💡 setupProxy.js 作用说明：

• CRA 开发服务器启动时自动加载此文件;

• 用于注册 Express 中间件，接管 API 请求;

• 实现 Mock 数据返回与代理转发逻辑;

• 使用单例模式，解决 CRA 热重载导致的重复实例问题;

方式三：Vue CLI 项目

Vue CLI 项目需要在 vue.config.js 中同时配置 插件实例 和 devServer 中间件 两部分。

vue.config.js

const { defineConfig } = require("@vue/cli-service");
const path = require("path");
const MockSwitchWebpackPlugin = require("mock-switch-webpack-plugin");

// 1. 创建插件实例（共享同一份配置）
const mockPlugin = new MockSwitchWebpackPlugin({
  // 配置项
});

module.exports = defineConfig({
  transpileDependencies: true,

  // 2. 配置插件：注入客户端 UI 代码
  configureWebpack: {
    plugins: [mockPlugin],
  },

  // 3. 配置 devServer：注册服务端路由（在 Express 服务上注册 Mock 数据返回、代理转发等逻辑）
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      // 获取 Express app 实例
      const app = devServer.app;

      // 注册中间件
      mockPlugin.registerRoutesWithBodyParser(app);

      return middlewares;
    },
  },
});

💡 setupMiddlewares 作用说明：

• Vue CLI 内部对 devServer 配置有独立的处理流程，插件通过 compiler.options.devServer 修改的配置会被 Vue CLI 覆盖，导致自动注册的中间件不生效;

• 因此需要在 setupMiddlewares 钩子中手动调用 registerRoutesWithBodyParser() 来完成路由注册;

• 这是 Vue CLI 环境下的标准做法，确保 Mock 路由能正确接管 API 请求;

启动开发服务

npm run start

• 打开浏览器，你会看到右下角的悬浮切换按钮
• 点击按钮展开控制面板，进行环境实时切换 🎉🎉🎉

配置说明

完整配置项

new MockSwitchWebpackPlugin({
  /**
   * Mock 文件存放目录
   * @default './mock'
   */
  mockDir: './mock',

  /**
   * API 请求前缀
   * @default '/api'
   */
  apiPrefix: '/api',

  /**
   * 是否启用 Mock 文件热更新
   * @default true
   */
  hotReload: true,

  /**
   * 是否自动注册 DevServer 中间件
   * @default true
   * CRA 项目请设为 false，使用 createMockMiddleware
   */
  autoRegisterMiddleware: true,

  /**
   * 环境配置
   * 内置 mock/dev/prod 三个环境，可自定义名称和目标地址
   */
  environments: {
    mock: {
      name: 'Mock环境',
      target: null  // null 表示使用本地Mock文件
    },
    dev: {
      name: '开发环境',
      target: 'http://localhost:8080'
    },
    prod: {
      name: '生产环境',
      target: 'https://api.example.com'
    }
  }
})

environments 配置详解

每个环境配置包含：

|参数|类型|说明| |---|---|---| |name|string|环境名称| |target|string | null|代理目标地址，null 表示使用 Mock|

示例：自定义环境

environments: {
  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 开发服务器启动时会自动加载此文件。

createMockMiddleware 函数参数

createMockMiddleware(app, options)

|参数|类型|说明| |---|---|---| |app|Express|Express 应用实例，由 CRA 传入| |options|Object|配置选项，与插件构造函数参数一致|

Mock 文件规范

目录结构

your-project/
├── mock/
│   ├── GET_users.json          # GET /api/users
│   ├── POST_users.js           # POST /api/users
│   ├── GET_users_1.json        # GET /api/users/1
│   └── GET_users_1_orders.js   # GET /api/users/1/orders
└── src/

文件命名规则

插件会按以下优先级查找 Mock 文件：

1. {METHOD}_{path}.json - 带方法的 JSON 文件

2. {path}.json - 不带方法的 JSON 文件

3. {METHOD}_{path}.js - 带方法的 JS 文件

4. {path}.js - 不带方法的 JS 文件

path 中的 / 会被替换为 _

静态 Mock (JSON 文件)

mock/GET_users.json

{
  "code": 0,
  "message": "success",
  "data": [
    { "id": 1, "name": "张三" },
    { "id": 2, "name": "李四" }
  ],
  "_delay": 500
}

动态 Mock (JS 文件)

mock/POST_users.js

module.exports = function(req, res) {
  // 可以访问请求参数
  const { name, age } = req.body;
  
  // 返回动态数据
  return {
    code: 0,
    message: 'success',
    data: {
      id: Date.now(),
      name,
      age,
      createdAt: new Date().toISOString()
    },
    _delay: 300  // 模拟网络延迟（毫秒）
  };
};

特殊字段 _delay

在返回数据中添加 _delay 字段可以模拟网络延迟：

{
  "code": 0,
  "data": {},
  "_delay": 1000  // 延迟 1 秒返回
}

2. 创建 Mock 文件

在项目根目录创建 mock 文件夹，按以下命名规则创建文件：

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)

// mock/GET_user_list.json
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      { "id": 1, "name": "张三" },
      { "id": 2, "name": "李四" }
    ]
  },
  "_delay": 500
}

动态 Mock (JS)

// 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: '用户名或密码错误'
  };
};

如果这个插件对你有帮助，欢迎给个 ⭐ Star 哦！！！

GitHub • Issues