本技能提供 Mock Service Worker（MSW）v3 的规则与官方最佳实践，适用于在用 MSW 编写或修改代码之前查阅。MSW 3.0 于 2026-09-28 发布，许多 v2 的写法在 v3 中会无法编译或行为不同，因此第一步是确认安装版本，例如用 node -p "require('./node_modules/msw/package.json').version" 检查；若为 3.x 则按本资料执行。对 API 不确定时应阅读 node_modules/msw/lib/**/*.d.ts 中的类型定义，而非猜测。
主要变更与能力。GraphQL 改从 msw/graphql 导入，并需使用 graphql.link(url) 后再调用 query/mutation，不再提供顶层 graphql.query/graphql.mutation；v3 新增 api.subscription，api.operation 可匹配任意操作。监听与启动选项由 onUnhandledRequest 改为 onUnhandledFrame，server.listen() 与 worker.start() 均如此，其值可为 'bypass'、'warn'、'error' 或回调 ({ frame, defaults }) => …，回调中 defaults.error() 仅打印而不使请求失败。服务器级事件由 'connection' 改名为 'websocket:connection'，回调参数中的 url 是 URL 对象；worker.stop() 返回 Promise，需 await。MSW 不再绕过假定时器，使用 delay() 时需在测试中推进定时器，如 await vi.advanceTimersByTimeAsync(ms)。读取 cookie 改用解析器参数 ({ cookies }) => cookies.session。包仅支持 ESM，要求 Node ≥ 22.12、TypeScript ≥ 5.9；移除了 handleRequest() 与 msw/native，改用 msw/experimental 的 defineNetwork() 或 @msw/react-native。ws.link(url).addEventListener('connection', …) 的用法不变。
导入方式。从 msw 导入 http、HttpResponse、delay、passthrough、bypass、ws、sse；从 msw/graphql 导入 graphql；Node 测试（Vitest、Jest）用 msw/node 的 setupServer；浏览器用 msw/browser 的 setupWorker。
使用范式。HTTP 处理器示例包括按路径参数返回 JSON、读取请求体创建资源、用 HttpResponse.error() 模拟网络错误、用 new HttpResponse(null, { status: 503 }) 加 { once: true } 模拟一次性失败。GraphQL 通过 graphql.link 定义 api 后编写 query、mutation 处理器。Vitest 中在 setup 文件里用 beforeAll 启动 server.listen({ onUnhandledFrame: 'error' })，afterEach 调用 server.resetHandlers() 清除 server.use() 覆盖，afterAll 调用 server.close()。单个测试可用 server.use(http.get(…)) 覆盖处理器。
生命周期事件。HTTP 事件有 request:start、request:match、request:unhandled、request:end、response:mocked、response:bypass；WebSocket 事件有 websocket:connection、websocket:error。可用于记录未处理请求或收集连接 URL。
WebSocket 与 Vite。用 ws.link('wss://…') 并监听 connection，在 client 上监听 message 并 send 回显。v3 新增 Vite 开发服务器集成：在插件中加入 msw/vite 的 msw()，并在应用入口按 import.meta.env.DEV 条件动态导入 virtual:msw 与处理器，调用 network.configure({ handlers }) 和 await network.enable()。
最佳实践。共享处理器描述成功路径，错误、空状态与慢响应在需要它们的测试中通过 server.use() 注入，并配合 afterEach 重置处理器，不要给共享处理器加“错误模式”开关。不要在处理器内做请求断言，如 spy、捕获请求体或检查是否被调用，而应让处理器像真实 API 一样校验请求并在错误时返回 400 等错误，再断言被测代码的返回值或渲染结果；生命周期事件仅用于分析等无可见效果的单向请求。用泛型而非类型断言标注处理器，如 http.post<Params, RequestBody, ResponseBody> 和 api.query<Query, Variables>。大型 API 按领域拆分处理器文件并统一组合。重复逻辑用高阶解析器封装，例如 withAuth。演示与本地开发可用场景映射：将所选场景的覆盖处理器放在基础处理器之前，因为最左侧处理器优先。浏览器 worker 用 npx msw init public --save 生成，--save 会在 package.json 记录 msw.workerDirectory 以便升级时重新生成，public/mockServiceWorker.js 应提交到仓库，不要手写或复制。测试中应让未知流量失败。server.close() 只能调用一次，v3 对已关闭的服务器再次 close 会抛出 "already disabled"。
完成前应运行项目类型检查 npx tsc --noEmit，并用 vitest run 运行改动过的测试而非 watch 模式。更多前后对比例子见 references/v2-to-v3.md。资料未提供收费、价格等信息。