张瑞15129378030前端开发做到一定阶段，几乎都会被接口联调这件事折腾过。后端还没写好、接口文档频繁变更、测试环境不稳定、异常场景难以复现……这些痛点每个前端er都懂。我自己在前端团队里折腾过好几轮mock方案，从最早的本地json文件、到mockjs拦截XHR、再到json-server起本地服务，直到后来接触了Mock Service Worker（简称MSW），才感觉终于找到了一个真正"站在网络层面做拦截"的优雅方案。这篇文章就围绕MSW展开，从原理到实战，把我在项目中落地这套方案的经验和踩过的坑一起分享出来，希望能帮你少走弯路。
1. Mock方案的前世今生：为什么非要Mock Service Worker不可
1.1 传统Mock方案的三座大山
在讲MSW之前，先聊聊我们为什么需要mock。前端开发是高度依赖接口的，只要后端接口没就绪，前端就被卡死。这不是某个团队的问题，而是全行业普遍的协作痛点。为了不阻塞开发，大家通常用三类方案：
第一种是本地json数据文件。在项目里建一个mock目录，放一堆手写的JSON文件，请求时直接import进来。这种方式最原始，优点是简单，但缺点也很明显——它只在纯前端逻辑层生效，一旦代码里有真实请求发送的异步逻辑，根本无法模拟；而且数据是静态的，想模拟登录失败、网络超时这些动态场景几乎得靠手动改文件，很痛苦。
第二种是拦截HTTP库的方案，典型代表是mockjs和axios-mock-adapter。mockjs通过重写XMLHttpRequest对象，在浏览器请求发出前返回伪造数据；axios-mock-adapter则是直接劫持axios实例的请求方法。这类方案比json文件进了一步，能拦截真实请求，但它们都有一个致命伤——只能拦截特定的请求库。mockjs对fetch无能为力，axios-mock-adapter更是绑定axios，项目里一旦换了请求库，所有mock代码全废。而且这种劫持发生在内存层面，不经过网络栈，看起来多少有点"假"。
第三种是本地起mock服务，比如json-server、koa+mock，或者后端同学临时部署的测试环境。这种方案数据灵活、能模拟真实网络行为，但代价是需要额外维护一个服务进程，而且部署和分享都非常麻烦。团队成员多一个，多一套环境，联调沟通成本直线上升。
这三种方案各有利弊，但共同的问题是：mock代码和业务代码之间存在耦合，或者mock环境与真实网络环境存在距离。开发的时候能用，测试的时候又要重新换一套，功能测试、集成测试、E2E测试各搞各的，mock方案没法复用，维护成本翻倍。
1.2 MSW的差异化打法：网络层拦截
MSW的出现，完全改变了游戏规则。它不是在业务代码层面拦截，也不是在请求库层面拦截，而是直接利用浏览器原生支持的Service Worker，在网络线程层面拦截请求。这意味着你的代码发出的每一个请求都是"真实"的，它会经过完整的请求生命周期，只是被一个"代理"——也就是Service Worker——在中途截获，然后返回你预先定义好的响应。
这个思路很巧妙。因为Service Worker是浏览器底层的能力，所以它不依赖任何请求库，fetch、axios、XMLHttpRequest……通通适用。你在浏览器Network面板里依然能看到这个请求，它照常出现在网络列表里，只是响应内容变成了mock数据。这种"以假乱真"的效果，让mock这件事变得前所未有的干净。
更重要的是，MSW提供了一套统一的API，同一套handler既可以在浏览器环境用setupWorker拦截，也可以在Node测试环境用setupServer运行。这意味着你只需要写一份mock逻辑，开发和自动化测试都能用，彻底解决了之前"开发一套、测试又得换一套"的重复劳动问题。这一条就足够让我在团队里推广它了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心原理拆解：Service Worker如何"骗过"浏览器
2.1 请求拦截的生命周期
很多人第一次接触MSW时，会对"Service Worker踩能拦截请求"这个机制感到好奇。其实它依赖的就是浏览器原生API。Service Worker是一个独立于主线程运行的JavaScript脚本，它和普通脚本最大的区别是：它本质上是一个反向代理，可以监听页面的所有fetch请求。
当你调用worker.start()时，MSW会往页面里注册一个Service Worker脚本。注册成功后，浏览器会把后续所有请求都先交给这个脚本处理。MSW在Service Worker里维护了一个请求监听器，每当有请求经过，它就把请求信息（URL、请求方法、请求头、请求体等）传给主线程的匹配器去比对。
具体流程是这样的：
- 页面业务代码发起一个请求（fetch或XHR）。
- 浏览器将这个请求交给已激活的Service Worker处理。
- Service Worker把请求的method、URL、headers等信息缓存起来，并告诉主线程：这里有一个请求，需要匹配mock规则。
- 主线程的MSW核心库在已注册的handlers列表里逐一匹配。
- 如果能匹配上，就执行对应的resolver函数，生成响应内容，返回给Service Worker。
- Service Worker用这个响应直接回答页面请求，请求结束。
- 如果匹配不上，请求直接放行，走真实网络逻辑。
整个过程非常快，而且对业务代码完全透明。业务代码根本不知道自己的请求被"拦截"过，它拿到的就是一个普通的Response对象。这也是MSW相比其他mock方案最本质的区别——它是在浏览器网络栈的边缘介入，而不是在应用代码内部改写逻辑。
2.2 匹配器与解析器：两个核心概念
理解MSW的玩法，最关键的就是搞清楚两个概念：请求匹配器（Request Matcher）和响应解析器（Resolver）。
请求匹配器就是handler里的第一个参数，用来描述你要拦截什么样的请求。MSW在1.x版本里提供了rest对象，里面封装了rest.get、rest.post、rest.put、rest.delete等常见方法；到了2.x版本，这个API变成了http.get、http.post，写法更简洁。每个方法接受一个URL路径和对应的resolver函数。
javascript复制import { http } from 'msw'
export const handlers = [
// 拦截请求路径为 /api/user 的所有GET请求
http.get('/api/user', (req, res, ctx) => {
return res(
ctx.status(200),
ctx.json({ name: '张三' })
)
}),
]
URL路径支持多种写法，可以写死，也可以用:param的方式提取路径参数，还可以用通配符*匹配任意结尾。比如http.get('/api/user/:id', ...)就能匹配/api/user/1、/api/user/2等所有同一结构的请求，而且处理函数里可以通过req.params.id拿到具体的参数值。
响应解析器则是handler里的第二个参数，也就是那个接收req、res、ctx三个参数的函数。它负责最终构造出响应内容。req包含请求相关的信息，ctx则是MSW提供的一系列工具函数，用来便捷地组合响应状态码、响应头、响应体和延迟。
这里有一个值得注意的点：MSW 2.x里，响应构造方式从res()函数变回了更直观的HttpResponse.json()形式。我项目里用的就是2.x，下面代码就用新写法，如果你还在看1.x的老教程，注意差异。
javascript复制import { http, HttpResponse } from 'msw'
export const handlers = [
http.get('/api/user/:id', ({ params }) => {
return HttpResponse.json({
id: params.id,
name: '李四',
age: 25,
})
}),
]
2.3 响应构造器的灵活用法
刚才看到了最简单的HttpResponse.json()，实际项目中响应头、状态码、延迟这些都是常客。MSW的响应构造器虽然简单，但花样不少，我根据自己的使用经验总结几个高频场景。
javascript复制import { http, HttpResponse } from 'msw'
export const handlers = [
// 带自定义状态码和响应头
http.post('/api/login', async ({ request }) => {
const body = await request.json()
if (body.username === 'admin' && body.password === '123456') {
return new HttpResponse(
JSON.stringify({ token: 'mock-token-xxx' }),
{
status: 200,
headers: {
'Content-Type': 'application/json',
'X-Token': 'mock-token-xxx',
},
}
)
}
return HttpResponse.json(
{ message: '用户名或密码错误' },
{ status: 401 }
)
}),
// 模拟网络延迟
http.get('/api/slow-response', async () => {
await delay(2000)
return HttpResponse.json({ data: '等了2秒' })
}),
]
我在第一次使用MSW的时候，一直纠结一个问题：mock的数据能模拟真实网络状态吗？后来发现MSW在响应构造上考虑得挺全面，状态码、响应头、延迟、甚至网络错误（HttpResponse.error()）都能模拟。这意味着你可以非常逼真地模拟接口超时、服务器500、鉴权失败等场景，开发前端异常处理逻辑的时候特别有用。
3. 从零到一：在项目里落地MSW
3.1 环境准备与安装
说完了原理，下面直接上手操作。MSW对前端项目几乎是无痛的，无论是React、Vue还是原生项目，都可以使用。安装只需要一条命令：
bash复制npm install msw --save-dev
# 或者使用yarn
yarn add msw --dev
安装完成后，需要初始化Service Worker脚本。MSW提供了一个CLI命令，会把mockServiceWorker.js这个文件生成到你的项目public或静态资源目录下。这个文件是MSW运行的核心，一定不能改文件名，也不能手写，它实际上就是一个Service Worker脚本，负责和主线程通讯、拦截请求。
bash复制npx msw init public/
如果你的项目用的是Vite，静态资源目录默认是public；如果是CRA项目，也是public；如果是Next.js，需要放在public目录下，具体路径要根据框架而定。生成完这个文件后，可以看到public/mockServiceWorker.js已经被创建出来。
接下来，我习惯在src/mocks目录下统一管理所有mock代码。这样项目里哪个文件是mock相关的，一目了然，后期移除也方便——直接把src/mocks目录删掉，把入口文件的调用代码注释掉即可。
3.2 初始化Worker与目录规划
我习惯的目录结构长这样：
text复制src/
mocks/
browser.ts # 浏览器环境的worker启动入口
server.ts # Node测试环境的server启动入口
handlers.ts # 所有mock handler的汇总/导出
data/ # mock数据源，可以按模块拆分
user.ts
order.ts
handlers.ts负责把各个业务模块的handler合并导出：
javascript复制import { userHandlers } from './data/user'
import { orderHandlers } from './data/order'
export const handlers = [
...userHandlers,
...orderHandlers,
]
browser.ts负责在浏览器环境注册并启动worker：
javascript复制import { setupWorker } from 'msw/browser'
import { handlers } from './handlers'
export const worker = setupWorker(...handlers)
然后在项目的入口文件（比如React的main.tsx或Vue的main.ts）里，根据环境变量决定是否启动mock。我用的是一个区分环境的变量VITE_ENABLE_MOCK，只有显式开启时才启用：
javascript复制if (import.meta.env.VITE_ENABLE_MOCK === 'true') {
const { worker } = await import('../mocks/browser')
await worker.start()
}
这个做法的好处是：mock完全按需加载，生产构建时根本不会打包mock代码，不影响线上环境的性能。
3.3 一个完整的REST接口模拟流程
下面用一个用户信息模块的例子，完整走一遍REST接口的mock流程。假设后端接口长这样：
GET /api/user/:id：获取用户信息PUT /api/user/:id：更新用户信息GET /api/user/:id/orders：获取用户订单列表
对应的handler代码：
javascript复制import { http, HttpResponse } from 'msw'
// mock数据源，实际项目中可以从data目录导入
const users = {
1: { id: 1, name: '张三', age: 28, email: 'zhangsan@example.com' },
2: { id: 2, name: '李四', age: 32, email: 'lisi@example.com' },
}
const orders = [
{ id: 101, userId: 1, amount: 299, status: 'paid' },
{ id: 102, userId: 1, amount: 199, status: 'pending' },
]
export const userHandlers = [
// 获取用户信息
http.get('/api/user/:id', ({ params }) => {
const user = users[params.id]
if (!user) {
return HttpResponse.json(
{ message: '用户不存在' },
{ status: 404 }
)
}
return HttpResponse.json(user)
}),
// 更新用户信息，从请求体读取数据
http.put('/api/user/:id', async ({ params, request }) => {
const body = await request.json()
const userId = params.id
if (users[userId]) {
users[userId] = { ...users[userId], ...body }
return HttpResponse.json(users[userId])
}
return HttpResponse.json(
{ message: '用户不存在' },
{ status: 404 }
)
}),
// 获取用户订单列表
http.get('/api/user/:id/orders', ({ params }) => {
const userOrders = orders.filter(
(order) => order.userId === Number(params.id)
)
return HttpResponse.json(userOrders)
}),
]
这一段代码看起来很简单，但已经包含了路径参数解析、请求体读取、条件分支、状态码返回等核心用法。实际项目中，我通常还会配合delay来模拟真实网络延迟，避免前端在开发环境"响应太快"而掩盖了loading状态的问题。
启动开发服务器，在浏览器控制台里应该能看到Worker启动成功的日志。此时打开Network面板，请求/api/user/1，你会看到这个请求确实返回了我们在handler里定义的数据。
4. 进阶玩法：GraphQL、错误模拟与动态场景
4.1 GraphQL接口模拟
如果说REST是MSW的基本功，那么对GraphQL的支持就是它的加分项。MSW官方提供了graphql命名空间，可以轻松拦截GraphQL的query和mutation。先看代码：
javascript复制import { graphql, HttpResponse } from 'msw'
export const graphqlHandlers = [
graphql.query('GetUserInfo', ({ variables }) => {
return HttpResponse.json({
data: {
getUserInfo: {
id: variables.id,
name: '王五',
age: 30,
},
},
})
}),
graphql.mutation('UpdateUserInfo', async ({ variables }) => {
return HttpResponse.json({
data: {
updateUserInfo: {
success: true,
},
},
})
}),
]
这里要比对的是操作名称（Operation Name），比如GetUserInfo，而不是具体的请求路径。这是GraphQL和REST在mock时的一个显著不同：GraphQL的请求往往只发到一个地址（通常是/graphql），真正的业务区分是靠query/mutation的名字和参数。所以MSW在这方面很聪明，直接用操作名来匹配。
我自己在项目里用GraphQL时，会把所有handler按业务域拆分开，比如用户域、商品域、订单域，每个域管理自己的query和mutation。这样就算后端GraphQL schema特别庞大，mock代码也不会失控。
4.2 错误状态与网络异常模拟
Mock不只是为了"给前端返回假数据"，很多时候是为了模拟各种异常情况，让前端把错误处理逻辑也写好。我在实际开发中最常模拟的几种场景：
javascript复制import { http, HttpResponse } from 'msw'
export const errorHandlers = [
// 模拟服务端500错误
http.get('/api/error-500', () => {
return new HttpResponse(null, { status: 500 })
}),
// 模拟超时：延迟5秒返回（前端一般会设置超时时间）
http.get('/api/timeout', async () => {
await new Promise((resolve) => setTimeout(resolve, 5000))
return HttpResponse.json({ data: '迟到的响应' })
}),
// 模拟网络异常，让fetch直接抛错
http.get('/api/network-error', () => {
return HttpResponse.error()
}),
]
HttpResponse.error()会把请求变成一个网络级别的错误，fetch会直接走进catch分支，XMLHttpRequest的onerror也会被触发。这对于调试前端全局错误提示、日志上报等功能很有价值。
我还喜欢把异常模拟做成可切换的开关。比如在页面上做一个mock控制面板，通过query参数或者全局变量来切换某个接口是返回正常数据还是错误数据。这样产品、设计同学在做Demo演示时，也能很方便地展示各种状态。
4.3 按登录状态返回不同数据
实际业务里最常见的场景是：同一套接口，根据用户登录状态返回不同的数据。在MSW里实现这种动态逻辑非常简单。我习惯把"当前登录状态"用一个内存变量保存，然后在handler里读取这个变量做分支。
javascript复制import { http, HttpResponse } from 'msw'
// 模拟当前登录状态
let isLoggedIn = false
export const authHandlers = [
http.post('/api/login', async ({ request }) => {
const { username, password } = await request.json()
if (username === 'admin' && password === '123456') {
isLoggedIn = true
return HttpResponse.json({
token: 'mock-token-abc',
username
})
}
return HttpResponse.json(
{ message: '登录失败' },
{ status: 401 }
)
}),
http.post('/api/logout', () => {
isLoggedIn = false
return HttpResponse.json({ success: true })
}),
http.get('/api/user/profile', () => {
if (!isLoggedIn) {
return HttpResponse.json(
{ message: '未登录' },
{ status: 401 }
)
}
return HttpResponse.json({
id: 1,
name: '张三',
role: 'admin',
permissions: ['read', 'write', 'delete'],
})
}),
]
当然，内存变量在浏览器刷新后会重置。如果需要持久化的登录状态，可以把状态存到localStorage里，每次初始化时读取：
javascript复制let isLoggedIn = localStorage.getItem('mock_login') === 'true'
这种用法在写前端登录流程、权限控制相关功能时，非常顺手，不用频繁去改代码，刷新页面就能模拟不同的起始状态。
5. 测试环境里的MSW：同款handlers复用
5.1 setupServer替代setupWorker
MSW最有价值的一点，就是它不止能在浏览器里用，在测试环境里也能跑。你可能要问：需要区分吗？是的，在Node测试环境中并没有Service Worker的概念，所以MSW提供了msw/node的setupServer接口，它用Node的拦截机制（基于@mswjs/interceptors）实现同样的请求拦截能力，只不过是在进程内拦截HTTP请求。
使用方式几乎一致：
javascript复制import { setupServer } from 'msw/node'
import { handlers } from './handlers'
export const server = setupServer(...handlers)
然后在Jest的全局配置里，开启、重置、关闭server：
javascript复制// jest.setup.js 或者测试文件的beforeAll/afterEach
import { server } from './src/mocks/server'
beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())
这段代码的意思是：所有测试运行前启动mock server，每个测试用例结束后重置handlers状态，所有测试结束后关闭server。server.resetHandlers()尤其重要，因为团队里不同成员可能在测试中临时添加过handler，如果不重置，可能会污染后续用例。
5.2 在Jest中接入MSW
把MSW引入测试后，写组件测试变得极度舒适。比如测试一个"获取用户信息并渲染"的组件，以前我得mock api模块，现在只需要这样：
javascript复制import { render, screen, waitFor } from '@testing-library/react'
import UserProfile from './UserProfile'
test('渲染用户信息', async () => {
render(<UserProfile userId={1} />)
// 因为mock handler已经返回了用户数据，这里直接等待渲染结果
await screen.findByText('张三')
expect(screen.getByText('zhangsan@example.com')).toBeInTheDocument()
})
如果某个测试需要覆盖异常场景，可以直接在测试文件里追加handler：
javascript复制import { http, HttpResponse } from 'msw'
import { server } from '../src/mocks/server'
test('接口500时显示错误提示', async () => {
server.use(
http.get('/api/user/1', () => {
return HttpResponse.json(
{ message: '服务器异常' },
{ status: 500 }
)
})
)
render(<UserProfile userId={1} />)
await screen.findByText('服务器异常')
})
这种写法让我体会到MSW在测试领域真正的价值：开发时写好的mock数据和测试用例共享同一套机制，团队不用再维护"两套mock"。而且由于所有请求都是真实发出的，组件里的fetch、axios、甚至第三方SDK的请求都能被覆盖，测试的覆盖率和可信度都高很多。
6. 实战问题速查：那些年我踩过的坑
6.1 worker启动失败与静态资源路径
最常遇到的问题就是worker.start()控制台报错。最常见的罪魁祸首是mockServiceWorker.js没有放到正确的静态资源目录下。这个脚本必须能被浏览器以根路径/mockServiceWorker.js访问到，如果项目public目录配置不对，或者中间层改写了静态资源映射，就会注册失败。
经验是：启动时打开Network面板，直接访问/mockServiceWorker.js，看能否拿到200和正确的js内容。拿不到就检查文件位置和项目静态资源配置。如果是Next.js这类带服务端渲染的框架，还要注意只在客户端注册worker，不要影响SSR的Node进程。
另一个隐蔽问题是：Service Worker有作用域限制。如果worker文件放在子目录，它只能拦截该目录下的请求。这也是为什么官方都建议放在public根目录，原因就是确保service worker作用域覆盖整个站点。
6.2 请求没拦到？先查这三件事
遇到"请求没被拦截"的灵异事件，我一般按顺序排查：
第一，检查handler路径是否精确匹配。MSW的路径匹配是精确匹配（除了通配符），/api/user不会匹配/api/user/，/api/user/1不会匹配/api/user/:id对应的严格模式。如果你请求里带了query参数，比如/api/user?page=1，那在handler里应该用/api/user来匹配，query参数不影响匹配结果，但路径本身必须一致。
第二，检查请求是否走了Service Worker。如果页面地址是http://localhost:3000，但请求发到了http://other-domain.com，跨域请求也要看你的mock规则是否覆盖了该域名。默认情况下MSW可以拦截跨域请求，但需要确认handler里的URL是否包含完整域名。比如http.get('https://api.example.com/user', ...)这种写法，才能拦截到跨域API。
第三，检查worker是否处于激活状态。开发者工具Application面板的Service Workers标签页里，看mockServiceWorker.js有没有被激活。有时候旧版本的worker缓存会导致更新不及时，在Application面板里勾选"Update on reload"，或者直接Clear storage刷新一次，能够解决大部分"改了handler没生效"的问题。
6.3 与开发代理的冲突处理
在Vite、Webpack里，很多项目都配置了devServer代理，把/api开头的请求转发到后端地址。这就可能导致一个冲突：代理先于Service Worker拦截了请求，或者反过来，请求被Service Worker拦截后，代理的配置实际没产生作用。
我项目的处理方式是：开启mock时，临时取消代理配置，或者调整优先级。比如Vite配置里用环境变量来控制是否启用代理：
javascript复制// vite.config.js
export default defineConfig({
server: {
proxy: process.env.VITE_ENABLE_MOCK === 'true' ? {} : {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
},
},
},
})
这样一来，开启mock时请求完全走MSW的Service Worker，不经过代理；关闭mock时走真实代理，互不干扰。在纯前端环境（比如用vite preview构建产物预览）跑mock时，因为没有devServer代理，也要确保mock handler覆盖了所有需要拦截的API路径。
MSW这个库，我用下来的整体感受是：它把"mock"这件事提升到了一个更接近真实网络的位置，比传统的mockjs、axios拦截器方案都要先进。虽然最开始上手时，Service Worker的概念可能让你觉得有点绕，但只要理解了"请求被网络层拦截、而不是代码层拦截"这个核心思路，再看它的API设计就会非常顺畅。最关键的是，同一套handler可以从开发环境带到测试环境，这确实是实实在在省下了很多维护成本。如果你还没在项目里试过MSW，找个老项目或者新项目的空闲时间，花半小时跑一下demo，应该很快能感受到它的好用。