Next.js + TestCafe配置e2e测试时遇window未定义错误的解决咨询

你最初判断「测试脚本被在服务端执行」属于认知偏差：实际是被测Next.js应用在服务端渲染流程中直接访问了仅存在于浏览器环境的window全局对象，渲染阶段抛出的未捕获异常被TestCafe内置的JS错误检测机制拦截，最终触发测试流程中断。

核心解决路径 #

根源修复：从Next.js代码层面规避SSR阶段的window访问 #

这类方案是真正解决问题的手段，可避免把潜在的渲染问题带到生产环境，不建议长期依赖跳过错误的方式跑测试：

• 所有可能在服务端执行的代码块，访问window前必须做环境判断，禁止裸写浏览器全局对象

  // 错误写法：SSR执行到这一行会直接抛出ReferenceError
  const storedTheme = window.localStorage.getItem('theme')
  
  // 正确写法：先校验当前运行环境是否存在window
  const storedTheme = typeof window !== 'undefined'
    ? window.localStorage.getItem('theme')
    : null
  

• 对于强依赖window的第三方组件（比如图表库、富文本编辑器、浏览器专属SDK），不要在页面初始渲染阶段直接引入，改用Next.js内置的动态导入能力，标记为仅浏览器端加载

  import dynamic from 'next/dynamic'
  
  // 跳过SSR渲染环节，让组件仅在浏览器端加载执行
  const ChartComponent = dynamic(
    () => import('@/components/echarts-chart'),
    { ssr: false }
  )
  

TestCafe配置的临时兜底方案 #

这类方案仅适合临时快速跑通测试流程，不能替代代码本身的SSR问题修复：

• 如果需要临时跳过这类已知的环境报错，可在TestCafe启动命令中添加--skip-js-errors参数，TestCafe将不再把应用抛出的JS错误作为测试失败的判定依据

  # 示例启动命令
  testcafe chrome ./e2e/**/*.spec.js --skip-js-errors
  

• 测试启动前必须先完成Next.js应用的生产构建、启动服务到可访问端口，不要在开发模式的编译、热更新过程中触发TestCafe测试，否则很容易把编译阶段的临时报错误判为应用运行异常。

内容的提问来源于stack exchange，提问作者Tércio Garcia