start()

注册 Service Worker 并启动请求拦截。

调用签名

¥Call signature

worker.start() 方法接受可选的 选项 对象，你可以使用该对象自定义工作者注册。

¥The worker.start() method accepts an optional Options object that you can use to customize the worker registration.

默认情况下，当不带任何参数调用时，worker.start() 方法会注册在 ./mockServiceWorker.js 下提供服务的 Service Worker 并启动请求拦截。

¥By default, when called without any arguments, the worker.start() method registers the Service Worker served under ./mockServiceWorker.js and starts the request interception.

import { setupWorker } from 'msw/browser'
import { handlers } from './handlers'
 
const worker = setupWorker(...handlers)
await worker.start() // Promise<{ pending }>

当 MSW 处于活动状态时，你可以在浏览器的控制台中看到打印的确认消息。

¥You can see a confirmation message printed in the browser’s console when MSW is active.

[MSW] Mocking enabled.

选项

¥Options

serviceWorker

url

  • 字符串，默认值："/mockServiceWorker.js"

    ¥String, default: "/mockServiceWorker.js"

自定义服务工作者注册 URL。如果你在自定义路径下提供工作脚本，请使用此选项。

¥Custom Service Worker registration URL. Use this option if you are serving the worker script under a custom path.

worker.start({
  serviceWorker: {
    url: '/assets/mockServiceWorker.js',
  },
})

options

这些选项会修改 Service Worker 注册本身，与 MSW 不直接相关。

¥These options modify the Service Worker registration itself and are not related to MSW directly.

worker.start({
  serviceWorker: {
    options: {
      // Narrow down the scope of the pages that the worker can control.
      scope: '/product',
    },
  },
})

findWorker

  • 函数，预期返回类型：布尔值

    ¥Function, expected return type: Boolean

用于在服务器上定位工作脚本的自定义函数。如果你的应用在代理后面运行或具有动态主机名，则可能需要使用此选项，否则会阻止库在 <HOSTNAME>/mockServiceWorker.js 处定位工作脚本。

¥A custom function to locate the worker script on the server. You may want to use this option if your application runs behind a proxy or has a dynamic hostname that otherwise prevents the library from locating the worker script at <HOSTNAME>/mockServiceWorker.js.

worker.start({
  findWorker(scriptUrl, mockServiceWorkerUrl) {
    return scriptUrl.includes('mockServiceWorker')
  },
})

quiet

  • 布尔值，默认值：false

    ¥Boolean, default: false

禁用库中的所有日志记录（例如激活消息、拦截的请求的消息）。

¥Disables all the logging from the library (e.g. the activation message, the intercepted requests’ messages).

worker.start({
  quiet: true,
})

onUnhandledRequest

  • 字符串，默认值："warn"

    ¥String, default: "warn"

  • 函数

    ¥Function

决定如何对未处理的请求（即没有匹配的请求处理程序的请求）做出反应。

¥Decide how to react to unhandled requests (i.e. those that do not have a matching request handler).

标准模式

¥Standard modes

处理方式描述
warn（默认）向浏览器的控制台打印警告消息，按原样执行请求。
error抛出错误，中止请求。
bypass不打印任何内容，按原样执行请求。

自定义 onUnhandledRequest 函数

¥Custom onUnhandledRequest function

worker.start({
  onUnhandledRequest(request, print) {
    // Ignore any requests containing "cdn.com" in their URL.
    if (request.url.includes('cdn.com')) {
      return
    }
 
    // Otherwise, print an unhandled request warning.
    print.warning()
  },
})

waitUntilReady

  • 布尔值，默认值：true

    ¥Boolean, default: true

推迟在 Service Worker 注册期间发生的任何应用请求。

¥Defers any application requests that happen during the Service Worker registration.