使用keycloak-js15.0.1对接Keycloak15的React应用提示window未定义错误

架构老林

2026-10-7

错误根因

这个报错的核心原因是你的React应用启用了服务端渲染（SSR），Node.js服务端运行环境不存在浏览器专属的window全局对象，而keycloak-js@15.0.1本身是纯客户端SDK，代码底层直接依赖window对象完成初始化，服务端侧直接导入执行就会触发该错误。

解决方案

方案1：仅在客户端侧导入初始化keycloak-js（最推荐）
避开服务端渲染阶段加载该SDK，仅在浏览器端执行的生命周期中动态导入：

// React 函数组件示例
import { useEffect, useState } from 'react'

function App() {
  const [keycloak, setKeycloak] = useState(null)

  useEffect(() => {
    // 仅客户端会执行useEffect回调
    const init = async () => {
      const Keycloak = (await import('keycloak-js')).default
      const instance = new Keycloak({
        url: '你的keycloak地址',
        realm: '你的realm',
        clientId: '你的clientId'
      })
      await instance.init({ onLoad: 'check-sso' })
      setKeycloak(instance)
    }
    init()
  }, [])

  // 未初始化完成前可以加载loading态
  if (!keycloak) return <div>加载中...</div>
  return <div>你的应用内容</div>
}

如果你用的是Next.js框架，也可以使用dynamic导入直接关闭组件的服务端渲染：

import dynamic from 'next/dynamic'
const KeycloakProvider = dynamic(() => import('../components/KeycloakProvider'), {
  ssr: false,
  loading: () => <div>加载中...</div>
})

方案2：服务端逻辑改用服务端适配包
如果你需要在服务端完成Keycloak相关的鉴权、接口调用逻辑，不要使用keycloak-js，改用Keycloak官方提供的服务端SDK，例如Node.js环境可以使用@keycloak/keycloak-admin-client。
方案3：服务端模拟window对象（临时调试用，不推荐）
可以在服务端入口文件最顶部添加模拟代码，提前给全局注入空的window对象避免导入报错，但是该方案可能引发后续其他浏览器API调用异常，仅适合临时排查问题：
```
// server-build/index.js 最顶部添加
if (typeof window === 'undefined') {
  global.window = {}
}
```