PocketMocker 是什么？

PocketMocker 是一款前端开发专用的页面内 HTTP 控制器。

简单来说，让你直接决定接口返回什么——无需改后端，无需起 Mock Server。

它提供了一个可视化控制面板直接嵌入浏览器，让你实时拦截和操作 HTTP 响应，通过即时看到变化来快速构建健壮的 UI。

为什么选择 PocketMocker？

轻松 Mock

告别手写 Mock 代码。自动拦截请求，智能生成数据，一键导入 API 文档。

完全掌控

• 时序控制：模拟网络延迟、竞态条件
• 状态控制：强制 500 错误、401 未授权、空响应
• 载荷注入：测试边界数据和异常情况

即时调试

在浏览器中实时编辑响应，立即看到 UI 更新。无需切换工具，保持开发心流。

实际应用场景

即时状态切换

一键切换成功、错误（500/404）或空数据状态。验证您的 UI 如何处理加载动画或错误提示，无需修改任何代码。

实时数据调整

需要测试超长用户名？缺失的头像？或特定的价格格式？直接在面板中编辑响应 JSON，立即看到 UI 更新。

边界情况验证

模拟网络延迟、超时错误或未授权（401）响应，确保您的应用优雅地处理异常情况。

https://github.com/user-attachments/assets/e7501191-7ef1-4bd4-bd21-6500585fe4ad

何时使用 PocketMocker？

使用 Postman 进行：

• API 设计与文档
• 后端契约测试
• 团队级 API 管理

使用 PocketMocker 进行：

• 快速 UI 开发："我现在就需要让这个列表为空。"
• 可视化调试："为什么我的错误边界没有显示？"
• 零上下文切换：留在浏览器中，保持心流状态。
• Git 友好：通过配置文件共享 Mock 规则，就像您的代码一样。

安装

npm install pocket-mocker --save-dev
# 或者
yarn add pocket-mocker -D
# 或者
pnpm add pocket-mocker -D

快速开始

方式一：零配置使用（本地模式）

适合个人开发或快速尝试。直接在项目的入口文件中引入并启动：

import { pocketMock } from 'pocket-mocker';

// 仅在开发环境中启动
if (process.env.NODE_ENV === 'development') {
  pocketMock();
}

启动项目后，页面右下角会出现 PocketMocker 浮窗。

方式二：团队协作模式（Vite 插件）🔥 推荐

适合生产级项目。通过 Vite 插件打通文件系统，将 Mock 规则保存为配置文件，方便团队共享。

1. 在入口文件引入

import { pocketMock } from 'pocket-mocker';

if (process.env.NODE_ENV === 'development') {
  pocketMock();
}

2. 配置 vite.config.ts

import { defineConfig } from 'vite';
import pocketMockPlugin from 'pocket-mocker/vite-plugin';

export default defineConfig({
  plugins: [
    pocketMockPlugin()
  ]
});

3. 启动开发

运行 npm run dev。PocketMock 会自动检测插件环境并切换到 服务器模式。

进阶功能

URL 模式匹配

PocketMock 支持强大的 URL 模式来模拟复杂的 API：

• 路径参数: /api/users/:id → 匹配 /api/users/123, /api/users/john
• 通配符: /api/* → 匹配 /api/users, /api/users/123/posts
• 混合模式: /api/:version/users/*/profile → 匹配 /api/v1/users/123/profile

在模拟函数中获取捕获的参数：

(req) => {
  const { id, version } = req.params;
  const { include } = req.query;
  return { id: parseInt(id), version, includeAuthor: include === 'true' };
}

智能 Mock 数据生成

PocketMock 内置强大的智能生成器，使用简单语法即可生成逼真的测试数据。

快速体验

{
  "user": {                            // → 生成用户数据
    "id": "@guid",                    // → "550e8400-e29b-41d4"
    "name": "@name",                  // → "张三"
    "username": "@username",        // → "brightpanda"
    "email": "@email",                // → "zhangsan@example.com"
    "avatar": "@image(100x100)",      // → "https://via.placeholder.com/100x100"
    "age": "@integer(18,60)",        // → 25
    "role": "@pick(管理员,用户)",       // → "管理员"
    "ip": "@ip()",                   // → "192.168.1.1"
    "ipv6": "@ip(v6)"                 // → "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
  }
}

常用生成器

更多功能

{
  "users|5": {            // 生成5个用户
    "id": "@guid",
    "name": "@name"
  },
  "scores|3-5": "@integer(60,100)"  // 生成3到5个分数
}

动态响应（函数 Mock）

不再局限于静态 JSON！你可以编写 JavaScript 函数来根据请求动态生成响应。

(req) => {
  // 根据 Query 参数动态返回
  if (req.query.id === '1') {
    return { id: 1, name: '管理员', role: 'admin' };
  }

  // 根据 Body 内容判断
  if (req.body?.type === 'error') {
    return {
      status: 400,
      body: { message: '参数错误' }
    };
  }

  // 默认返回
  return { id: 2, name: '访客' };
}

导入与导出

无缝集成现有的 API 工作流。

• 导入: 支持从 Postman Collection (v2.1) 和 OpenAPI 3.0 (Swagger) 文件直接导入 Mock 规则。
  • 智能转换将自动映射字段，如 user_id 映射为 @guid。
• 导出: 支持直接从规则编辑器将任意 Mock 规则导出为 Postman JSON 格式，方便分享或在其他工具中测试。

使用方法: 点击控制台顶部的"导入"按钮，选择 JSON 文件即可。

功能全面的网络面板

内置的网络面板将实时记录所有网络请求（包括 Mocked 和真实请求），提供强大的调试功能：

• 查看详情: 点击日志查看完整的 Request/Response Body。
• 右键菜单: 在任意日志上右键单击即可：
  • 复制 URL/响应: 快速复制数据到剪贴板。
  • 复制为 cURL: 生成 cURL 命令以便在终端重现请求。
  • 添加到 Mock 规则: 即时将真实请求转换为 Mock 规则。
• 筛选: 支持按 URL、方法、Mock 状态筛选。

技术原理

• 猴子补丁: 通过重写 window.fetch 和扩展 XMLHttpRequest 原型链来拦截请求
• Shadow DOM: 使用 Shadow Root 封装调试 UI，实现样式完全沙箱化
• Vite 库模式: 使用 Vite 的库模式和 css: 'injected' 策略，将 CSS 内联到 JS 中，实现单文件导入体验

项目路线图

查看我们的 项目路线图，了解 PocketMocker 的未来规划以及如何参与贡献！

贡献与联系

我们欢迎所有对 PocketMocker 的贡献！无论是报告 Bug、提出新功能建议、改进文档还是提交代码，您的帮助都将使 PocketMocker 变得更好。

请阅读我们的 贡献指南 了解如何参与项目。

联系我

如果您有任何疑问、建议或想加入交流，欢迎通过以下方式联系：

• Twitter (X): https://x.com/tiancha79267301
• 微信

License

MIT © tianchangNorth