MSW Dashboard

一个 Mock Service Worker (MSW) 管理工具，提供便捷的 CLI 命令和直观的 Web 管控界面，帮助开发者轻松管理和配置 API 模拟请求。

⚠️ 重要说明

msw-dashboard 是基于 Mock Service Worker (MSW) 的管理工具，需要与 MSW 结合使用。 使用本工具前请先确保项目中已经集成 MSW，详见msw官网：Browser integration。

✨ 特性

• 🚀 CLI 工具 - 命令行界面，支持快速初始化和启动管理界面
• 🎯 Web 界面 - 现代化的管理面板，支持实时预览和编辑
• 🔄 实时同步 - WebSocket 连接，确保数据实时更新
• ⏺️ 接口录制 - 支持真实接口录制，一键创建模拟请求

🚀 快速开始

前提条件

在开始使用 MSW Dashboard 之前，请确保：

1. 已安装 MSW: 在您的项目中安装并配置了 Mock Service Worker
2. 了解 MSW 基础: 熟悉 MSW 的基本概念和工作原理

1. 安装和配置 MSW (必需)

如果您的项目还未集成 MSW，请先完成以下步骤：

# 1. 安装 MSW
pnpm add -D msw

# 2. 初始化 Service Worker 脚本
npx msw init <PUBLIC_DIR> --save

2. 安装 MSW Dashboard

# 使用 pnpm (推荐)
pnpm add msw-dashboard

# 使用 npm
npm install msw-dashboard

# 使用 yarn
yarn add msw-dashboard

3. 初始化配置

npx mswd init

在您的项目根目录下执行上面命令，MSW Dashboard 会自动生成 .mswd 目录结构，包含完整的 MSW 集成代码：

目录结构：

.mswd/
├── browser.ts          # MSW 浏览器集成文件
├── config.json         # MSW Dashboard 配置
├── resolver.ts         # 处理器解析器
├── handlers/           # Mock 处理器目录
│   ├── index.ts       # 处理器入口文件
│   └── *.json         # 各个 API 的 Mock 配置
└── mocks/             # Mock 数据目录

在项目中集成：

// src/main.tsx
import { createRoot } from "react-dom/client";
import App from "./App.tsx";

// 1. 引入 `.mswd` 目录下预设好的函数
import { enableMocking } from "../.mswd/browser";

// 2. 执行该异步函数后启动您的应用
enableMocking().then(() => {
  createRoot(document.getElementById("root")!).render(<App />);
});

配置文件 (.mswd/config.json)：

{
  "mswEnabled": true,  // 全局启用 MSW Dashboard
  "delay": 500,        // 控制所有模拟请求的网络延迟 (毫秒)
  "port": 51011        // Dashboard 服务端口（默认: 51011），可自定义
}

重要说明：

• MSW Dashboard 使用 mswEnabled 配置控制是否启用 Mock
• 不启动管控界面（mswd ui）时 MSW 功能不会生效
• 目录 .mswd/ 下的文件由 MSW Dashboard 自动生成和管理

‼️重要说明： 正常开启/关闭（按 Ctrl + c 时） Dashboard 时会自动设置 mswEnabled 设置为 true/false。 如果意外关闭 Dashboard 后发现 msw 仍然生效，请检查 mswEnabled 是否为 true。

4. 启动 UI 界面

npx mswd ui

这个命令会启动一个服务与静态页面，访问控制台输出的 URL 即可使用管理界面。

5. 验证集成

当执行 ui 命令后，集成步骤完毕。在浏览器开发者工具的控制台中应该能看到：

[MSW] Mocking enabled.

验证步骤：

1. 检查配置文件: 确认 .mswd/config.json 中 mswEnabled: true
2. 查看控制台: 应显示上述成功消息
3. 测试 Mock 接口: 发送请求到配置的 Mock API，验证返回模拟数据
4. WebSocket 连接: 如果启用了 Dashboard，会自动连接到管理界面

如果集成失败，可能看到：

MSW Dashboard is disabled. Set 'mswEnabled: true' in .mswd/config.json to enable mocking.

这表示需要检查配置或重新初始化 MSW Dashboard。

CLI 命令

# 显示帮助信息
npx mswd --help

# 初始化 MSW Dashboard 配置
npx mswd init

# 启动 Web 管理界面
npx mswd ui

📖 文档

📚 完整指南

• 📋 安装指南 - 详细的安装步骤和系统要求
• 🎯 使用教程 - 全面的使用指南和最佳实践
• 📝 更新日志 - 版本历史和变更记录
• 🤝 贡献指南 - 如何参与项目贡献

🔗 相关链接

• GitHub 仓库
• npm 包
• 问题反馈
• 讨论区

❓ 常见问题

MSW 集成相关

Q: dynamic import warning

在 .mswd/resolver.ts 中使用了 import 动态导入 Mock 处理器文件。如果开发阶段在终端出现警告

# In Vite
The above dynamic import cannot be analyzed by Vite.
See https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars#limitations for supported dynamic import formats. If this is intended to be left as-is, you can use the /* @vite-ignore */ comment inside the import() call to suppress this warning.

# In Webpack
warn    Compile warning: 
File: .mswd/resolver.ts:1:1
  ⚠ Critical dependency: the request of a dependency is an expression

出现上述问题时，需要在 import 语句中添加注释 /* webpackIgnore: true */ 来告诉 Webpack 忽略该动态导入。 或者在 Vite 中添加注释 /* @vite-ignore */ 来告诉 Vite 忽略该动态导入。

目前，msw-dashboard 已支持 Vite、Webpack 项目。

Q: 什么是 MSW？为什么需要它？

A: Mock Service Worker (MSW) 是一个 API 模拟库，使用 Service Worker 在网络层面拦截请求。MSW Dashboard 是 MSW 的管理工具，需要与 MSW 配合使用才能发挥作用。

Q: 如何知道 MSW Dashboard 是否正确集成？

A: 检查以下几个方面：

1. 控制台消息: 浏览器控制台应显示 [MSW] Mocking enabled.
2. 配置检查: 启动 mswd ui 后，确保 .mswd/config.json 中 mswEnabled: true
3. 文件结构: 项目中应有完整的 .mswd/ 目录结构

Q: enableMocking() 函数报错怎么办？

A: 常见错误和解决方案：

1. "MSW Dashboard is disabled":

   • 检查 .mswd/config.json 中 mswEnabled 是否为 true

2. "Cannot resolve module './.mswd/browser'":

   • 确保运行了 npx mswd init 生成 .mswd 目录
   • 检查 .mswd/browser.ts 文件是否存在

3. Service Worker 注册失败:

   • 确保在 HTTPS 环境或 localhost 下运行
   • 检查 mockServiceWorker.js 文件是否存在于公共目录
   • 运行 npx msw init public --save 生成 Service Worker 文件

Q: 如何控制 Mock 的启用和禁用？

A: MSW Dashboard 提供了配置化的控制方式：

// .mswd/config.json
{
  "mswEnabled": true,  // 设为 false 可禁用 Mock
  "delay": 500,        // 控制响应延迟
  "port": 51011        // 控制管控界面启动时的端口
}

这比传统的环境变量控制更灵活，可以在开发过程中随时切换。

使用相关

Q: Mock 处理器不生效？

A: 请确认：

1. MSW 已正确集成并启动
2. 处理器已正确启用
3. URL 路径匹配正确
4. 浏览器开发者工具中无错误信息
5. Service Worker 已成功注册

Q: 如何在不同框架中使用？

A: MSW Dashboard 可以在任何支持 MSW 的框架中使用，集成方式基本相同：

• React:

// src/index.tsx
import { enableMocking } from "../.mswd/browser";

enableMocking().then(() => {
  ReactDOM.render(<App />, document.getElementById('root'));
});

• Vue:

// src/main.js
import { enableMocking } from "../.mswd/browser";

enableMocking().then(() => {
  createApp(App).mount('#app');
});

• Vanilla JS:

// 在 入口 JS 文件中
import { enableMocking } from "../.mswd/browser";

document.addEventListener("DOMContentLoaded", async () => {
  await enableMocking();
  // 启动应用逻辑
});

开发相关

Q: 支持 TypeScript 吗？

A: 完全支持！MSW Dashboard 本身就是用 TypeScript 开发的，提供完整的类型定义。

Q: 如何调试 Mock 处理器？

A: 可以通过以下方式调试：

1. 查看浏览器开发者工具的 Network 标签
2. 在 MSW 处理器中添加 console.log
3. 使用 MSW 的生命周期事件进行调试
4. 检查 Service Worker 的状态和日志

🤝 贡献

欢迎贡献代码！请查看 贡献指南 了解详细信息。

📄 许可证

MIT License

🙏 致谢

感谢所有贡献者和开源社区的支持！

MSW Dashboard - 让 API Mock 变得简单而强大 🚀