Next.js项目转TSX后JSX代码报错但浏览器运行正常求排查解决

我之前也碰到过这种「代码标红但项目能跑」的情况，其实大多是TypeScript的配置、编辑器缓存或者类型依赖的问题，咱们一步步来排查解决：

1. 先检查tsconfig.json的关键配置 #

Next.js对TS的配置有特定要求，重点看这几个选项：

• jsx：必须设置为preserve（Next.js App Router默认）或者react-jsx（Pages Router常用），如果设成react可能会导致JSX类型提示异常。
• include：确保包含了你的TSX文件路径，比如["src/**/*", "pages/**/*", "app/**/*"]，别漏了你的组件目录。
• exclude：确认没有误排除掉需要检查的文件，比如不要把pages/或者app/目录加进去。
• lib：要包含dom和dom.iterable，否则TS识别不了浏览器环境的JSX元素。
• target：至少设为ES6，过低的版本会影响TS对JSX的解析。

2. 重启编辑器的TypeScript服务 #

编辑器（比如VS Code）的TS服务有时候会缓存旧的类型信息，导致错误提示不更新。你可以：

• 按下Ctrl+Shift+P（Windows）或Cmd+Shift+P（Mac）
• 输入TypeScript: Restart TS Server并执行
• 或者干脆关闭再重新打开编辑器，清一下缓存

3. 确认类型依赖安装完整并兼容 #

Next.js的TS项目需要对应的React类型包，版本不匹配也会出问题：

• 先检查package.json里有没有@types/react和@types/react-dom，如果没有就安装：

  npm install @types/react @types/react-dom --save-dev
  

• 确保这些类型包的版本和你项目里的React、Next.js版本兼容，比如Next.js 13+对应React 18，那@types/react也要装18.x的版本。

4. 补全组件的类型定义 #

有时候项目能运行是因为React对类型不严格，但TS会检测到类型缺失：

• 比如你写了一个组件但没定义props类型，TS会标红JSX部分，但React运行时不会报错。给组件加上类型就能解决：

  // 定义props类型
  type ButtonProps = {
    text: string;
    onClick?: () => void;
  };
  
  // 给组件传入类型
  const Button = ({ text, onClick }: ButtonProps) => {
    return <button onClick={onClick}>{text}</button>;
  };
  

• 也可能是你使用了未声明的变量或者类型，仔细看一下下划线提示的具体错误信息，针对性补全类型。

5. 检查Next.js和TypeScript的版本兼容性 #

不同版本的Next.js对TS版本有要求，比如Next.js 13需要TS 4.9以上，版本太低会导致解析异常：

• 查看package.json里的typescript版本，运行下面的命令升级到兼容的最新版：

  npm install typescript@latest --save-dev
  

6. 排查类型声明冲突 #

如果项目里有自定义的.d.ts文件，或者第三方库的类型有冲突，也会导致错误提示：

• 暂时把项目根目录下的自定义.d.ts文件移到别的地方，重启TS服务看错误是否消失
• 如果是第三方库的问题，可以尝试升级该库，或者在tsconfig.json里的types选项里调整类型加载顺序

按照上面的步骤排查，基本就能解决这种「标红但能跑」的问题啦！

内容的提问来源于stack exchange，提问作者Sarthak K