Nuxt3 SSR插件调用报500错误：$setup.$hello不是函数求助

我是Nuxt新手，正在学习SSR（服务端渲染）与CSR（客户端渲染）中的插件用法。按官方文档的HelloWorld示例测试时，CSR环境下（使用/plugins/hello.ts或/plugins/hello.client.ts）插件可正常运行；但SSR环境下（使用/plugins/hello.server.ts）发起请求会返回500错误，提示信息为[GET] 500 $setup.$hello is not a function。

相关代码 #

插件文件（plugins/hello.(client/server/).ts） #

export default defineNuxtPlugin(() => {
    return {
      provide: {
        hello: (msg: string) => `Hello ${msg}!`
      }
    }
  })

页面文件（pages/hello.vue） #

<script setup lang="ts">
const { $hello } = useNuxtApp()
</script>

<template>
  <div>
    {{ $hello('world') }}
  </div>
</template>

错误原因解析 #

这个错误的核心原因是服务端插件仅在服务端注入方法，但页面模板会在客户端水合阶段尝试调用该方法，而客户端实例中不存在这个方法。

具体细节：

• 命名为hello.server.ts的插件只会在Nuxt服务端生命周期中执行，仅向服务端的NuxtApp实例注入$hello方法，客户端的NuxtApp实例不会包含这个方法。
• 页面在SSR阶段会先在服务端渲染出HTML，此时服务端能正常调用$hello生成内容；但当页面发送到客户端后，Vue会进行水合操作，此时客户端的Vue实例尝试执行模板中的$hello('world')，但客户端并没有这个方法，最终触发500错误。

如果需要让插件仅在服务端可用，需确保调用$hello的逻辑只在服务端执行，比如放在serverPrefetch钩子或服务端专属代码块中；如果需要客户端也能调用该方法，不要使用.server.ts后缀，改用通用插件hello.ts，或者同时创建.client.ts和.server.ts版本分别处理两端逻辑。

参考文档 #

Nuxt官方插件目录结构指南

内容的提问来源于stack exchange，提问作者Wasabi-sudo