Next.js TypeScript项目中.tsx文件HTML标签报错（如h1未找到）

DevOps 小满

2026-7-17

解决Next.js TypeScript项目中.tsx文件HTML标签语法高亮报错问题

以下是几个实用的排查和解决步骤：

重启TypeScript语言服务：在VS Code中按下Ctrl+Shift+P（Windows）或Cmd+Shift+P（Mac），输入并执行TypeScript: Restart TS Server。很多时候服务进程卡住会导致语法校验异常。
校验tsconfig.json配置完整性：确保compilerOptions里的关键配置符合Next.js要求，尤其是：
```
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*", "app/**/*"], // 根据你的项目结构调整
  "exclude": ["node_modules"]
}
```
同时确认tsconfig.json位于项目根目录，且VS Code已识别到它——可以点击右下角的TypeScript版本标识，选择"Select TypeScript Version..."，再选"Use Workspace Version"绑定项目本地的tsconfig。
检查依赖版本兼容性：确保项目已安装正确版本的typescript、@types/react、@types/react-dom，且版本与你使用的Next.js版本匹配（比如Next.js 13+建议TypeScript 4.9及以上）。可以通过执行npm list typescript @types/react查看版本，不匹配的话重新安装对应版本。
确认JSX的使用场景：JSX只能出现在React组件函数的返回值中，或者被React.Fragment（或<></>）包裹的顶层结构里。避免在非组件的顶层作用域直接写HTML标签，比如：
```
// 错误示例
<h1>直接在顶层写JSX会报错</h1>

// 正确示例
export default function Home() {
  return <h1>Hello World</h1>;
}
```
排查VS Code插件冲突：暂时禁用除官方TypeScript and JavaScript Language Features之外的其他TS/React相关插件（比如旧版的React代码片段插件），重启VS Code后看报错是否消失。
清除VS Code缓存：关闭VS Code，删除项目根目录下的.vscode文件夹（如有），或者清除VS Code全局缓存（Windows：%APPDATA%\Code\Cache；Mac：~/Library/Caches/Code），重新打开项目后重新加载配置。