MSW在Vite 5.x中base路径配置问题的解决方案

问题背景

在使用MSW（Mock Service Worker）进行前端API模拟时，当项目基于Vite 5.x构建并配置了base路径时，可能会遇到Service Worker加载失败的问题。具体表现为浏览器控制台报错404，无法找到mockServiceWorker.js文件。

问题原因

Vite 5.x版本对开发服务器和预览环境的HTML服务行为进行了对齐调整。当在vite.config.ts中设置了base路径（如'/my-app/'）时，所有静态资源的请求路径都会基于这个base路径。然而，MSW默认生成的Service Worker注册路径没有考虑这个base配置，仍然尝试从根路径加载mockServiceWorker.js文件。

解决方案

方案一：显式指定Service Worker URL

在启动MSW worker时，可以通过serviceWorker.url参数显式指定正确的路径：

if (import.meta.env.DEV) {
  const { worker } = await import("./mocks/browser");
  await worker.start({
    serviceWorker: {
      url: `${import.meta.env.BASE_URL}/mockServiceWorker.js`,
    },
  });
}

这种方法利用了Vite提供的环境变量import.meta.env.BASE_URL，它会自动获取vite.config.ts中配置的base路径。

方案二：通过package.json配置

另一种方法是在package.json中设置homepage字段，然后在启动worker时引用这个值：

import packageJson from '../package.json'

if (process.env.NODE_ENV === 'development') {
  const { worker } = await import('./mocks/browser')
  
  await worker.start({
    serviceWorker: {
      url: `${packageJson.homepage}/mockServiceWorker.js`,
    },
  })
}

技术原理

Service Worker的注册路径必须与实际文件位置完全匹配。在Vite项目中，当配置了base路径后，所有静态资源都会被重新定位到base路径下。MSW默认生成的mockServiceWorker.js文件也会被放置在这个路径下，但Service Worker的注册逻辑没有自动适应这个变化。

通过显式指定url参数，我们确保了Service Worker的注册路径与实际文件位置一致，解决了404错误问题。

最佳实践

1. 对于Vite项目，推荐使用import.meta.env.BASE_URL方案，因为它直接与Vite配置同步
2. 确保mockServiceWorker.js文件被正确复制到构建输出目录
3. 在开发和生产环境使用相同的base路径配置，避免环境差异
4. 如果项目需要部署到不同路径下，考虑使用环境变量来动态设置base路径

总结

Vite 5.x的base路径配置是一个有用的功能，但在与MSW结合使用时需要特别注意Service Worker的注册路径问题。通过本文介绍的两种解决方案，开发者可以轻松解决路径不匹配的问题，确保API模拟功能在各种部署环境下正常工作。