如何消除React中使用React.lazy时的ESLint Fast Refresh警告

问题背景 #

使用React.lazy实现组件懒加载时，触发ESLint警告：

ESLint: Fast refresh only works when a file only exports components. Move your component(s) to a separate file.(react-refresh/only-export-components)

懒加载功能正常运行，但需要消除该警告，使用的技术栈：

• react: ^18.2.0
• react-dom: ^18.2.0
• react-router-dom: ^6.14.2
• vite: ^4.4.0

问题原因 #

Vite默认集成的react-refresh插件对文件导出内容有严格要求：文件要么仅导出React组件（保证Fast Refresh热更新正常工作），要么是纯工具/逻辑文件（不含组件定义）。你的路由文件中，既通过React.lazy定义了组件，又导出了非组件类型的router对象，违反了插件规则，因此触发警告。

解决方案 #

方案1：抽离懒加载组件定义到单独文件

创建一个专门管理懒加载组件的文件（比如lazyComponents.ts），仅导出通过React.lazy生成的组件：

// src/lazyComponents.ts
import { lazy } from "react";

// 集中管理所有懒加载组件
export const ErrorPage = lazy(() => import("../pages/404/ErrorPage.tsx"));
// 其他懒加载组件可在此统一添加

然后在路由文件中导入这些组件：

// router file
import { createBrowserRouter } from "react-router-dom";
import IndexPage from "../pages/Index.tsx";
import { ErrorPage } from "./lazyComponents";

const router = createBrowserRouter([
    {
        element: <IndexPage/>,
        path: "/",
        children: [
            // ... 其他页面配置
            {
                path: "*",
                element: <ErrorPage/>
            }
        ]
    }
]);

export { router };

这种方式让路由文件仅导出router，懒加载组件文件仅导出组件，完全符合react-refresh的规则。

方案2：在路由文件中禁用该ESLint规则

如果不想抽离文件，可以直接在路由文件顶部添加注释临时禁用规则：

/* eslint-disable react-refresh/only-export-components */
import { createBrowserRouter } from "react-router-dom";
import { lazy } from "react";
import IndexPage from "../pages/Index.tsx";

const ErrorPage = lazy(() => import("../pages/404/ErrorPage.tsx"));

// ... 路由配置

也可以在ESLint全局配置中给路由文件添加规则例外：

// .eslintrc.js
module.exports = {
  // ... 其他配置
  overrides: [
    {
      files: ["src/path/to/your/router/file.tsx"], // 替换为你的路由文件实际路径
      rules: {
        "react-refresh/only-export-components": "off"
      }
    }
  ]
};

方案3：确认组件文件仅导出组件（非当前问题核心）

你的ErrorPage.tsx已经符合仅导出组件的要求，但可以再次确认：

// ErrorPage.tsx
import { FC } from "react";

const ErrorPage: FC = () => {
    return (
        <section className="error-page">
            <h1>Not found</h1>
        </section>
    );
};

export default ErrorPage;

该文件本身无问题，警告根源在路由文件的混合导出。

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