MSW在CRA项目中设置homepage时请求拦截失效的解决方案

问题背景

在使用Create React App(CRA)项目时，当开发者在package.json中设置了"homepage"属性后，Mock Service Worker(MSW)会出现无法正常拦截请求的情况。这是一个常见但容易被忽视的配置问题，特别是在需要部署到子路径的生产环境中。

问题现象

开发者报告了以下典型现象：

1. 在未设置homepage时，MSW能够正常拦截/api/code/NAT/1这样的请求
2. 一旦在package.json中添加"homepage": "myPage"配置后：
   • 浏览器控制台显示MSW已启用("Mocking enabled")
   • 但实际请求返回404错误(Cannot POST /myPage/api/code/NAT/1)
   • 请求监听器(request:start事件)不再触发

问题分析

通过调试发现，问题的核心在于Service Worker的注册路径处理。当设置homepage后，CRA会自动将所有静态资源路径加上此前缀，但MSW的默认配置未能自动适应这种变化。

关键点在于：

1. MSW的mockServiceWorker.js文件默认预期在根路径下
2. 设置homepage后，实际路径变为/myPage/mockServiceWorker.js
3. 如果不显式配置serviceWorker.url参数，会导致Service Worker注册失败

解决方案

经过验证，有以下两种解决方案：

方案一：显式配置serviceWorker.url

await worker.start({
  serviceWorker: {
    url: `mockServiceWorker.js`, // 相对路径即可
  },
});

这种方案最为简洁有效，它明确告诉MSW使用相对于当前页面的路径来加载Service Worker脚本。

方案二：动态读取homepage配置

const packageJson = await import("../package.json");
await worker.start({
  serviceWorker: {
    url: `${packageJson.homepage}/mockServiceWorker.js`,
  },
});

这种方案动态读取package.json中的homepage配置，理论上更加灵活，但在实际测试中效果不如方案一稳定。

最佳实践建议

1. 始终等待worker.start()完成：确保使用await或.then()等待Service Worker完全注册
2. 开发环境检查：仅在开发环境启用Mock
3. 路径处理：优先使用相对路径而非绝对路径
4. 错误处理：添加适当的错误处理逻辑

技术原理深入

MSW的核心工作原理是通过Service Worker拦截网络请求。当设置homepage后，整个应用的URL结构发生变化：

1. 基础路径从/变为/myPage/
2. 所有相对路径的解析都基于这个新基础路径
3. 如果Service Worker注册路径不正确，就无法建立正确的拦截范围

方案一之所以有效，是因为相对路径mockServiceWorker.js会自动适应当前页面的基础路径，无论homepage如何设置都能正确解析。

总结

在CRA项目中使用MSW时，如果遇到homepage设置导致请求拦截失效的问题，最简单的解决方案是在worker.start()中明确指定serviceWorker.url为相对路径mockServiceWorker.js。这确保了Service Worker能在各种部署环境下正确注册和运行。理解这一机制有助于开发者更好地处理前端Mock在不同环境中的一致性问题。