Next.js+TypeScript重启开发服务器后编译失败，免React导入失效问题排查

我正在开发一个基于Next.js和TypeScript的项目，之前开发服务器运行一切正常。修改next.config.js后重启（已撤销修改），服务器突然无法编译，终端抛出模块解析失败的错误，错误指向_app.tsx中的JSX语法。

安装@babel/preset-react后能恢复运行，但现在每个组件都必须手动添加import React from 'react';，而之前根本不需要这么做。想知道问题原因和解决方案。

配置文件 #

tsconfig.json（默认Next.js配置） #

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

.babelrc #

{
  "presets": ["@babel/preset-env", "@babel/preset-typescript"],
  "plugins": [
    "@babel/plugin-proposal-class-properties",
    "@babel/plugin-proposal-object-rest-spread",
    [
      "module-resolver",
      {
        "alias": {
          "@": "./src"
        }
      }
    ]
  ]
}

终端错误信息 #

ready - started server on 0.0.0.0:3000, url: http://localhost:3000
info  - Loaded env from /my/file/path/.env
info  - Disabled SWC as replacement for Babel because of custom Babel configuration ".babelrc" https://nextjs.org/docs/messages/swc-disabled
info  - Using external babel configuration from /my/file/path/.babelrc
error - ./src/pages/_app.tsx
Module parse failed: Unexpected token (5:9)
|   var Component = _ref.Component,
|       pageProps = _ref.pageProps;
>   return <Component {...pageProps} />;
| }
| _c = App;

原因分析 #

1. JSX解析失败：自定义.babelrc中缺少@babel/preset-react，Next.js默认会用SWC或内置Babel配置处理JSX，但存在自定义Babel配置时，Next.js会禁用SWC并完全使用你的配置，导致JSX语法无法被解析。
2. 需手动引入React：React 17+和Next.js默认配置支持自动引入React（无需手动写import React from 'react'），但@babel/preset-react默认未开启该功能，需手动配置runtime: 'automatic'。

解决方案 #

方案1：修复自定义Babel配置 #

修改.babelrc，添加@babel/preset-react并开启自动引入：

{
  "presets": [
    "@babel/preset-env",
    "@babel/preset-typescript",
    ["@babel/preset-react", { "runtime": "automatic" }]
  ],
  "plugins": [
    "@babel/plugin-proposal-class-properties",
    "@babel/plugin-proposal-object-rest-spread",
    [
      "module-resolver",
      {
        "alias": {
          "@": "./src"
        }
      }
    ]
  ]
}

方案2：移除自定义Babel配置（推荐） #

如果自定义Babel配置仅用于路径别名，Next.js可通过tsconfig.json的paths配置实现，无需额外Babel插件。直接删除.babelrc，Next.js会恢复使用默认的SWC或内置Babel配置，自动处理JSX和React引入。

验证步骤

1. 保存修改后的配置文件（或删除.babelrc）
2. 删除node_modules和.next文件夹
3. 重新运行npm install和npm run dev

内容的提问来源于stack exchange，提问作者713sean