Nuxt 3 SSR未正常启用：process.server始终返回false

问题情况 #

• 无法获取私有环境变量，已知仅在SSR模式下能访问私有环境变量
• 全局配置ssr: true，但页面中执行console.log(process.server)一直返回false
• 已在routeRules里对/portal/**和/checkout/**禁用SSR，但测试页面不在这些路由范围内

用户提供的nuxt.config.ts配置：

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
    ssr: true,
    routeRules: {
        '/portal/**': { ssr: false },
        '/checkout/**': { ssr: false }
    },
    runtimeConfig: {
        stripeKey: '',
        public: {
            API_BASE_URL: process.env.API_BASE_URL || "http://192.168.1.100:8000/api",
        }
    },
    modules: [
        '@nuxtjs/i18n',
        '@pinia/nuxt',
    ],
    css: [
        '@/assets/css/main.css',
        '@/assets/css/colors.scss',
        'vuetify/lib/styles/main.sass',
        'primevue/resources/themes/lara-light-blue/theme.css',
        'primevue/resources/primevue.css',
        'primeicons/primeicons.css',
        '@fortawesome/fontawesome-svg-core/styles.css'
    ],
    build: {
        transpile: [
            'primevue',
            'vuetify'
        ]
    },
    postcss: {
        plugins: {
            tailwindcss: {},
            autoprefixer: {},
        },
    },
    app: {
        head: {
            script: [{ src: "https://js.stripe.com/v3/" }],
            title: '',
            meta: [
                {
                    name: 'color-scheme',
                    content: 'only light'
                }
            ],
            link: [
                {
                    href: 'https://fonts.googleapis.com/css?family=Material+Icons|Material+Icons+Outlined',
                    rel: 'stylesheet',
                }
            ]
        }
    },
    i18n: {
        lazy: true,
        langDir: "locales",
        strategy: "no_prefix",
        locales: [
            {
                code: 'en',
                iso: 'en',
                name: 'English',
                file: 'en.json'
            },
            {
                code: 'nl-Nl',
                iso: 'nl-NL',
                name: 'Dutch',
                file: 'nl-NL.json'
            }
        ]
    }
})

排查与解决方法 #

1. 确认当前路由未被禁用SSR #

先确认你测试的页面不在/portal/**或/checkout/**路由下，如果属于这两个路由，客户端渲染模式下process.server返回false是正常行为。

2. 正确获取私有环境变量 #

私有环境变量（比如stripeKey）不能直接在客户端代码中访问，必须通过服务端上下文获取：

• 在页面组件中，结合服务端逻辑读取：

<script setup>
const config = useRuntimeConfig()

// 仅在服务端执行的代码块
if (process.server) {
  console.log('私有Stripe密钥:', config.stripeKey)
}
</script>

• 或者通过服务器API路由中转：
  在server/api/stripe-key.ts中编写：

export default defineEventHandler(() => {
  const config = useRuntimeConfig()
  return { stripeKey: config.stripeKey }
})

然后在客户端通过useFetch调用这个API获取变量。

3. 验证SSR模式是否真的启用 #

• 启动项目时看终端，全SSR模式会显示Nuxt Server相关启动信息，若显示Nuxt Client则说明SSR未启用
• 查看页面源码：SSR渲染的页面会包含组件渲染后的实际内容；客户端渲染的页面只有空的根容器标签

4. 检查页面级SSR配置 #

确认测试页面的组件中没有单独设置禁用SSR：

<script setup>
// 若存在此配置会覆盖全局SSR设置
definePageMeta({
  ssr: false
})
</script>

5. 清理缓存重启项目 #

缓存可能导致配置不生效，尝试：

• 删除.nuxt目录和node_modules/.cache文件夹
• 重新启动开发服务器

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