React/Next.js+TypeScript中visualViewport的Object is possibly 'null'错误解决

1. 修正全局类型定义文件 #

你的全局声明文件需要被TypeScript识别为模块，否则无法正确覆盖原有类型。修改你的.d.ts文件，添加模块标记：

declare global {
  interface Window {
    visualViewport: VisualViewport;
  }
}

// 标记为模块，确保全局类型扩展生效
export {};

将文件放在项目类型定义目录（如src/types/）下，推荐命名为window-extension.d.ts以避免命名冲突。

2. 配置tsconfig.json识别类型文件 #

检查tsconfig.json的配置，确保TypeScript能加载自定义类型：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "lib": ["DOM", "ESNext"], // 必须包含DOM，确保基础DOM类型可用
    "strict": true
  },
  "include": ["src/**/*", "./src/types/*.d.ts"]
}

3. 非空断言操作符（快速应急方案） #

如果上述配置仍未生效，可直接用TypeScript非空断言操作符!，明确告知编译器visualViewport不会为null：

const viewportScale = window.visualViewport!.scale;

或使用类型断言：

const viewportScale = (window.visualViewport as VisualViewport).scale;

注意：使用前需确认运行环境支持visualViewport（多数现代移动端浏览器及部分桌面浏览器已支持）。

4. 验证类型生效 #

重启TypeScript语言服务（或编辑器）清除缓存，再检查代码是否仍存在Object is possibly 'null'错误。

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