Nuxt报Invalid value used as weak map key错误如何排查解决

• 本地执行npm run dev启动Nuxt项目时，控制台抛出Invalid value used as weak map key报错，对应报错截图：
  
• 本地开发环境触发该报错时存在容错机制，项目仍可正常运行，但部署到生产环境后会直接出现运行/构建异常，无法正常提供服务，生产环境报错截图：
  

JS原生WeakMap结构仅支持对象类型作为键名，当代码尝试将字符串、数字、布尔值、null、undefined这类非对象类型作为键传入WeakMap时就会触发该报错。
Nuxt项目中该报错的高频触发场景：

• 服务端渲染阶段直接访问仅浏览器端存在的window、document等对象，拿到undefined值后传入了Nuxt内置的上下文、响应式、缓存类API（这类API内部依赖WeakMap做存储）
• 调用definePageMeta、useState、useNuxtApp().provide、自定义组件缓存配置等API时，给要求对象格式的配置项/参数传入了原始类型值
• 项目使用的Nuxt版本与第三方Nuxt模块版本不兼容，模块内部调用Nuxt内部API时传参不符合版本要求
• 给<NuxtPage>内置组件的pageKey属性直接传入了原始类型的路由参数、查询值，没有做合法格式包装

本地开发环境不会直接崩溃是因为dev模式下有HMR热更新容错、部分逻辑仅在客户端执行，不会触发服务端的校验逻辑；生产构建会做全量的服务端预渲染、静态优化、代码压缩校验，遇到非法传参就会直接抛出异常中断流程或者导致线上运行错误。

按以下步骤逐一排查修复：

1. 定位报错具体位置
   执行带debug参数的构建命令，根据报错栈定位到触发问题的具体代码行：

   npm run build --debug
   

2. 修复非法传参问题
   • 所有访问浏览器端API的逻辑，必须包裹在process.client判断或者onMounted生命周期内执行，避免服务端渲染阶段拿到undefined传入内置API
   • 检查所有definePageMeta配置，确保key、middleware、layout等字段赋值符合官方类型要求，禁止给对象类型配置项传原始值
   • 检查useState、全局provide/inject的传参，原始类型值需要包装为ref/reactive响应式对象后再传入
   • 检查<NuxtPage>组件的pageKey属性，若传动态值需返回合法格式，禁止直接传入原始类型的路由参数，示例正确写法：

     <template>
       <NuxtPage :page-key="route => ({ params: route.params })" />
     </template>
     

   • 检查nitro.routeRules中的缓存配置，确保缓存键配置为合法对象格式，不要直接传字符串作为缓存键
3. 修复版本兼容问题
   升级Nuxt到最新稳定版，同时升级所有第三方Nuxt模块到适配当前Nuxt版本的版本，删除依赖缓存后重新安装：

   npx nuxi upgrade --force
   # 根据自己使用的包管理器删除对应锁文件和缓存目录
   rm -rf node_modules package-lock.json pnpm-lock.yaml yarn.lock .nuxt .output
   npm install
   

内容的提问来源于stack exchange，提问作者Amine EL GHAZALI