Next.js自动重置tsconfig.json的jsx选项引发VS Code React导入警告

问题描述 #

开发Next.js-TypeScript项目时，突然出现VS Code警告：所有使用React Fragment（<>）的.tsx文件必须添加import React from "react"语句。尝试将tsconfig.json中的"jsx":"preserve"改为"jsx":"react-jsx"后警告消失，但启动或重启本地服务时，Next.js会自动将该选项重置回preserve，终端提示"已重新配置tsconfig.json"。

项目依赖配置 #

"dependencies": {
  "@reduxjs/toolkit": "^2.2.7",
  "bcryptjs": "^2.4.3",
  "mongoose": "^8.7.0",
  "next": "^14.2.13",
  "next-auth": "^5.0.0-beta.20",
  "react": "^18.3.1",
  "react-dom": "^18.3.1",
  "react-hook-form": "^7.53.0",
  "react-icons": "^5.3.0",
  "react-player": "^2.16.0",
  "react-redux": "^9.1.2",
  "react-simple-star-rating": "^5.1.7",
  "react-toastify": "^10.0.5",
  "redux-persist": "^6.0.0",
  "sass": "^1.79.4"
},
"devDependencies": {
  "@tailwindcss/aspect-ratio": "^0.4.2",
  "@types/bcryptjs": "^2.4.6",
  "@types/node": "^20.16.10",
  "@types/react": "^18.3.10",
  "@types/react-dom": "^18",
  "@types/redux-persist": "^4.0.0",
  "daisyui": "^4.12.10",
  "eslint": "^8",
  "eslint-config-next": "^14.2.13",
  "postcss": "^8.4.47",
  "tailwindcss": "^3.4.13",
  "typescript": "^5.6.2"
}

当前tsconfig.json配置 #

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

注：该问题仅出现在TypeScript项目中

原因分析 #

Next.js 13+（含14.x版本）的App Router模式下，强制使用jsx: "preserve"配置——因为Next.js会自行处理JSX转译，适配服务器组件与客户端组件的编译逻辑，手动修改该选项会被Next.js的自动配置系统覆盖。而VS Code的TypeScript语言服务可能因缓存、版本不匹配或类型识别问题，错误要求导入React以使用Fragment。

解决方案 #

1. 重启TypeScript语言服务 #

打开VS Code命令面板（快捷键：Ctrl+Shift+P / Cmd+Shift+P），执行TypeScript: Restart TS Server，清除服务缓存后重新分析项目，多数情况下可直接消除警告。

2. 切换到项目本地TypeScript版本 #

• 打开任意.tsx文件，查看VS Code右下角状态栏的TypeScript版本号
• 点击版本号，选择Use Workspace Version（对应项目node_modules/typescript下的5.6.2版本），避免全局TS版本与项目依赖不匹配导致的识别偏差。

3. 确保Next.js类型文件被正确加载 #

确认tsconfig.json的include数组已包含.next/types/**/*.ts（你的配置已满足），该路径是Next.js自动生成的类型文件，用于让TS识别App Router的JSX处理规则。

4. 添加类型声明文件（可选） #

若上述方法无效，在项目根目录创建types/react.d.ts文件，添加以下内容强制TS识别全局Fragment：

import * as React from 'react';

declare global {
  namespace JSX {
    interface IntrinsicElements {
      Fragment: React.FragmentProps;
    }
  }
}

5. 检查ESLint配置 #

确保.eslintrc.json的extends包含Next.js官方规则，避免ESLint与TS服务的规则冲突：

{
  "extends": ["next/core-web-vitals", "next/typescript"]
}

内容的提问来源于stack exchange，提问作者Md. Ta-Seen Fuad Jeem