Nuxt 3组合式函数修改后触发ReferenceError问题求助

问题场景 #

通过npx nuxi init <project-name>创建Nuxt 3项目（覆盖3.0.0至3.3.3多个版本），在composables目录下编写useBoxPlot组合式函数，首次启动yarn dev运行正常，但修改该函数代码触发热更新后，控制台抛出错误：

Uncaught (in promise) ReferenceError: useData is not defined at app.vue:25:1

必须手动终止并重启服务器才能恢复正常。

排查与解决步骤 #

• 检查useBoxPlot的依赖关系
  确认useBoxPlot内部是否直接或间接调用了useData但未正确导入：

  • 若useData是自定义组合式函数，确保它放置在composables目录下，且使用export const useData或export default useData的方式导出，符合Nuxt自动导入规则；
  • 排查是否存在嵌套组合式函数的依赖遗漏，比如某个被useBoxPlot调用的函数内部依赖useData但未导出。

• 禁用自动导入，手动导入测试
  在nuxt.config.ts中配置排除useBoxPlot的自动导入：

  export default defineNuxtConfig({
    imports: {
      exclude: ['useBoxPlot']
    }
  })
  

  之后在app.vue中手动导入useBoxPlot：

  <script setup>
  import { useBoxPlot } from '~/composables/useBoxPlot'
  // ... 其他代码
  </script>
  

  修改useBoxPlot代码后观察热更新是否正常，以此排查自动导入机制的异常。

• 清理Nuxt缓存

  • 执行yarn nuxt clean清理项目缓存，再重启开发服务器；
  • 也可手动删除.nuxt目录和node_modules/.cache目录，重新执行yarn install后启动服务，排除缓存导致的依赖解析错乱。

• 检查组合式函数代码结构

  • 避免在useBoxPlot内部使用动态导入或未处理的异步逻辑，这类代码可能干扰热更新的依赖追踪；
  • 确保函数内没有修改全局变量或共享状态的操作，防止热更新时状态污染。

• 升级Nuxt版本
  尝试将Nuxt升级至3.4及以上的稳定版本，后续版本可能修复了组合式函数热更新时的依赖解析bug。

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