PWA项目部署到Vercel后生产构建无service-worker.js文件如何解决

核心产生原因 #

• 构建环境变量配置不一致：绝大多数Workbox+Webpack的PWA配置都会设置仅在生产环境下生成Service Worker文件。如果Vercel构建时未指定NODE_ENV=production，或者项目的构建脚本没有绑定生产模式，Workbox插件不会触发service-worker.js的生成逻辑；本地执行生产构建时默认走生产环境，因此可以正常生成文件。
• Vercel构建输出配置错误：如果Vercel项目设置中的Output Directory参数不是Webpack配置的dist目录，或者填写了错误的子路径，会导致部署时仅同步部分符合路径的产物，manifest.json刚好匹配到路径就会正常存在，而service-worker.js在正确的dist目录未被同步。
• Workbox输出路径配置异常：如果Webpack配置中Workbox插件的swDest参数填写了绝对路径，或者相对dist目录之外的路径，本地环境有权限写入对应路径，而Vercel构建沙箱的文件写入权限受限，会导致service-worker.js生成失败。
• 依赖安装范围问题：如果workbox-webpack-plugin被放在devDependencies中，Vercel默认构建时会跳过安装开发依赖，导致Webpack构建时找不到对应插件，直接跳过Service Worker生成逻辑。
• 构建产物清理逻辑冲突：如果项目中配置了clean-webpack-plugin等构建后清理插件，插件执行时机晚于Workbox生成sw文件的时机，就会把生成的service-worker.js误删，本地和Vercel的Node版本、插件执行顺序差异可能会导致仅在Vercel环境触发该问题。

对应解决方案 #

• 修正package.json的构建脚本，显式指定生产环境，示例配置："build": "NODE_ENV=production webpack --mode production"
• 检查Vercel项目的构建配置：确认Build Command填写为你的生产构建命令（如npm run build），Output Directory填写为dist即可，不要添加额外前缀或后缀。
• 调整Webpack中的Workbox配置，swDest仅填写文件名或相对dist目录的路径，示例配置：swDest: 'service-worker.js'，不要使用绝对路径。
• 将workbox-webpack-plugin移到dependencies依赖中，或者在Vercel环境变量中添加NPM_PRODUCTION=false，关闭Vercel的开发依赖跳过安装逻辑。
• 调整clean-webpack-plugin的执行时机，或者配置exclude规则忽略service-worker.js，避免生成后被误删。

内容的提问来源于stack exchange，提问作者Mihail Fjodorov