NUXT 3中UseRuntimeConfig未定义问题（NX monorepo环境）

问题描述 #

按照Nuxt官方文档要求，在defineNuxtConfig内配置runtimeConfig来管理环境变量，但在NX monorepo（搭配@nx/nuxt）中运行时出现**"useRuntimeConfig is not defined"**错误。已尝试重新安装依赖、升级TypeScript，但问题未解决。

核心依赖版本：

{
  "devDependencies": {
    "@nx/nuxt": "18.0.4",
    "nuxt": "^3.10.0",
    "nx": "18.0.4",
    "typescript": "~5.3.2"
  }
}

可行解决方案 #

1. 确认useRuntimeConfig的调用上下文 #

useRuntimeConfig是Nuxt的组合式API函数，不能直接在nuxt.config.ts的配置对象中调用，仅能在以下场景使用：

• Nuxt页面/组件的<script setup>或setup()函数内
• Nuxt插件（plugins目录文件）
• Nuxt服务器路由（server/api目录文件）

如果是在nuxt.config.ts中配置环境变量，直接通过runtimeConfig字段声明即可：

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 仅服务器端可访问的私有变量
    apiSecret: process.env.NUXT_API_SECRET,
    // 客户端/服务器端均可访问的公开变量
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE
    }
  }
})

2. 校验NX monorepo的项目配置 #

确保Nuxt子项目的nuxt.config.ts位于正确目录，且NX的project.json中已正确关联该配置文件，避免NX未识别到Nuxt的配置上下文。

3. 修复TypeScript类型识别问题 #

在Nuxt子项目的tsconfig.json中显式添加Nuxt类型引用，让TypeScript识别全局API：

{
  "extends": "./.nuxt/tsconfig.json",
  "compilerOptions": {
    "types": ["nuxt"]
  }
}

4. 对齐NX与Nuxt的版本兼容性 #

当前@nx/nuxt@18.0.4与nuxt@3.10.0可能存在版本适配问题，尝试：

• 将@nx/nuxt和nx升级到匹配Nuxt 3.10的最新稳定版
• 或回退Nuxt版本到NX官方支持的范围

5. 清除缓存后重新构建 #

执行命令清除NX和Nuxt的缓存：

nx reset
npx nuxt clean

再启动开发服务器：

nx serve <你的Nuxt子项目名称>

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