如何在NextJS应用中正确声明全局可用类型

云上老周

2026-8-28

NextJS 全局类型声明正确实现方案

问题根因

之前的写法存在两处核心错误：

type React from "react"属于非法语法，type关键字仅用于定义类型别名，无法实现模块类型的全局挂载
未使用declare global块做全局命名空间挂载，若.d.ts文件存在顶级导入/导出语句，会被识别为模块文件而非全局声明文件，内部声明不会自动生效到全应用

具体操作步骤

你的tsconfig.json中include配置本身是正确的，无需调整，仅需修改类型声明文件内容即可：

确认env.d.ts放置在项目根目录（与tsconfig.json同层级），若放在其他子目录需确保路径被include规则覆盖
重写env.d.ts内容，使用正确的全局声明语法：

// 全局挂载React类型，全应用TS/TSX文件无需手动导入即可使用React.*类型
import type React from 'react';

declare global {
  export { React };

  // 可在此处追加其他全局自定义类型，示例：
  // type GlobalBaseResponse<T = unknown> = { code: number; data: T; msg: string }
  // interface GlobalUserInfo { id: number; username: string; avatar: string }
}

（可选优化）如果希望省略React.前缀直接使用FC、MouseEvent等常用类型，可以在declare global块内追加别名：

declare global {
  export { React };
  type FC<P = Record<string, unknown>> = React.FC<P>;
  type MouseEvent<T = Element> = React.MouseEvent<T>;
  // 其他常用类型按相同方式追加即可
}

配置生效操作

写完配置后如果IDE仍提示需要导入React，执行以下操作即可：

重启TS语言服务：VS Code中使用快捷键Ctrl+Shift+P（Mac端为Cmd+Shift+P）调出命令面板，搜索并执行TypeScript: Restart TS Server
若仍未生效，检查是否手动修改过tsconfig.json中的typeRoots配置，无特殊需求不要手动覆盖该配置，使用NextJS默认生成的配置即可